In the introduction to this series, https://community.microfocus.com/cyberres/idm/w/identity_mgr_tips/3370/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: https://community.microfocus.com/cyberres/idm/w/identity_mgr_tips/3837/the-sap-driver-family-for-idm

As this series develops, I will update the links to the rest of the series here:

• SAP HR CMP Integration Driver Walkthrough - Part 1
• SAP HR CMP Integration Driver Walkthrough - Part 2
• SAP HR CMP Integration Driver Walkthrough - Part 3
• SAP HR CMP Integration Driver Walkthrough - Part 4
• SAP HR CMP Integration Driver Walkthrough - Part 5
• SAP HR CMP Integration Driver Walkthrough - Part 6
• SAP HR CMP Integration Driver Walkthrough - Part 7
• SAP HR CMP Integration Driver Walkthrough - Part 8
• SAP HR CMP Integration Driver Walkthrough - Part 9

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.  (Sadly this Wiki is now defunct).

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.

Lets continue then from where I left off with the Matching and Create rules.

Publisher Matching Rule:

Click to view.

pub-mp-LogBefore

Now that we are finally into the Matching rule, we start with a little bit of logging if enabled by the GCV.

Not really much to say about this one. Looks like it just logs that it made it this far in the process.

pub-mp

Users are matched by DirXML-sapID, which is mapped to PERNUM from SAP. PERNUMs are sort of unique, except for when a user has more than one. How is that for a lousy definition?

There is the concept of a central person (CP) number, that relationship 209 lists off. There are a number of cases where a user might have more than one PERNUM in SAP HR, usually due to changes in countries. I honestly do not understand the WHY of it, from an SAP HR side, I am more of a victim of the issue, and have seen users change PERNUM's which is really darn annoying when you are using it as an association value, which is supposed to be globally unique and not change. Then it goes and changes on you!

Now to be fair it is pretty rare, and usually there is a preceding event that suggests that the PERNUM is about to change. In the example of an Expatriation and following Inpatriation. I cannot quite explain it well, but you are an expatriate of your original country and in inpatriot of your new country. When you return both end, and you become a regular user as well.

Usually there is a SAP grouping attribute that changes that helps indicate this. But I think that is installation specific, how exactly that one works.

Regardless, this should work to match users.

The exact same rule, but with a different object class repeats for the O (Organization), S (Position), and C (Job) objects using the DirXML-sapID, which is at that point known as OBJID instead of PERNUM. Persons have PERNUM's. objects have OBJID's.

The last rule is for future dated events, and is looking for Work Order objects, and this matches by CN of the work order.

pub-mp-LogAfter

This rule actually logs some interesting and useful things. As usual it checks the GCV to see if it should actually log anything or not.

First it sets the logging variable, lvTemp to "...passed, (no match found)" to initialize the process.

Next it tests for a Destination DN. This is a neat trick, and in fact a key thing to understand how the matching rule, and the Find Matching object tokens work. You can have a long list of Find Matching Object tokens, one after another, in order of priority, because the first rule that successfully matches, sets the Destination DN value (you could test with if Destination DN is available, as done here. or else with an if XPATH of @dest-dn, which would return true if there is a value and false if not), and all following Find Matching Object tokens perform the same test and just move on if there is a destination DN.

Thus testing here, tells us an object was found.

But there is an extra twist, there is also a test that destination DN is not equal to ? and we see that the next if then block tests for the case where it IS equal to ?

This is a neat add on in later Identity Manager versions, where the multiple match case is much better handled. I wrote some more about this extra functionality in the article:
New IDM 3.6 enhancement to do-find-matching-object

Basically if more than one match is found, the destination DN is set to the funny value, and you can thus detect it. There are even some error variables that get set, with all the multiple match values, so in those error cases, you could fix the problem before it gets out of the Matching rule.

Anyway, in this case, if none of the tests are true, it will log that the it passed the matching rule, with no match found. If there is but a single Destination Dn value, then it will log that it passed with a single match found, and if there are multiple matches, it will log that it passed with multiple matches found.

Now this is interesting, as in my experience, multiple matches found usually generates an error and stops the process cold. I wonder if something has changed in Identity Manager 3.6.1 that lets it pass into the later rules, that is different than before.

And with that, we are done with the matching rule.

Publisher Create Rule:

Click to view.

pub-cp-LogBefore

This as usual logs that you are entering the Create rule for the specific object.

Nothing special here to see, same basic logging as all along.

pub-cp

The first rule is User: add jobCocde tries to get the short name for the SAP Position that this user is assigned.

A couple of tricks. Nice first thing to note is the value is set in a local variable, and then tested for a value (using a regular expression test of . which means any character, and any number of them). This is just good planning.

The local variable is set using the Destination Attribute token, for the attribute DirXMl-sapSShortName, in the class DirXML-sapS (Position object) located by the Association value. Usually you know the DN of the target object and can either calculate it, search for it, or specify it. Here they are using the other option, specify the target object by Association value, and calculating the value as the letter S followed by the value of the operational attribute DirXML-sapP-A-S which is the op attr that maps the users (DirXML-sapP part of the attribute name) forward reference (-A-) to their position object's Object ID in SAP (S). Thus if the position for a user is 12345678 then the Association value for that object would be S12345678.

This is a neat way of doing a search without having to do a proper search. Let the engine handle it via an Association value lookup.

Then as mentioned above, check for a value, and if there is one, write it out to jobCode on the current object in process.

User: add Title

Title is the long name of the Position object. This uses the exact same process as the previous rule, this time looking for the attribute DirXmL-sapSLongName on the S object the user is assigned too.

Now an interesting thing you will see happen in trace, that is often quite bewildering is that when a query is sent to eDirectory for a Policy object such as this pub-cp object, the first time it has to query, it may look for multiple attributes, and you would look at trace and wonder, why did it do that? I only needed the one attribute yet the engine queried for two, three or more.

This is actually a really cool feature of Identity Manager, (and I was told a patent pending bit too by its author! Thanks again Father Ramon, you really help out!) that reads the policy object, decides which queries can be optimized into just one, and then when it does the query, it reads them all in, which populates the cache so that in the next rule, when the Query is run again, the data is in the cache, and no time is wasted setting up, sending, receiving, and parsing the query.

This is really a big boost to performance, as the act of performing a query is "slow" compared to reading it out of cache. Not just because of the search time, which is often not that bad, due to the ability of eDirectory to cache most of the database in memory, or due to indexing returning results quickly, but mostly due to the fact the query document is processed by the entire rule set in both directions before being completed, and while quick, that still takes minor measurable time.

When querying and getting a response out of the cache that process of running through the entire rule set is skipped, as the first query already did all that work, and there is no need to run it again.

User: veto if Surname or Given Name is missing

This is a classic Create rule, veto example, using the veto if operational attribute is not available token. I understand why Surname is required, as eDirectory base schema requires a Surname value to create a user, but I am not sure why the Given Name missing is worth a veto here.

This does pose an interesting point that people using SAP for HR, and having employees in many countries may face. Naming is HARD. Much harder than you would think, especially in global companies. Some countries have very different naming patterns than you might have grown up with. Living in North America (first Canada, then the United States) I am spoiled by relativly easy naming standards. But the rest of the world? They are crazy folk out there! They will name themselves anything! And everything!

Indonesians (lovely people, but annoying naming!) often have no last name. They just have a first name. Well eDirectory is NOT amused by folk like this! Thus you have to decide how to handle that, and I do not think this driver handles it out of the box.

What I did in practice is add an attribute acmeNoLastName as a boolean, and for Indonesians, set it to true. Then anytime we did naming rules, test for that attribute to know that we copied the first name to the surname field and blanked the first name. My apologies to the folk in Indonesia, but it was the best I could do.

What I did notice from the live data was that most such users usually had the letter M or S as their last names, for reasons no one in the company (living in the culturally illiterate United States you see) could explain why or what it meant. Which actually was great, as it obviated the need for such code in almost all cases.

User: add DirXMl-sapPAux

This one makes me wonder, as usually the engine will do this work for you, (as it leaves the Command Transform and just before it hits the Notify filter) and add any needed auxiliary classes, should an attribute contained in one be needed. I too, often find it easier, knowing I am using such attributes to add the auxiliary classes myself just to be sure.

I know there is a subtlety of when this is needed, and when not, but I always forget, and just to be safe add it by hand. I guess this is one of those cases where it is needed.

DirXML-sapO: veto if DirXML-sapOID is Missing

DirXML-sapS: veto if DirXML-sapSID is Missing

DirXML-sapC: veto if DirXML-sapCID is Missing

These three rules do the same basic thing for the three SAP object classes (other than Person (aka Users)), and makes sure they have a OBJID from SAP. This is the key identifier in SAP and used in the Association values.

Interestingly, no such veto exists for the SAP Person (User) objects here.

DirXML-Workorder (Future Events): veto if DirXML-Other1 or DirXML-DueDate is missing or empty.

As you will recall, way back in part 3 of this series, we talked about future dated events, and that we generate a DirXML-WorkOder object that holds payload with the information to be processed. There are a couple of attributes that this information is stored in. DirXML-Other1 stores the target user for the future event, and DirXML-DueDate holds the date at which the future event comes due. DirXML-Content stores the long string it builds, storing all the info about the future event, that would need to be teased apart to handle it in the future. (Yes, I had to go back and look to remind myself!)

Thus without a target user, or a due date, this is not very useful as a work order, so Veto it.

pub-cp-LogAfter

Nothing to see here, move along. Just log we made it out of the Create rule.

With that we are done with the Create rule.

Next article we will work through Publisher Placement rules.