Talking about the DirXML-Policies attributes


Update: They got the images back!  Yippee!

In a series of articles I talked about the various attributes that are available on the DirXML-Driver object in Novell's Identity Manager product. (Or is it NetIQ Identity Manager now. Who knows?

Whatever its called, still IDM), you can find them at this series of links:

In the first article of that series, I discussed the attribute DirXML-Policies. Which is quite the interesting attribute. As I mentioned there, it is new with Identity Manager 3.5, where the policy linkage model was changed (for the better!).

Quickly, in the past, each policy set in the fishbone diagram (Event Transform, Create, Match, Placement, Command, Input and Output) had its own attribute that referenced (via a DN reference attribute) the first rule in the chain. Then each policy object had a DirXML-NextTransformation attribute which pointed at the next policy in line. This worked initially and was probably easy to manage.

With IDM 3.5 a whole bunch of new features were added that needed this to change. Thus the old approach of an attribute per policy set and then linking to the next rule was deprecated and instead the DirXML-Policies attribute was added.

This is a multivalued attribute, that is of an interesting syntax called Typed Name. You can read more about the various eDirectory schema syntaxes in this series of articles:

There is a funny story about those articles. I was actually taking a training course on Microsoft's Forefront Identity Manager (FIM, at various times called MIIS, ILM, ILM2, etc) and in discussing some concepts I got to thinking about the various eDirectory schema syntaxes, since they are so interesting and started writing this series. I managed to write it all while taking notes on the training sessions. (There were a lot of really dumb questions asked).

When I look back at it, I see that for Typed Name I defined what it is, but did not know of any uses for it. Well DirXML-Policies is one such instance. It is useful when you want a DN reference component, and then a couple of integers. Since they are 32 bit integers they are perfect for holding timestamps in CTIME format (Count of seconds since the very beginning of 1970, and alas, runs out of values around 2037. Lovely a Y2K37 issues is coming down the pike).

Additionally I know of DirXML-SPPriority which is an attribute of DirXML-SharedProfileSet that uses this syntax. I am not entirely sure what that object class is used for but I think it is where the Entitlements Service driver (Role Based Entitlements, the precursor to RBPM (Roles Based Provisioning Module) and Workflow for granting entitlements) stores the policies. You would see this show up in Designer in the Entitlements Policies container, under the driver set. Like many things in Designer this is something of an unexpected abstraction, as opening any of the subordinate objects in an editor actually opens an editor that shows all the subordinates in one view. Kind of like how in the Provisioning view, the object classes in the DAL (Directory Abstraction Layer) look like subordinates, but are really shown in a single editor for the DAL.

Regardless, this is actually a really useful syntax when you need to use it. We have used it for monitoring drivers. The DN holds the driver reference, and then using the two 32 bit integers store two time stamps. One for the last time we successfully read from the driver, and the other from when we last successfully wrote to the driver. This was we can tell if we have both channels running. If there is a discrepancy in time greater than some threshold (say 10 minutes) then we know that although the driver is up, it is not communicating. Perhaps the remote loader is down or something is wrong on the application side.

In that case, the integers used are quite high, since CTIME as the count of seconds since 1970 is now coming close to the two billion second mark. Where as in the DirXML-Policies case, the numbers are quite low. Not that it really matters from a raw data perspective, but it looks very different.

Rather than in the past where some of the attributes were on the driver object (for Schema Map, Input and Output transforms), some on the Subscriber and Publisher channels (Event, Create, Match, Placement, Command), now DirXML-Policies is the only attribute and it is stored on the driver object.

It has many values, as many as you have policies. Each policies, ECMA, GCV object (as of IDM 4) gets an entry. The linkage order is stored by identifying the Policy Set for the policy using an integer, and then a position within that Policy Set. This worked better before ECMA objects and GCVs as they are technically not Policy Sets, but you get the idea.

Since I have not seen it written down anywhere, I went through, populated a driver with everything I could think of and figured out what each value represents.

Policy ordering in DirXML-Policies:

0 Schema Map
1 Input Transform
2 Output Transform
3 ECMA Script Object
4 Sub Event Transform
5 Pub Event Transform
6 Sub Match
7 Pub Match
8 Sub Create
9 Pub Create
10 Sub Command Transform
11 Pub Command Transform
12 Sub Placement
13 Pub Placement
14 GCV Objects
15 Startup (New in IDM
16 Shutdown (New in IDM

You can see from the table that each step in the fishbone diagram,

Click to view.

is covered, and two that do not show up in it since they are sort of outside the policy flow, that is ECMA and GCV objects. With the IDM release, two new policy sets showed up, Startup and Shutdown, but they do not appear in the regular fishbone diagram. Take a look at this article to see a discussion of these new policy sets.

ECMA Objects were introduced right around the same time as DirXML-Policies in Identity Manager 3.5. These are really just simple objects that hold ECMA Script functions as text strings. These are great, as you can easily call out to ECMA when needed, anywhere in IDM policy, using an XPATH token (verb in Argument Builder, or in a condition test of If XPATH true/not true) by referring to a namespace es: and then the function name (and of course any parameters it needs).

You can read about useful ECMA Scripts in this article I wrote a while back and maintain, and as always if you have any useful ideas, submit it as a comment and I will update the article: Open Call for useful ECMA functions to use in Identity Manager

Perhaps one of the most interesting functions discussed in that article is an LDAP implementation in ECMA. I got that from Lothar Haeger, who used it in his excellent Password Notifier Driver:

Lothar used it to add functionality that IDM is missing in its Query token. The Query token cannot look at a timestamp field and return only those who are say, greater than or less than a value. For dates and times this is really useful. Wouldn't it be great to say, get me all objects with a timestamp attribute less than right now. (I.e. Things that have come due). Well Query cannot do it, but LDAP filters do support it. (Or more correctly the NLDAP service in eDirectory supports it, since the LDAP standard requires it).

This turns out to be so useful, that if you look in Identity Manager 4.0, you will see a Package in the Common, ECMAScript containers, there is an LDAP Library that includes this functionality. (The Package includes a GCV object that holds the connection information. Lothar was way cooler than that, and figured out a way to configure LDAP without specifying user names or passwords. You can read my description of how he does that in this article: An even easier way to call a Job from policy )

There is also an Advanced Java Class package in the Common, ECMAScript that contains a really neat ECMA object with close to 100 ECMA functions that were originally written in Java for (or by) Novell Consulting to use in engagements. Once ECMA became available they tasked Shon Vella to port it to ECMA. This way you include an object in eDirectory (that Designer can push) instead of requiring maintaining a Java class in the file system. Now it is available to all of us to use. Some are useless, like many of the date conversion functions, since the Convert Time function is significantly better than the ECMA version. Others are great, like the GUID converters, and there are many more.

Looking in Designer, on the properties of a driver, there is a side tab, with an option Driver Configuration. Once you select that tab, there is an ECMA Script tab along the top. This is where you select ECMA objects to link into this driver. The driver needs to be told that there is an ECMA object to read at load time, or else the functions are not available to be used. In iManager, this is in the Advanced tab, along side Jobs and Mapping tables. The image below shows you what that would look like in Designer.

Next up are GCV objects that were added in Identity Manager 4, to allow a Package to deliver a set of GCV's as a standalone object (and thus can belong to a Package with all the benefits that ensue). These are linked in much like the ECMA objects are linked in, in Designer. You can see that tab in the attached image:

There is still support for GCV's on the driver object itself, as it is needed for backwards compatibility, and those get shown as having the driver name in the normal GCV tab of the driver configuration.

What is new, is that there will be a series of tabs across the top of the GCV tab in Properties of the driver, one tab per GCV object linked in. Thus you can tell where the specific GCV you are working with came from. Alas, the iManager snapins support the tabs showing the various GCV's but since complete Package support was not officially ported to iManager one thing missing is the ability to link or change the linkage of GCV objects on the driver.

You can see this tab view in Designer in the picture below:

Now, when you change one of the linkages in Designer, it turns out there is an abstraction (I suppose for backwards compatibility in some ways), and compare the changes, what you see denoted as different is not exactly reflected in attributes.

For example, GCV's show up as DirXML-GlobalConfig with a list of GCV objects in the list. However, if you look, there is no such attribute on the Driver nor Driver set object. So what on earth is Designer looking at, comparing, and then changing? Well figuring this out is what triggered my writing this article. In fact, it is editing the DirXML-Policies object, looking for things with the position of 14. It reads them back, then the second integer is the order within the GCV's to determine how the GCV's should be linked.

Initially this threw me for a while, till I figured it out, since I could not make the change I needed in iManager, and for a variety of reasons I had no intention of Deploying the driver to change it in Designer.

In fact this is true of all the policy linkages, when you make a change in Designer, the compare will show the difference as being in a the old pre-IDM 3.5 attribute name. (DirXML-EventTransform, DirXML-CommandTransform, and so on). I had noticed this, but not thought much about it.

The other thing you will notice is that you cannot update just that one attribute to push the linkage changes. You need to update at the Driver object level (or perhaps the channel, Publisher or Subscriber level). This limitation of Compare now makes sense in light of the fact that Designer is showing the change in a simple to understand view, based on the policy model attributes (that are not really used anymore) because they are much easier to visualize than just showing the raw attribute data.

After all, how many people have memorized the above table of the numeric representations of policy sets?

But since this is really an abstraction of a single attribute, with many many values, it makes sense that the changes need to be deployed as part of the object that holds it (the Driver object) as opposed to the sort of pseudo attributes shown in the compare summary.

Thus since iManager does not support manipulating the GCV linkage in a pretty fashion, I was able to edit the DirXML-Policies attribute as a raw attribute in either ConsoleOne or LDAP and make the changes that I needed. You need the DN of the object, the policy set number, and then its order (starting at 0) in the policy chain.

I hope this is helpful to someone, I know it answered a lot of questions I had and explained some things I had wondered about, but never deeply investigated.


How To-Best Practice
Comment List