SAP HR CMP Integration Driver walkthough part 3:
In the introduction to this series, SAP HR CMP Integration Driver I discussed the plan of working through the SAP HR driver that comes with the Compliance Management Platform (CMP) to give a better understanding of its inner workings.
You can read more about the new family of SAP drivers that were released with Identity Manager 3.6 and the Compliance Management Platform in this article on the SAP family of drivers:
The SAP Driver Family for IDM
As this series develops, I will update the links to the rest of the series here:
The plan is to try and get more articles of this nature, which walk through a default driver configuration, explaining WHAT is going on, and when possible WHY it is done that way, in order to make troubleshooting and modifications easier and safer. If you do not know WHY something is being done, it is often hard to work with it.
There are all sorts of interesting little tidbits scattered throughout the various driver configurations that are of interest, and it would be great to have them all in one location as a reference.
Thus I started this Wiki page: Detailed driver walk through collection to try and pull it all together.
If you have the time, consider looking at a driver configuration you are very familiar with and try writing up a channel (Publisher or Subscriber), a policy set (Say the Publisher Event Transform, or the Subscriber Command Transform, or whatever tickles your fancy), or if you can, the entire driver.
The more we get written, the better it is for everyone. This is also of interest for the older and newer driver configurations, as they change from version to version, and it is important to be able to notice the differences between the two, if we are to ever have a hope of doing a meaningful upgrade.
The hope is to get as much content, even duplicate content, as different perspectives are of interest, together to make it better for everyone.
A quick recap of the SAP HR driver then. The current shipping driver handles the relationships between Organizations, Positions, Jobs, and Persons in SAP's HR module in a somewhat simple fashion, and if your SAP OM (Organizational Management) module is used in a somewhat complex fashion, then the driver may have problems handling it.
This was recognized, and for backwards compatibility reasons, the Novell Identity Manager 3.6 product comes with two different versions of the SAP HR driver. There is the previous approach, updated for Identity Manager 3.6 and there is the version called the CMP SAP HR driver.
This second driver is the one under discussion, and it requires a second driver to work hand in hand with, the SAP Business Logic driver.
Let's work through the new CMP SAP HR driver first, then on to the SAP Business Logic.
The plan here is to start at the Input transform rule, down the Subscriber channel, turn around, come back up the Publisher channel, all the way to the Output Transform and look at each Policy object or Style sheet object, in order to try and explain what is going on in reasonable detail. This is probably going to be somewhat boring if you are not interested in the SAP HR driver, so my apologies in advance for that. But the hope is that it will serve as a useful reference document for others working with these drivers.
Thus let's begin.
Sets a driver scoped value as to whether it is initialized or not. If it is, breaks, if not, does the initialization process.
Checks to see if there is a DirXML-sapDMRoot object. If there is, it moves on, else it creates the structure to hold the Org structure.
Adds an object of class DirXML-sapDMRoot to create the sap container for the driver, as driverDN\sap.
Adds an object of class DirXML-sapOMRoot as the driverDN\sap\om
Adds an object of class DirXML-sapOContainer as the driverDN\sap\om\o
Adds an object of class DirXML-sapSContainer as the driverDN\sap\om\s
Adds an object of class DirXML-sapCContainer as the driverDN\sap\om\c
Then it sets the driver scoped variable dmInitialized, to true so it will not do this again.
This looks to be a pretty generic CMP/Resource Kit rule to log much of what is happening via the logging rules new with CMP/Resource Kit.
This is an XSLT style sheet, with comments in German, which is not helpful to me, alas. Thankfully Google translate manages a barely understandable translation.
It looks like the driver is reading info type (IT) 0000 MASSN, offset 74, length of 2, which is mapped to DirXML-sapActions. This is an SAP Action code item as I recall.
Then it checks the timestamp and only for valid time stamps builds a variable "actions" with the following XSLT:
<xsl:variable name="action" select="concat($validity, '#BEGDA=', substring-before(@timestamp, '-'), '#ENDDA=', substring-after(@timestamp, '-'), '#MASSN=', ., '#MASSG=', $actions-instance/node()[@attr-name='P0000:MASSG:none:76:2']/value[$position], '#STAT2=', $actions-instance/node()[@attr-name='P0000:STAT2:none:79:1']/value[$position])"/>
The variable "validity" is set to -1, 0, or 1, with -1 being historical, 0 current, and 1 future dated. SAP HR sends the entire history with each event, so there will almost always be more than one, but all but one will be in the past or future. Only one can be current at any moment in time.
Then we get #BEGDA as a string, then the SAP begin date in SAP date format of YYYYMMDD, then #ENDDA with the end date value, then #MASSN and the action value from SAP, the #MASSG the value from the IT0000, MASSG filed at position 76, which is 2 characters long, then #STAT2 with the ITOOOO STAT2, offset 79, length of 1 data. STAT2 is the active, inactive value, and there are usually 0-3 values. The four values are usually:
We had a client where they used 1, inactive to indicate part time employees, so heads up, as this one might bite you if the SAP HR system runs the same way..
So DirXML-sapActions would probably have something like
This is the basic input transform from the standard SAP HR that does some format conversion.
Probably the biggest issue to be aware of is that the position number 99999999 is considered reserved in this driver and indicates that the user is inactive. At a client I was at, they used 99999999 as a place holder even for active users, before adding them properly. Had to disable this rule for the client, since it was not quite standard, so heads up.
For users, this is basically the same as the regular SAP HR driver, with the addition of DirXML-sapActions as discussed above, which used to be mapped to Login Disabled in the previous driver.
There are also new mappings of:
The sap-A-C, sap-A-O, and sap-A-S part is meant to reference the A type forward reference from SAP's relationship mappings. There is also a backwards reference that with be sap-B-something that will come up with the other object classes.
You can read more about the A-B relationship for O, C, S, and P objects in article on Relationships within the standard SAP HR driver:
SAP HR Driver and Organizational Management - Part 1
New mappings are for Organization, Job, and Positions as new object classes DirXML-sapC, DirXML-sapO, and DirXML-sapS whereas in the previous SAP driver they were mapped to preexisting object classes, CommExec, Organizational Unit, and Organizational Role respectively.
Otherwise those mappings are the same, with a long name and short name, and the OBJID of the object.
Publisher Event Transformation:
Now we move into the Publisher Event Transformation part of the process. This is a lot more complex than the previous driver. So let's get started.
As discussed above, events coming from SAP HR can be in the past, the present, or the future. Past events are of little interest and thus are discarded by this rule. Present events get copied through, and future events get added to the document in a node in the format of this line:
<xsl:variable name="futureEvent" select="concat('CLASS=', $class-name, '#TARGET=', $assoc, '#NAME=', $attr-name, '#VALUE=', ./text(), '#FROM=', $start, '#TO=', $end)"/>
which should generate a string value that looks something like:
where the FROM and TO values are in CTIME, which is the internal time format eDirectory uses for time based attributes. It is a count of seconds since Jan 1, 1970 at midnight.
You should get one such value, for each future dated attribute in the document.
This will become much more interesting later, as we will be loading these values into a Work Order, that the SAP Business Logic driver will process into Work Order To Do objects when that future date comes around. This is one of the features of the SAP Business Logic driver, but there are more. I have a series of articles on that driver coming once I finish this series. So many things to write, so little left of the keys on my keyboard! Many letters have been completely rubbed off, I am just waiting till I wear one down to the bare spring before replacing it! That would be a funny site to see.
Basically the SAP Business Logic driver that comes with the Compliance Management Platform version of the drivers has two main functions. The first is to process the Work Orders that get generated by this CMP version of the SAP HR driver for future dated events. From this aspect it is basically a standard Work Order driver that takes in Work Order objects as they come due (or as they are triggered, one of several ways, like setting DirXML-nwoDoItNow flag to true, DiXML-setting nwoSendToPublisher to true, or if the DirXML-nwoDueDate is due then the polling cycle will pick it up ) up the Subscriber channel, and then spit out a DirXML-WorkTo-Do with all the attributes that made it through the filter copied back onto the DirXML-WorkToDo object.
The second function that is much more complex is to handle some of the relationship information, after it has been received from SAP HR, and written out by this driver. Much of the series on the SAP Business Logic driver is going to focus on this second aspect of its job. That is a pretty complex driver, since the problem of managing relationships in SAP is actually quite complex as well.
I will try and get that series completed as soon as I finish this series. Then on to the other SAP drivers if I have time for it. I expect the SAP Business Logic driver to be quite interesting, based on what I have looked at so far.
It's a shame there is no easy way in Designer to look at an entire driver, with a Policy Builder view, in one giant long view (and hopefully printable) as that would make this sort of review much easier. I tried printing the Designer generated documentation, but as I went to read it on paper, I realized that there are a number of tokens, that are missing information, and it turns out to be next to useless for a code review. I guess I could read the raw driver export in the XML of DirXML Script, but I find the Policy Builder view in Designer much easier to read and understand. In fact I find the Designer view much easier for an overview than the iManager view. Additionally I have been writing most of this series as I take the bus to and from work in New Jersey to New York city, so offline in Designer is much easier for me.
It seems like I just get started, before it is time to take a break for the next segment of this series. Sorry for the boring aspects of it. This really is an interesting driver, that does a lot of neat things. There is just so much of it to walk through and understand.
Stay tuned for part 4, same bat time, same bat channel.