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 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 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.
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, and 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.
The GCV's for this driver initially look simple and trivial, all you see are 5 values, New User Naming (hide), and Object Relationships (hide), Future Events (hide), Debugging (hide), and Process Logging (hide).
But if you change those values from hide to show, oh boy, are there lots of options.
Here you get three naming options for objects. This is an interesting twist as the standard SAP HR driver had an XSLT style sheet that implemented the naming model. What I found easiest, was to leave it behind, then use a DirXML Script policy object afterwards to create the name I wanted too. The Unique Name token is truly excellent, and worth using. In my mind it is much more advanced than the style sheet used in that version of the driver.
You can read more about the Unique Name token, in this article: Unique Name Token Functionality in IDM 3.5
There are two options that are employee name based, fixed length and variable length. Then there is an Attribute based value where you then get an option to select a User Naming Attribute. The default suggestion is based on workforceID, which would give you an all numeric user name, usually.
When I have implemented this driver, usually we use the info type 105 USERID subtype, allowing HR to control the user name at hiring time. However, that is site specific, so there are all sorts of different approaches possible.
Change the setting for Show Object Relationship Options from hide to show, and oh dear, are there a number of options available suddenly.
Probably the most important setting is the first one, Discover Relationships, which enables the relationship model. If this is off, no relationships will be managed.
Next up is the filter. This is used to limit the relationship types that are supported, as SAP HR has many many possible relationship types, (for example Person to Central Person Number is 209, so you can imagine there are several hundred possible values, though I only know of a small number of them.)
The attribute uses one of the new GCV types, called, Structured, which allows you to define a template to be filled out, with values. There is a great demo of this new GCV type at: Structured Global Configuration Values in Designer 3.5 (Demo)
Anyway, there is a filter value for each of the possible object classes that will represent relationship objects.
|Previous HR driver object Class|
|CMP HR driver Object Class|
For each object class, the schema has been extended with an attribute for each major relationship type.
Let's take the Position object, S, as an example. The attributes are named in ways that look like:
DirXML-sapS-R-A-O-003, which broken up means, DirXML-sapS, the object class, -R- for relationship, then either an A- or B- for forward or backwards reference, and finally the number of the relationship type. Some examples are:
008 is the Position Holder. B on the Person, A on the Position, thus the attribute on the Position object would be:
DirXML-sapS-R-A-O-012 would be the position that manages the Organization. That is, on the Position object (DirXML-sapS), a relationship (-R-), a forward reference (A-), to an Organization object (O-) that is relationship type for a managing position (012).
This list goes on quite a bit, with many of the possible relationships. The main ones are:
If you intended to handle additional relationships that are specific to your site, you would be extending these GCV's to specify some of the handling. You would probably have to change some policy to handle the additional relationships, but this would probably be your first step.
We will see later that this filter is used to limit the processed relationship values. However, you should work with your SAP HR folk to filter what SAP HR includes in the iDOCs. There is overhead in processing each relationship, even if they are being filtered, and the cornucopia of values will just make troubleshooting harder.
Having said that, do not let them tell you that it is sufficient to send just one half of the A - B (forward - reverse) relationship pairing, since you can infer the other, as that would require additional custom coding and would be a short sighted decision.
There were a number of future dated settings in the previous article (SAP HR CMP Integration Driver Walkthrough - Part 1) in this series, about the Configuration settings, but here is where we get one more chance to control whether we record future events in Work Order objects or not.
The Work Orders are stored in the context of the SAP Business Logic driver, and the next option is to specify the DN of driver. You should use the DN picker so that it enters it in the correct format. This is used to generate placement DN's for Work Order objects as they need to be created.
All the CMP version of drivers that I have seen to date use a similar logging model of writing out each attribute that is changed and some minor details, in a more compact (and compressible) format. More on this in the next article or two, as we work through the rules where it is managed.
Thankfully you can easily enable or disable this feature by GCV, in case you are tight on disk space.
This particular setting is adding some additional logging specific to this driver, for what it calls generated attribute names, which I believe is a reference to the relationship attributes. They are called generated, since they are calculated in policy and style sheets by the object name (DirXML-sapO for example), then the -R- for relationships, then the referenced object, and the relationship type and so on, as discussed in the previous section on the relationship filtering.
This is over and above the usual default logging the CMP drivers with and would be useful for reading and troubleshooting a concise log of relationship values. If you have ever worked with the raw iDOCS and the XML that gets generated you will greatly appreciate the brevity of this logging.
This logging reference is the more standard CMP driver model logging. The rules come out of a shared library, and are consistent across all the CMP enabled drivers I have looked at so far.
Enable it with Enable Process Logging, specify a daily log file format that includes the date stamp in the format of:
<YYYYmmDD>-<driver-name>-<drv.proclog.logfile> withe Daily Logfile option.
Otherwise you need to specify a file name for the log file with the Logfile Name option.
Finally you need to give it a directory to place the logs in. As always take care, and place this in a file system with LOTS of space, and avoid using a file system, that if filled up, can cause issues. Obviously this differs depending on operating system and file system layout, so I cannot give much more direct advice.
That takes care of the Global Configuration Values. With the driver configuration values discussed in part one (SAP HR CMP Integration Driver Walkthrough - Part 1 ) of this series, we have most of the configuration settings handled now. Obviously this driver has a strong dependency on the SAP Business Logic driver (you will recall we had the specify the DN of that driver in the Future Dated event processing section above) and the configuration of the SAP Business Logic driver is important as well. Stay tuned for a series of articles working through that driver, once I finish this series.
Next episode of this series I will start working through the actual style sheets and policy objects that make up the guts of this driver. Much of the work is done in the Publisher channel, as data comes out of SAP HR in the form of iDOCS. Very little is managed on the way into SAP HR through the Subscriber channel. This is similar to the previous version of this driver and not much has changed there.
Hopefully this will be of value to some implementing this driver, as it truly is one of the more complex drivers out there.