SAP HR CMP Integration Driver Walkthrough - Part 1
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.
Lets 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.
Lets start with some of the configuration options.
Driver Configuration options:
I am working with the Designer view, which breaks the configuration options into three pages on the Driver Parameters tab. as Driver Options, Subscriber Options, and then Publisher Option sub-tabs. Can we ever have enough tabs? Not to my mind! The iManager view, usually puts them all on one long page. But it is hard to look at iManager offline, whereas Designer works just peachy for that purpose.
The driver configuration is your standard one, with a few SAP specific custom settings. The SAP system number, the SAP User Client number, the language, character set encoding. Ask your SAP folk, and they will know the answers to all of these.
The Metafile is a text file, usually stored on the remote loader, (though I guess you could run this local) that is a listing of SAP Infotypes. They are named HRMD_Axx where xx is 05, 06, or 07 which correspond to the version of SAP you are connecting too. The documentation for this is actually pretty good and not worth duplicating here.
You provide the info for this file in two parts, first the path to the file, then the name of the file.
Now we come to an interesting issue. Future dated events.
In SAP HR every event is delimited. That is, has a start and end date. For example, your name will be delimited usually by your birthday, since that is sort of when you started using it, and they are nice prognosticators, the end date for your name is Dec 31st, in the year 9999. (Shown as 99991231 in SAP HR format). I imagine less progressive companies might consider changing the end date of your name when they know you have passed away, to the day of death, but that seems a little bit morbid to me, and too much information in the HR system!
Of course, should you see an end date on some of your personal HR data, that is not too far in the future, I would consider contacting them to find out what they know, that you do not!
There is an additional twist you need to watch out for. If you are syncing end dates into a Time syntax attribute in eDirectory, you probably got some -613 Illegal Syntax errors when you actually tried it, since eDirectory Time syntax uses a format called CTIME, which is a 32 bit integer value that counts the number of seconds since Jan 1, 1970 one second after midnight. This has a major problem, in that CTIME runs out sometime in the year 2037. Yes, there will be a Y2K37 problem! Yay! This one, to my mind will probably be worse than Y2K, but time will tell.
I usually add a GCV named endOfTime that I set instead of 99991231 in eDirectory when one of these events come through. You will need to consider how you want to handle this issue, if you come across it.
Anyway, so what do you do when someone is being transferred but it does not start until the end of the month? Well HR has the paper work today, and wants to enter it, but it should not take affect for say two more weeks. In SAP HR, this is a non issue, as they enter it now, with a begin date of two weeks from now.
But Identity Manager is event driven, so what do we do with that event? Process it now? Stall? If so how?
The original driver used FUTR files on the remote loader. That is, when an iDOC comes in from SAP HR, the current or past dated events are processed immediately, and any future dated events are pulled out and written to a new file, ending in .futr. Then when that future date comes due, they are processed.
This is one approach to stalling the event. The major downside to consider is, what if someone is promoted and it is dated a month in the future, but in the intervening month is caught in an illicit affair with the office supplies? (Hey I dunno where you work, but stuff happens, ok? We may not want to talk about it...)
Then a demotion or perhaps termination is entered, before that promotions future date. Well what happens one month from now, when his promotion, in the .futr file comes through and is processed? But the user is terminated? Depending on the data in the .futr file you might reactivate the user.
The alternative in the standard version of the SAP HR driver is to let all future events through at iDOC processing time, and manage them in policy yourself, in whatever form that might take.
As it turns out the default of .futr files, usually work relatively well, and the CMP version of the SAP HR defaults to letting future dated events flow. Then the driver handles them, in this case, through the use of Work Orders, which are processed by the SAP Business Logic driver, thus the comments that the two drivers work hand in hand.
I am not sure what the Future-dated Event Validity Checking option does, but I will try and figure out and update when I do.
Next is Object Type code. In SAP HR objects have names, that are single letters. The driver by default supports the basic types, O, C, S, and P. Organizations (O), Jobs (not sure why C, I imagine the German word for Jobs makes sense as C), Positions (S), and Persons (P)
There are a few additional types, I have heard of K for Cost Center, but that is a bit of a task, as it is not really part of the HR system. Usually there is no need to touch this setting.
The next two Address Subtype Code, and Communications Subtype Code are somewhat similar. An iDOC can reference the same 'field' but with a different subtype, and thus have a different meaning in that context. Thus IT 0105 which is the Communications, has a field USRID, which is the user id in the SAP system, when no subtype (I guess that would be a subtype of 000), but means email address when subtype is 010, and is cell phone or pager when using those subtypes. Just to confuse things, there seem to be well known aliases like CELL for a subtype that is not numeric.
If your SAP HR system has extended IT0105, with new subtypes, then you would need to think about adding them here, as well as in the schema map, filter, and rules to process them.
Subscriber Options sub tab:
Communication Change Mode is an interesting choice, and I in fact did not run into this, until the very end of the project. When Identity Manager decides to send an event back to SAP HR, there needs to be a decision about how that change is going to look in SAP HR. The default is Delimit mode, which means the previous value is set to an end date as of yesterday and the new entry is added, with a begin date of today, and an end date of Dec 31, 9999 (I like to call that end of time!). In the case of a remove-value this would imply that the current value in SAP HR would get changed from an end date of end of time, and instead would be set to the current date.
You might not want that, and instead might want to use the Delete mode, which would just remove the value on a remove-value. The difference between Delete and Change mode seems to only occur when you get a <remove-value> node, and a <add-value> node in the same document. In this case, the removed value is removed, with Delete mode, but modified in Change mode.
Next we have Communication Validity Date Mode, This decides whether to use the drivers current model of validity dating which is begin today, and end at 99991231 or else to just let SAP HR handle it itself, however it is configured. I.e. Do not send any validity date information.
Internal Data Change Mode and Internal Data Validity Date Mode are the same decisions as the Communications that just preceded these, but focused on IT0032, where as Communications is IT0105.
Here you specify the IDoc File Directory, on the local or remote system, where the SAP HR system is dumping the iDOCS into the file system. Obviously the format of the path would depend on the target system, where Unix and Windows would have different formats.
Enable/Disable Publisher Connection to SAP Application Server lets you decide if you can query back to get info out of SAP HR. Now if this works, that would be great, since this did not seem to work for me, in the IDM 3.5 version of this driver! That would be very helpful.
Poll interval tracks how often it looks at the file system to see if new iDOCs have arrived.
Well thats that for this segment. This will take a while, as there is a huge amount of detail involved in this driver! Stay tuned for the next parts of this series.