Open Call for IDM Move Event Documents
Novell Identity Manager can connect a large number of different systems together. The driver shims for each connected system were sometimes developed by different groups, and at accelerant times.
Usually this does not much matter, as there is a common XDS XML dialect that they all convert events into, a common API to perform actual commands with, and other common libraries to share code.
However, every so often you find some unique bits that are driver shim specific.
For example, in Active Directory, when you delete an object, the delete event node in the XDS document, does not include the object class. Thus testing to veto Delete events, for Users, will not actually work, since the event may be a delete event, but there is no class-name="User" in the <delete> node. Thus adding the condition class is equal to User will never match and thus your rule will never fire. You also cannot tell from the source DN since you will see the tombstone object as the deleted object DN, which is not helpful, nor related to where the original object was found.
I discussed this in the article:
More about the Veto Command for Scoping Events
In the case of Active Directory, the Association value still points to the original Active Directory objects GUID, and there is still an object in eDirectory with that association value. Therefore it is possible to use the Resolve token (new in Identity Manager 3.5 and higher) that will convert the <delete> nodes association to a DN in eDirectory. Then you could test the object class of the associated object and decide if it is a User, a Group, or an Organizational Unit, and do with the event as you please. Hmm, that sounds like an idea for a follow up to that article with some code samples. Ah well, on a rainy day... Add it to my list of possible articles. I sort of already wrote the example in the next article quoted below.
Similarly, the Lotus Notes Domino driver has a similar issue with deletes, requiring additional care when writing rules to handle delete events for an object. Scoping Delete Events in the Lotus Notes Driver for IDM
You can see that unlike in Active Directory, when deleting an object, where there is no Object class value in the document, for events coming on the Publisher channel from Lotus Notes, the object class is available, but it is actually set to Unknown. Which is just as useless as no object class being included.
I should probably compile a list of delete events coming out of the various driver shims and start an open call for that as well. That could be useful for exactly the same set of reasons.
But todays topic is <move> events. Like deletes, some systems have little tweaks and peculiarities on move events, that make using a single rule to handle all of them, basically not realistic. There is a nice desire to use common rules across all drivers, stored in a Library (new feature in Identity Manager 3.5 and higher as well. If you are still running IDM 3.01, upgrade please!! 3.5, 3.51. 3.6, and 3.61 are so much better and easier to use) so that you can reuse them again and again.
Libraries are kind of cool, because you can store stuff in them, and reference them from any driver in the Driver set. I was about to say tree, but I wonder about that. Libraries are objects in the directory. Can you reference a Library from different driversets? I wonder.
However, until you see a move event on the drivers Publisher channel, and look at it closely, it is hard to know exactly what you need to do to pick the event apart and react to it.
Thus this open call. Please email me Geoffrey Carman at email@example.com post a comment, send me a message through Cool Solutions, or whatever you like, with samples of move events from whatever driver you are working with. This is the same idea that worked so well in the article Open Call - IDM Association Values for eDirectory Objects about Identity Manager driver Association values. I would like to do this for as many different things about IDM as makes sense!
If you run into some other kind of thing that is common across all drivers, but slightly different in each case, and have one or two samples, please start your own open call! The more we can get contributed the easier it is for the next guy (or gal) who needs to know the subtleties to find the information.
I will edit the article and keep adding more sections for each event passed on to me. Heck while you are at it, if you happen to have a delete event from the same system, please send that on as well!
I will do a couple of the easy ones, eDirectory and Active Directory to get us started, and through in a nice esoteric one, for the SAP HR driver as well.
Usually with a move event there are a couple of things you want to know. The original identifier of the user in the system, that might be a DN, or something else. You can look at this Open Call for Association Values article Open Call - IDM Association Values for eDirectory Objects where I listed all the Association values for each driver. Very often that is the only unique identifier in the connected system, and often that is what will be the original identifier in that system.
eDirectory and Active Directory obviously have DN structures. As does Lotus Notes, at least for users, but intriguingly, Groups are all stored flat in Notes/Domino, without structure. Thus a move makes sense in those systems, since you can move within the structure.
Some systems, just have a single flat namespace, like Remedy, where it is just the Username, and it must be unique in the system. Thus there are no real moves that can come out of Remedy, just renames, at most.
Other systems, even though they have flat namespaces, might generate a move event in policy or in a stylesheet like SAP HR, where the source name is basically the PERNUM (what we might call the Person Number, WorkforceID, or Employee Number). The SAP HR driver is a bit of a special case, since it triggers a destination move, as users go Active or Inactive in SAP HR, to move them in the Identity Vault from an Active to Inactive container, or the other way around. The driver generates the move event in the XSLT Stylesheets, as part of the default config, and it is possible you might want to do some additional work, so you might see a move event there.
Thus finding the source name, of where the user being moved is starting from is one important thing.
The next obvious piece of information you would want to know is the destination DN, where it is going in the target system.
Then there are the unique vagaries of the system as discussed above for SAP HR, and as you will see for Active Directory below.
Thus the important things to provide are a code sample of a move event from the Publisher channel of the connected system driver, and then suggested XPATH to select the old-location, and then the new location from the event document. Finally please note anything unique about the specific example, that is important to know.
Lets begin with a nice simple example:
This is a pretty rare driver to see implemented, but it is out there, but often in larger companies, since SAP is quite a beast of a system, and often the overhead of running SAP is beyond what most companies need or can afford.
<move class-name="User" dest-dn="acme\Users\elf5151" dest-entry-id="40921" event-id="SAP-HR351:O_400_0000000011633059:P+00000287" src-dn="00000287" timestamp="20090807" xmlns:nsap="http://www.novell.com/dirxml/drivers/SAPShim" xmlns:query="http://www.novell.com/nxsl/java/com.novell.nds.dirxml.driver.XdsQueryProcessor">
This example is generated by the XSLT stylesheets that do much of the magic in this driver. I am not a fan of XSLT, and try to do as much as I can in DirXML-Script whenever possible.
Since this is generated in XSLT, it gets exactly what the XSLT provided, and not much more. Whereas the DirXML Script token Move Destination Object has built in code that makes its output look much the same all the time.
New Location: parent/@dest-dn
Old Location: @dest-dn
In this case, the object in SAP HR is not really moving, rather it is forcing a move in eDirectory. Thus the DN's are in eDirectory format (backslash notation as Identity Manager uses internally).
What is important to notice is that there is no Asscociation node on this event. This means that if you wanted to test a move event in policy, you would want to know if the user was associated, so that you could decide if you wanted to allow it or block. But in this case, there is no association value provided by the XSLT. As it turns out, the association value for objects in SAP HR are the PERNUM from SAP HR, which is in the event-id at the end (XPATH of subtring-after(@event-id, "P:+") to get it), the src-dn (XPATH of @src-dn to get it) or else you could use the Resolve token to get the association value from the DN, to look into eDirectory to see if the object is associated. Probably by that point, there is a better way to figure it out.
Probably the most common driver out there is the Active Directory driver, so lets go on to this slightly more complex example.
In Active Directory, it turns out the driver shim cannot really tell the difference from an internal Active Directory event for a move from a rename event and the converse.
Thus when an object is either moved or renamed in Active Directory (Rename in this context means the CN= in the DN changes) you actually get two events, a rename and a move.
There is policy that looks in eDirectory and checks to see if there is a DirXML-ADContext value, to get the old DN value, compare it, and figure out if it is a move or a rename, and veto the incorrect event.
From the Publisher channel:
<move class-name="organizationalUnit" event-id="Active Directory##1201fb6ea92##0" src-dn="OU=Users,OU=Computers,OU=GLEN,OU=NewNorth,DC=americas,DC=acme,DC=corp">
<rename class-name="organizationalUnit" event-id="Active Directory##1201fb6ea92##1" src-dn="OU=Users,OU=Computers,OU=GLEN,OU=NewNorth,DC=americas,DC=acme,DC=corp">
New Location: parent/@src-dn
Old Location: @src-dn
You can see right off the bat this is different than for SAP HR generating a move in eDirectory, where here the XPATH's are based on src-dn's instead of dest-dn's.
Worth noting, and knowing in advance means you can write a rule without having to see it happen in trace to understand!
We see that Active Directory sends two events for a move or a rename, therefore, you should probably wait un till after the driver resolves which event this really is before you try and manipulate it.
The 3.6 driver config has these rules in the Publisher Event transform, in the pub-etp-HandleMovesAndRenames policy object. You should probably add a policy object after this one, before trying to handle move and rename cases.
This is what gets sent on the Sub channel to the other half of the driver, to be received on the Publisher channel.
The eDirectory driver is one of the more confusing drivers, since it really consists of two halves of drivers, one half in each tree. And it is the Publisher channel that is in each tree that does the heavy lifting. Basically the eDirectory driver mostly looks at inbound events, coming to it from the other driver. I like to think of it as only thinking about inbound events.
This code snippet is actually from the Subscriber channel of an eDirectory driver, after a user was moved, in this case by hand in a connected Active Directory
<nds dtdversion="3.5" ndsversion="8.x">
<sync cached-time="20090505190943.139Z" class-name="User" event-id="mta-gwlab#20090505190943#1#2" from-move="true" qualified-src-dn="dc=corp\dc=acme\dc=asiapac\OU=China\OU=Shanghai\CN=tgwuser2" src-dn="\ACME-LAB-LDAP\corp\acme\asiapac\China\Shanghai\tgwuser2" src-entry-id="33906" timestamp="0#0">
<move cached-time="20090505190943.139Z" class-name="User" event-id="mta-gwlab#20090505190943#1#2" old-src-dn="\ACME-LAB-LDAP\corp\acme\asiapac\Japan\Tokyo\tgwuser2" qualified-old-src-dn="dc=corp\dc=acme\dc=asiapac\OU=Japan\OU=Tokyo\CN=tgwuser2" qualified-src-dn="dc=corp\dc=acme\dc=asiapac\OU=China\OU=Shanghai\CN=tgwuser2" src-dn="\ACME-LAB-LDAP\corp\acme\asiapac\China\Shanghai\tgwuser2" src-entry-id="33906" timestamp="1241117863#1">
<parent qualified-src-dn="dc=corp\dc=acme\dc=asiapac\OU=China\OU=Shanghai" src-dn="\ACME-LAB-LDAP\corp\acme\asiapac\China\Shanghai" src-entry-id="33786">
new loc: parent/@src-dn
old loc: @old-src-dn
Here we see a sync and a move event. Usually if the move happened on the same server you will see the pair of events. If the move event happened elsewhere in the tree, you will often only see a sync event. This gets a little confusing.
Here we see that in a move event, we get an old-src-dn and qualified-old-src-dn XML attribute in the <move> event node. This means we can select them with XPATHs of @old-src-dn or @qualified-old-src-dn (If we need it in LDAP format).
So how about dear readers? Got any move event traces from some driver other than the three I mentioned? Lets get them documented and up there to make all our lives easier!