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: http://wiki.novell.com/index.php/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 any a somewhat complex fashion, then the driver may have problems with 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 version, 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.
Lets work through the new CMP SAP HR driver first, then on to the SAP Business Logic.
In the first article (SAP HR CMP Integration Driver Walkthrough - Part 1) I discussed the driver configuration settings.
In the second article (SAP HR CMP Integration Driver Walkthrough - Part 2) I discussed the Global Configuration Values.
In the third article (SAP HR CMP Integration Driver Walkthrough - Part 3) I started on the Input transform. and got barely into the Publisher, Event Transform rule set.
In the fourth article (SAP HR CMP Integration Driver Walkthrough - Part 4)I got part way through the Publisher Event transform.
In the fifth article (SAP HR CMP Integration Driver Walkthrough - Part 5) I finally finished the Publisher Event Transform.
In the sixth article (SAP HR CMP Integration Driver Walkthrough - Part 6) I made it through the Match and Create rules.
In the seventh article (SAP HR CMP Integration Driver Walkthrough - Part 7) I made it through the Placement rule, which was trickier than expected.
In the eighth article (SAP HR CMP Integration Driver Walkthrough - Part 8) I made it through the Command Transform rules.
Lets continue then from where I left off, finally starting on the Subscriber channel.
The standard SAP HR driver does not do a lot in the Subscriber channel, and this version does not disappoint on that account. There seems to be just objects in the flow. A matching rule, a rule in the Command Transform, and an Output Transform style sheet.
Some of this is due to limitations in the SAP HR driver shim. The driver is pretty limited in what it can write back to SAP HR. I am pretty sure you cannot actually create an object in SAP HR's database, via the driver, since you are not allowed access to the various infotypes you would need.
iDOC files are position based, which means that you need to count the current location on the line to find a fixed length field. This is a real pain as some lines can be two to three hundred characters long. I run my laptop at a ridiculously high resolution of 1920 X 1280 on a 15 inch screen (PS: I LOVE IT!) and there is still not enough room on the screen for all that text to be readable. On a side note, if you were looking for an excuse to get dual 27 inch LCD panels at your work desk, start working on Identity Manager with Designer, and it is clearly obvious you need a couple of high resolution monitors! Worst than that there is a 63 character offset that sometimes counts, and sometimes does not, depending on how and where you are viewing the iDOC file. (Usually when editing the .meta file (that is sort of like a schema map file, which lists the various infotypes, and the offsets for each attribute inside the infotype) and the Schema map).
Anyway, the data in the iDOC is all the data you get. You cannot really query back into SAP HR, in most cases, only back into the data in the iDOC.
However on the Subscriber channel side the driver uses the published API from SAP, called BAPI (what the JCOTest.class tests as part of its connectivity testing) and is provided a transport by the JConnect libraries.
Alas, this limits the driver to the data that BAPI exposes. The list of infotypes is:
Personal Data (Infotype 0002)
Private Address (Infotype 0006)
Communication (Infotype 0105)
Internal Data (Infotype 0032)
There are all sorts of other limitations in terms of future dated events and how updates are done. Like changes to the Internal Data infotype (0032) and Communication infotype (0105 where email, phone numbers, etc are stored) are slightly different than the other infotypes, in terms of how the update is written to SAP. There is a configuration value to control whether the changes for these infotypes are set as new delimited values, or just modifications to the existing data.
However, since SAP HR is usually authoritative for HR data this is usually quite tolerable. The major consequence is that the Subscriber half of the driver policy flow is pretty empty.
The only objects matched are Users, and in this rule, the match is performed based on workforceID.
I guess I was hoping there might be some use of Central Person number in this version of the driver, but there isn't. Just to make things trickier, SAP HR has a PERNUM (which we usually map to workforceID) that is meant to uniquely identify an object. (Technically a User has a PERNUM, other objects have OBJIDs but same stuff different day). Except of course that a PERNUM can change. When I first encountered this my response was, are you kidding? You can change the unique identifier?
Worst than that, there is a real use case of it changing to something else, then later changing back to the original value! (Usually involves moving jobs from country to country within the same company's HR system. The argument I was told was that it has to do with different countries having different tax laws. I dunno that seems like it is missing some detail). There is a Central Person number that is ACTUALLY the really unique identifier and there is a relationship value that links users to their CP number. However this driver version still uses the PERNUM to link the users.
There is a single policy object here, sub-mp, that detects Add events, and vetoes them. As described above there is no ability to actually create a user in this driver due to BAPI limitations, so they are vetoed.
The main reason for doing this in the Command Transform instead of the more logical Event Transform policy set is usually because a modify event could come in, and the Add processor might convert the event into a synthetic add event.
However, since there is no Placement policy, any synthetic add events that get through would be vetoed, with a message about "No DN generated by the object placement policy".
I am not sure why this policy is needed, but there is no downside I can think of. I imagine there is some goofy error case where an event might slip through, and so this rule was added a safety valve.
What is also interesting is that it is named otp-VetoAdds which according to the new naming standard means it should be in the Output Transform (the 'ot' part of 'otp', as a Policy object (the 'p' part of the otp) as opposed to a style sheet (would have been 'ots', in that case).
There is a single object in this policy flow, it is an XSLT Style Sheet, that does some pretty basic transformations that are pretty typical.
There is the identity transform that means that if nothing else matches, the event document will get copied through.
Next up is a modification to the association value. It turns out the driver by default drops the first character of the association value, unless it is a User object (Class of P by the time we get this far in the driver, after the schema map). It uses a substring function of $assoc, 2, 8 which is start at position 2 (starts the count at 1, not at 0), for 8 characters. This is because other objects append the object class letter before the OBJID value, and this strips it off before handing it to the driver shim.
There is a matching rule in the input transform style sheet that takes the OBJID and prepends the object class letter onto it.
This little dance is really quite annoying when working with the driver, but the reality is that the association values having the object class in it, turns out to be relativly useful. I am torn if I like it or not. It would be easier not to do it, and use other tricks to infer the object class, but it does have its useful moments when reading trace.
I suppose as long as you know it is going on it is pretty easy to deal with, but if you assume an association value is an association value (which is pretty much the case in most drivers) then this one can throw you for a serious loop.
Beyond that we have some standard transforms for the Postal Address attribute from structured syntax to a string. Postal Address uses one of those funny sytaxes that is composed of six fields, all named string.
Next up is transform homePhone, and removes any characters that make a usual phone number look pretty. First get rid of the round brackets, then later in the following step remove dash characters.
With that, the driver configuration is wrapped. That took longer than I expected. Next up on the plate is to look at what is going on the Business Logic driver, which is the part that processes the Work Orders, and does other magical stuff I still need to figure out and understand.
I know based on Holger Dopp's presentation on this topic at BrainShare 2010, that he has a completely revamped configuration where even more of the work is moved out of the SAP HR CMP driver into the Business Logic driver, so I think after consideration it would be worthwhile to work through the version one driver still, and then revisit it when version 2 is released.