Let's talk some more about Packages in Designer 4 - Part 6

Novell Identity Manager initially came with a Console One plugin to manage policies and stylesheets, back when it was still called DirXML. Then as the product matured and DirXML Script became available we got iManager with plugins to manage it.

When Designer for Identity Manager was released, it really was a game changing paradigm shift for Novell's product. Being able to take a project offline, work on it, come back, push out (and double check) your changes made how we work on IDM projects totally different. Documentation generation did not hurt either!

Each release of Designer has added new features and functionality. I recently worked through a series on what is new in Identity Manager 4 Advanced Edition (and compared it to what was introduced with IDM 3.5 and 3.6 releases), which you can read here:

Of course most of those features discussed included support for managing them in Designer. In fact, the series on what has changed is more focused on what has changed in Designer. But that was a high level overview and so much more has changed down low in weeds it is going to take a fair bit of work to get through them all.

With Identity Manager 4 Advanced Edition there are some major engine and Designer changes that are yet another example of a paradigm shift, and it can be summed up in one word, Packages. I started talking about Packages in these articles:

There is so much to say about packages, that I wanted to continue on to some more of the interesting features. I realized after I finished the last article that this would really just be a series regurgitating the documentation, so I actually went and checked the documentation to see how much is there. That is when I realized there is almost nothing about building packages in the docs. There is a single long page with almost no useful details in it, so hopefully this series will be a good resource for others. If you see some details in a documentation page missing please be sure to use the Submit Comment button, as there really is a person at the other end of that link. (A busy person usually, but they do often respond).

In the first article Let's talk some more about Packages in Designer 4 - Part 1 I talked about versioning, base packages, building prompts, interesting linkages, GCV and filter extensions.

In the second article Let's talk some more about Packages in Designer 4 - Part 2 I talked about more details in the nitty gritty about packages like localization, dependencies and ordering, and finally about the package catalog and what is stored there.

In the third article Let's talk some more about Packages in Designer 4 - Part 3 I discussed how the process of adding a driver changes with the new package model.

In the fourth article Let's talk some more about Packages in Designer 4 - Part 4 I discussed options about building packages and some of the states that a package might go through in terms of usage, and in terms of recommended development paths.

In the fifth article Let's talk some more about Packages in Designer 4 - Part 5 I started looking at the various resource types that can be part of a package, and how they differ from their standard representation in a driver which would include the various new features added to support the package infrastructure. I was able to cover Global Configuration objects and Filter extensions.

In this article I would like to continue with objects that we can use in Packages.

The usual suspects are available, Policies and XSLT, as well as newer object types for the various Resource objects, like Mapping Tables, even Custom objects.

I ran into this as I was looking at two of the new drivers that come with IDM 4 the Managed System Gateway Driver and Data Collection Service driver. I am still trying to fully understand what each does for us in IDM 4. Anyway, I was looking through those for interesting tidbits to glean, and noticed that there is a Resource object in the Data Collection Service driver called, NOVLDCSERROR-TurnOffLoopBackDetection.

First off a couple of items about naming. When you build a Package you have to give it a short name, and Novell wants them to be both descriptive and unique, Yet there is no registry. However, since they are the only ones building packages at the moment it is not an issue, but I imagine it will be. The good news is, if someone builds a conflicting package then you just edit one of them, version it and go.

Anyway, the naming model for objects is now the SHORTNAME-pub-etp-EventTransform model, where the pub-etp-EventTransform was started in the late 3.5.1, early 3.6.1, Compliance Management Platform era. This notion is something like, three letter channel (pub or sub), then a two letter code for the Policy Set (et = event transform, c = Create, m = Match, p = Placement, cm = Command, it = Input Transform, ot = Output Transform). Then a single letter p or s for policy or style sheet, and then some kind of descriptive name for what it is doing.

Really this came about because with Library objects you could now have objects floating around, linked to a driver, but not stored in a location that provides info. Therefore a better naming model was needed. Anyway, with packages they prepended the sub-etp-EventTransform naming model with the name of the package. On the one hand this is good since it makes it easier to recognize the source (Package name), channel (the sub part), the policy set (etp, ctp, etc), whether it is Policy or Stylesheet (its-Transform for example) and some notion of what its purpose is like TurnOffLoopBackDetection in the example above. On the other hand the naming is getting really dense. I suppose I will get used to it as I see the package names more. Correlating between the nice Package Name in the catalog and the short package name in the policy naming will take some getting used too. Might be nice to be able to have a better link for trying to find it.

Actually that would be quite nice. Currently via properties of a Policy object you can see the References to it. That is where this object is linked into a driver. I was helping a client document their IDM project (30 drivers, lots of policy, and some very old, some poorly understood) and one thing I noticed was they had the same matching rule linked into both the Subscriber and Publisher channel on two different drivers. Very odd choice. Now as it happens it was cleverly written so that it worked that way, but dangerous as if you did not know that it was cross linked like that you could make a change that might break all sorts of things.

Anyway, I noticed in the NOVLDCSERROR-TurnOffLoopBackDetection resource object that it was of type Custom,

which is one of the many types of Prompts resource objects that can exist. We looked at a Global Configuration Variable approach in a previous article. Anyway, this one looked interesting, since it was doing something rather esoteric, based on the name, turning off loopback protection in a driver. Now this is interesting because this is not a driver configuration setting, nor a global configuration setting, rather it is an Engine Control Value (ECV) setting. So far I had not seen anything in packages to manipulate this. When I looked at the GCV prompt, I discussed that there are two items I did not fully understand yet, the Prompt Transformation and Target Transformation. The good news is they are named well, and I have an inkling of their purpose from their names, however I do not really understand how they work. Looking at some examples you see there is XSLT (XML Stylesheet Transform language) in those settings, but the examples I had found did not do anything.

This particular resource does do something, and it is simple, and a nice example. So we can guess from the names that the Prompt Transformation is to allow you to use XSLT to modify the prompts that show up. The second page on the Prompt page (as the screen shot shows is Prompts, and this takes the usual Configuration DTD XML. That is, everything you can do in a GCV, you can do in there. You can read more about the many GCV types in the articles:

This same XML DTD is used in the Driver Configuration tabs as well, just there is no UI to generate it, you have to either write the XML by hand, or else write it in the GCV fields, and copy and paste the XML in, which is what I usually do when needed.

Thus it makes sense to me (and I do not know if I am correct) that the Prompt Transform takes the OUTPUT of the Prompts (after you click Next) and transforms it. After all, the input is pretty flexible, and has a defined DTD and UI, so would not make a lot of sense to transform it before showing it.

But what does the Target Transformation do? Well this is an example that shows a simple use. Here is the XSLT:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
Turn Off Look-Back Detection - Target Style Sheet

Turn off look-back detection by setting the Engine Control Value 'dirxml.engine.allow-event-loopback' to 'true'.

Updated: 20100901
<!-- Turn off look-back detection -->
<xsl:template match="definition[@name='dirxml.engine.allow-event-loopback']/value/text()">
<!-- identity transformation template -->
<xsl:template match="node()|@*">
<xsl:apply-templates select="@*|node()"/>

There is a nice comment (Thank you! I love commentary in code! It is critical to understanding what is going on, the more the merrier) that explains they are trying to modify the specific Engine Control Value.

Then it tries to find something via an XPATH expression of definition[@name='dirxml.engine.allow-event-loopback']/value/text() which means:

The <definition> node, whose XML attribute name is dirxml.engine.allow-event-loopback, then look at the <value> nodes text string.

The ECV XML looks like GCV and Driver Configuration XML, and would look something like:

<definition critical-change="true" display-name="dirxml.engine.allow-event-loopback" name="dirxml.engine.allow-event-loopback" type="boolean">

Thus you can see how the XPATH selects it. Anyway, this XSLT will then set the value to of the text to true. Then comes the well known Identity Transformation Template that every XSLT sheet in IDM has (usually, I am sure there are examples where it would not but I cannot think of one).

<xsl:template match="node()|@*">
<xsl:apply-templates select="@*|node()"/>

This just basically copies everything in the current document through. XSLT works by applying a stylesheet to an XML document. If you do not use the Identity transform template, then only what you specify explicitly gets copied through, everything else would be dropped. The Identity Transform copies everything else through. This way if you did nothing, nothing happens, the input and output document would be the same.

What I do not understand is, what is the Target document? In other words, how does this XSLT know to specifically target the ECV settings? Is it the entire sum of the driver configuration being built up in memory from all the components of the package? That is, before Designer and iManager would import a monolithic XML file that had a bunch of 'stuff' in it. As much or as little as you wanted. You could have an import with a single rule or an entire driver or an entire set of drivers. (For staging at a client, we once exported all the drivers, stripped out the password prompting XML, search and replaced host names, removed rules we knew did not change, and just reimported the whole kit and kaboodle on top of the existing system. But that was 30 drivers where doing it most any other way would have been really hard).

What I need to find out is how the Package model works. My guess based on what I have seen so far is it effectively takes each package, summarizes the results, and builds the equivalent of the monolithic driver configurations of the past in memory, before finally importing it. If so, then the target would seem likely to be the summarized configuration at the moment in time when the XSLT is run. That would make the ordering of this Package important that it be linked after the package that sets up the ECV values or else it will not work. I initially spent time looking to figure out how the targeting might work, but I think this idea is the most likely one I can come up with. I will try and track down more information from Novell to see. The documentation on Designer 4 and packages is pretty light at the moment, alas.


How To-Best Practice
Comment List