Novell Identity Manager is a big product with lots of moving parts. It can be quite daunting to get started working with it. Just as bad, the deeper you dig, the more complexity you discover. Now this is not necessarily a bad thing, it is just something you have to deal with. There is a learning curve.

Thus my attempt here to try and lower that curve. First off I have an article with stuff you should start off reading to get over the first hump in the learning curve. If you have not already read this stuff, take a few minutes and do so, it will pay off ten fold as you work through IDM: FAQ: Getting started with IDM, what should you read?

On top of the learning curve, there are some reasonably well known common problems that beginners in the product will run into. I figured that trying to write them down can only help. If nothing else, Google ought to find it, if you search for it.

Thus I started this series, with the first article that you can read here: Common Mistakes Newcomers to IDM Make - Part 1

In that article I covered the concepts:

• Using the forums

• Basic articles to read to understand the engine

• Default DN formatting

• Verb vs Noun tokens in Argument Builder

• Time Conversions

• Built in variables (Local, global, and error)

• Active Directory driver and SSL

In the second article, Common Mistakes Newcomers to IDM Make - Part 2 I covered examples of:

• Getting a driver started (migration)

• Designer vs iManager versions of the project

• Case sensitivity issues when specifying shim class

• Move token, specify destination container

• The Attribute tokens

In the third article Common Mistakes Newcomers to IDM Make - Part 3 I covered examples of:

• XPATH

• Using the Remote Loader instead of Local

• Restarting eDir after a code change

• Tracing to a file per driver

In the fourth article Common Mistakes Newcomers to IDM Make - Part 4 I covered examples of:

• Per Replica attributes

• DirXML-Associations

In the fifth article Common Mistakes Newcomers to IDM Make - Part 5 I covered examples of:

• Variable interpolation with $ vs $$ vs ~~ vs XPATH

• Regular Expressions

In the sixth article Common Mistakes Newcomers to IDM Make - Part 6 I covered the issue of:

• Optimize Modify

On to part 7!

For this article, I wanted to talk about the second of two concepts in the filter that seem simple, and are to be fair, pretty poorly documented.

Merge Authority.

Merge Authority is another interesting thing in the filter (Optimize Modify, discussed in part 6 of this series is the other interesting subtle part of the filter). This is a setting on every attribute in the filter (again like Optimize Modify) and it seems like a very minor thing, but it can have huge affects on how events process.

The Merge process occurs when a modify event occurs for an unassociated object. Lets talk on the Publisher channel, since that is easier case to discuss first.

This unassociated object event gets through the Input transform (which converts any data formats) and the Event Transform, and you see in trace, fixing up association references, if the object is not associated, it will be converted to a synthetic add which makes its way through the Match, Create, and Placement rules to generate a proper add event. If the driver shim you are using does not provide an association node, then you should add one in policy, say by Append XML element, association to the XPATH of . (a simple period), and then Set XML text at the XPATH of association with the value of whatever you use for an association in this driver. Or else use the Set Association token, and build the value in Argument Builder. These are basically equivalent functions, just the Association token is a wrapper to make it easier.

There is an interesting consequence here, since you can actually modify the association at this point if you needed too. I had an interesting case where I wanted a Loopback driver to make some Work Orders for me, and specifically I wanted it to make two different types, but I was mapping a custom object class to a Work Order in it. So this meant any modifications to that custom class triggered an event and tried to modify the work order. But that is a one to one object mapping and I needed one object mapped to two. If I left it alone, it was setting the association for both Work Orders to the same Association value, which caused all sorts of nastiness. Thus I was able to reset the association to different values for each case, allowing the whole house of cards to remain standing (till the dog came running through chasing the cat... But that's another story).

If in the Match rule, a matching object is found, then the event remains a modify, but now it is also a merge event. Since we are going to add a DirXML-Association as part of this process, the engine wants to get the entirety of the object's attribute data into sync. More on that in a moment.

If after the Event Transform, the engine can find an object with an association value that matches, it will declare it in trace. That means there is actually a DirXML-Association attribute value for this specific driver with the specific Association value specified in the document, since DirXML-Associations uses a syntax called Path that is one of my favorite syntaxes. Path syntax can hold a 32 bit integer for nameSpace, a DN syntax attribute (volume) for the DN of the driver object this Association is for, and a string attribute for the Association value.

This is a little different on the Subscriber channel, since coming into the process eDirectory knows if there is a DirXML-Association value and it is available as the event begins. Whereas on the Publisher channel it only knows what the shim says the Association value ought to be, based on either how the shim was coded or else how it was generated by policy.

Now at some level this sounds like the Matching rule, doesn't it, and this can be a bit confusing. This is a slightly different case however. The Matching rule uses the criteria you provide in the Find Matching Object token to search the target for a match and is reasonably flexible and configurable. This however looks only, and without any configuration allowed (Well directly. Indirectly you can much about with the association value as above, to muck with what is looked for) for a DirXML-Association value that is for this driver and matches the association value.

You can read more about Association values that different drivers use in this article I maintain, collecting the list of known drivers:

• Open Call - IDM Association Values for eDirectory Objects

If you happen to own or write a driver I do not have listed, please contact me and I will add it to the list. It's a cheap and easy way to get some advertising for your driver.

On the topic of DirXML-Associations, this article is of interest:

• Let's talk about DirXML-Associations

And as long as we are talking about different eDirectory schema syntaxes, this is a good set of articles on the topic:

• Interesting Schema Syntaxes in eDirectory from an Identity Manager Perspective - Part 1

• Interesting Schema Syntaxes in eDirectory from an Identity Manager Perspective - Part 2

Once you get to this point (through a Match found, turning into a Merge event) you will see an XML Attribute called from-merge with a value of true. You can detect this two ways, one with condition token, if XML Attribute, named from-merge has the value of true, or secondly with an if XPATH is true condition test for the XPATH statement @from-merge='true' and they are basically identical tests. The XML Attribute token is basically a prettier way for people who would prefer not to use XPATH.

In the case of a merge from a match found, and in the case of an associated object found, the engine will read the current values from eDirectory for the attributes changing and look at the filters settings for merge authority. Actually that order may be backwards. Using the merge authority settings, the engine will look into eDirectory for the current values, and decide what needs to be updated.

So finally, getting to the direct point, what is the Merge Authority, and what are its settings?

Well there are four settings:

Default
Identity Vault
Application
None

If you click on the help button next to the Merge Authority setting in Designer you get what I consider to be the most circular, non-helpful help I have seen in a long time!

Default is defined as: If an attribute is not being synchronized in either channel, no merging occurs.

Identity Vault is defined as: Behaves the same was as the default behavior if the attribute is being synchronized on the Subscriber channel and not in the Publisher channel.

Application is defined as: Behaves the same was as the default behavior if the attribute is being synchronized on the Publisher channel and not in the Subscriber channel.

None is defined as: No merging occurs regardless of synchronization.

So let me get this straight. The definition of default is based on the case where nothing happens. The definition of Identity Vault and Application are the same as Default in the two cases where that are not defined for Default.

Finally None is a valid explanation... But seriously, who wrote this help, and what were the thinking that this would be helpful?

As they say in that Saturday Night Live skit, Seriously? Seriously?

So what does happen in a case where something DOES happen for Default?

The official docs will be better right? In my Designer 4.01 as I try to browse the help on this, I get page not found, which is a bug I have reported before that there seem to be two packages for help content and sometimes one is missing. Regardless, the full docs are a bit more helpful.

You can find the docs for this at the following link:
http://www.novell.com/documentation/idm401/policy_designer/data/fediting.html

Here for Default more clarity is provided. The three easy cases are handled. First if nothing is being synchronized, then nothing happens. I am glad at least that they spelled that one out. The next two cases are that if the attribute is being synchronized, (which is a mistake in terminology, since this is only for the merge case, after all, so it is not about synchronization, rather it depends on what data resides in each system. But nonetheless we continue) on one channel, then the data from there is written to the other side.

This means if the Application has a value for the attribute, and the Identity Vault is empty, then as a result of the merge the Identity Vault will be updated so that the two sides match. This works in the reverse situation as well.

This behavior is sometimes disconcerting as you might be looking at a Publisher channel event and will see events fly in both directions in your trace, and wonder, why am I writing back to the Application all these attributes! It is worth mentioning these events will go through the Output transform but not the Subscriber Command transform, so if there are transforms being done in the Command Transform, they will not apply. This too is a big area of confusion.

However it is the fourth case that actually adds to the confusion. This is after all the most complex case with many possibilities and it would be nice to have it clearly lain out in the docs. What happens when a merge event occurs and there is data in the Applications attribute and also in the Identity Vault side?

Well per the docs, it says "If an attribute is being synchronized in both channels and only one side can accommodate multiple values, the single-valued side’s value is added to the multi-valued side if it is not already there. If there is no value on the single side, you can choose the value to add to the single side. "

What? That does not really explain it. In the simplest case, two multivalued attributes, you make sure they both have all the values. "You can choose" it says? How would you chose the value to add on the single side?

First off in my experience I use None for merge authority when we have an attribute with multiple values on one side, and single valued on the other. This just has to be handled in policy, and there is not much you can do about it. You test as above for a merge event (@from-merge='true' in XPATH) and handle it your self. This way you control what is happening the way you want it.

For the case of multi valued attributes on both sides, it is simple and the two sets of values will be merged.

But what happens if it is a single valued attribute and both sides have a value populated, and they are different?

This is one of those cases where there is no great answer, more specifically no simple answer either. As it turns out that the Identity Vault version is considered authoritative. This is a bit annoying, as it is not always the case. And handling this in Policy can be a bit tricky. But it is doable. This means that if you leave it as Default, and the IDV and the Connected system both have data in the same single valued attribute then the Connected system will be overwritten with the Identity Vault values.

Of course it matters what the filter says about synchronizing the attribute as well to affect this! If the attribute is not being synced to the other side, then the merge treats it as if it were empty on that side, and pushes in the other attribute values. This is complicated by the fact that Notify is not counted as Sync for this. So literally ONLY the Sync option is considered. Notify, and None are considered as not syncing. Reset is enforced as well.

I.e. Attribute is flagged Subscriber Sync and Publisher Notify then on a merge the comparison will be between the values in the Identity Vault and null, since the Publisher channel view of that attribute looks 'empty' for this usage.

Just working through the docs show how confusing this can all be, and often it is just left at Default which is probably fine. However it is quite interesting the tricks you can play with these settings if you are so inclined.

No doubt there is much more to say on this topic, and if you have any questions, please leave them in the comments and I will get back to you.