Understanding Package versioning - Part 1

Understanding Package versioning - Part 1

If you are using Identity Manager version 4.0x and higher you will know about Packages. I love packages, as might be evident by how much I have written about them.

They have their benefits and strengths but it is also important to recognize their weaknesses. They make some things much easier but some things just get more complicated it seems.

Strength wise, the ability to version a set of thingies that make up changes to a driver is very useful. I.e. I can now bundle (or perhaps 'Package'?) up some policy changes, a filter change, a PRD, a Resource, and maybe a Job and deliver it to a client in a JAR file that they can import and apply to a driver with fairly good confidence it will apply the changes properly.

Then I can make a new version when they report a bug and they can upgrade or downgrade. Even better, when they swear they made no changes and it used to work, we can run in Factory mode, and test again, and in fact, show all the changes they might have made in detail. This part is amazing and great.

However all is not perfect, as is usually the case. The way that Filter changes are managed is annoying as heck. You MUST use the Filter Resource objects and if you ever change the filter by hand, or import the changes from the vault to Designer you break the checksum and then it is very hard to get the Packaged changes back to working again.

There is no way to package Schema with a package which would be nice. (I personally deliver schema using a DirXML-Resource of DirXML-ContentType of xml/text and paste in the SCH file content of the schema update.).

The whole Package Prompts model is needlessly complex and very hard to troubleshoot so I mostly skip it as I have heard a lot of people are doing. If you need to deliver new GCV's content and values, it makes more sense sometimes to copy the GCV values, then remove the package and re-add it to get the proper GCVs then reapply the customizations.

However I want to talk about a particularly frustrating aspect of Packages, namely Versioning.

On the one hand, this is a great strength of Packages. I can make a version with a GUID (should be unique since the original is generated randomly when the Package is first created) and a version number that should make it all uniquely and globally distinguishable.

Now for the issues. There was a break in compatibility around Designer 4.0 and 4.01, where the format of the version went from:

IDM 4.0 format: 1.0.7
IDM 4.01+ format:

That is the version string format now includes a date stamp, which is great, since it has seconds resolution so you should never be able to collide two versions with the same timestamp.

So far so good, right? But here is the root cause of the following issue. When you build a package it generates a date stamp as of the moment you started the process. When you deploy this package, you will get the DirXML-pkgGUID added with a value something like this (Taken from the 2.1.0 version of the SOAP base package):

DBLGVLV4_201006221048420840;com.novellinc.novlsoapbase;;SOAP Base;NOVLSOAPBASE

To dissect that semi-colon separated string it consists of these parts:

	DBLGVLV4_201006221048420840;	A GUID
com.novellinc.novlsoapbase; The JAR class name; Version string
SOAP Base; Long name of the package
NOVLSOAPBASE Short name of the package

The Short name does need to be unique, and is limited to 11 or 13 characters, an odd number I never understood the basis for the limit. I have never tried forcing a collision but I assume bad things happen.

I think that Designer actually finds your package by the JAR class name, most of the time, instead of anything else. That is, it loads all the packages into the Java heap as classes, and calls each one as needed. It is interesting that the class name is derived on the fly and you cannot quite directly control it. The values for packages I make are generally: com.computerintegratedservicesllc.cis-val-man

It obviously takes the Vendor company name, lower cases it all, drops special characters and munges it all together. Now if it happened I had a class hierarchy I wanted to force it into, I do not think I have the option, other than controlling the node after the "com" via the Vendor company name.

If you want to see the GUID of the package, click on the Package in the Outline view, from the Package Catalog and then in the bottom left (default Designer config. If you moved the windows around, all bets are off) titled Properties and the GUID is available there.

The only time you as a Package developer would want to know the GUID specifically to use, would be if you are building a base package and you wanted to have an option to require or optionally add packages as part of the base package. You could use a dependency where this package requires that package and Designer will resolve that for you. However if you have looked at the SOAP Base package, you will see that you get to choose between the SPML, DSML or Other configuration. This is done in the Properties of the Packages only available in the Base Package, called Configuration Wizard.

Using the example of the SOAP Base shim, it looks like this:
&ltr;?xml version="1.0" encoding="UTF-8"?&gtr;&ltr;features&gtr;
&ltr;or display-name="Connected System" expanded="true"&gtr;
&ltr;package id="T084BQAT_201006221631390503" name="DSML 2.0" selected="false"/&gtr;
&ltr;package id="1EYAB8FO_201006221633290761" name="SPML 1.0" selected="false"/&gtr;
&ltr;package id="WO6LKGEP_201006221635120432" name="SPML 2.0" selected="false"/&gtr;
&ltr;or display-name="Other"/&gtr;
&ltr;package id="YJ6BS5DL_201006240958340214" name="SOAP Password Synchronization" selected="false"/&gtr;
&ltr;package id="ONU7T00W_201006241220580327" name="SOAP Managed System Information" selected="false"/&gtr;
&ltr;package id="P75RTTR4_201312182332250287" name="Permission Collection and Reconciliation Service" selected="false"/&gtr;

That generates this screen.

This allows you to offer configurations for your base package. In some ways the JDBC driver used to do this, before they forked it into individual base packages. To me, the most interesting part of this example is how they used the "Other" option, which is available in the 2.2.0 and lower versions. In 2.3.0 they removed it, which I think is a mistake. At my company we use the SOAP shim with add on packages to do all sorts of interesting SOAP drivers, and we always select Other in that case. Yes of course I could make my own base package, but I want to pick up new features NetIQ releases as they fix issues and add new features and not be responsible for noticing and updating my own base package.

The Mandatories show up on the first page (screen shot above) and there is a second page for the optional components. You can see that you can default the selections, so that your recommendations are followed. In the case of my SOAP driver example, I would have a parent package I would offer via the Optional or Mandatory and allow the GUI specified Dependencies to drive the linked packages it would need. I.e. I do not think you can implement anything more complex than the current simple model. Though the way they implemented the "Other" option suggests that nesting might work at least a little bit.

Here you need to address the package by its 'id' which is its GUID. Now the GUID is generated when you first create the package and has the date stamp of the first time you created it in Designer.

But if we go back to the DirXML-PkgGUID there is a version with a date stamp and this is the area from which our issues originate.

When you start with a fresh Designer project and import from the Identity Vault, it reads all the DirXML-PkgGUID values that every object has and tries to find a Package version in your Designer that matches. Notice I said in your Designer, not in your Catalog. As of some update a few years ago, you no longer had to import every Package into your Catalog for this to work, instead all the Packages installed in Designer, via Check for Package Updates. What is important here as well is that if you imported a Package into a project in your workspace, then it won't be found unless it is in THIS projects catalog.

The GUID is used to find the specific package 'family' since all versions of the package will share the same GUID. This is what the Request Package Ownership in Designer used to accomplish. It searches the workspace for all packages with the same GUID and looks for the flag "Imported" of false. At which point you can then make new versions of this package as your project clearly 'owns' it, since it was not imported. How else could it get in, except being created. There is a Designer add on that will change that flag for you, so you can make new versions if you lose your project that owns the package. Of course a file system backup (ZIP export) of your project can be used to resurrect the ownership as well. I think (Never confirmed this one) that if you export a project that owns a package, then import it into a second workspace, then you could use Request Package Ownership and succeed. I think the Imported flag would stay static in that case, as false. If anyone has tried this, please leave a comment.

Ok, so you import from IDV and Designer finds a dozen packages involved, based on the GUIDs. Then it searches through the known packages installed and looks for the specific package version. This has a version 2.2.0 and a date stamp and it has to be the exact match. I.e. Having two 2.2.0 versions with different date stamps won't count or work.

So far this all works well actually. What is the issue? How do we get to orphaned versions? When you are developing a package you start and create the new package entirely which generates the GUID as well or else you make a new version of an existing package, both actions set the timestamp part of the version string as "NOW". You know, I have no idea if the timestamp is local time or UTC, not that it really matters, but as I thought about it, I do not know. I had to go check, and the answer is, local time zone, not UTC. I suppose it does not really matter, but interesting to know.

However, once you are done and want to promote the package for use in Production or some other environment you want to Build it. Here lies the problem. Guess what happens to the version date stamp when you build it? It resets to "NOW" again.

The old version is now lost, and I always thought you cannot get it back. There is an odd little tab next to the version when you make a new version, sort of looks like Kilroy sticking his tongue out. But it only shows you the existing date stamp versions. Selecting one from the list does nothing as you still get the current time as the date stamp. There seems to be no way to specify a specific timestamp.

As I was writing this I was supremely confident that the version was lost and there was no real way to get it back. But I started writing an explanation of how there were checksums in packages that would prevent editing the contents, and being the consistent and diligent person you all love and adore (Or if you are Aaron, barely tolerate) I went to go find an example to show how the checksum would block it.

But what I found out was that my supreme confidence was misplaced! Just for making me realize my own fallibility I am now going to make you all wait for the next article to find out the answer! Muahahaha! But there does seem to be a way to fix this! Colour me shocked!


Some content on Community Tips & Information pages is not officially supported by Micro Focus. Please refer to our Terms of Use for more detail.
Top Contributors
Version history
Revision #:
1 of 1
Last update:
‎2018-01-03 17:08
Updated by:
The opinions expressed above are the personal opinions of the authors, not of Micro Focus. By using this site, you accept the Terms of Use and Rules of Participation. Certain versions of content ("Material") accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company. As of September 1, 2017, the Material is now offered by Micro Focus, a separately owned and operated company. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.