Novell Identity Manager uses a language known as DirXML Script to manipulate identity events, that it receives in XML format. There are a number of really useful verbs, nouns, tokens, and actions available as part of DirXML Script. This is a huge step from XML Stylesheets, (XSLT) which is all that was supported in earlier versions. (DirXML 1.1a and earlier).

Some of the other tokens I have discussed before are:

ParseDN:
Examples of using the ParseDN Token in Identity Manager

Query:
The Query token in Identity Manager

Unique Name:
Unique Name Token Functionality in IDM 3.5

Source/Destination Attribute:
More thoughts on Source/Destination/Operation attribute tokens in Identity Manager

Time/Convert Time:
Using the Time Tokens in IDM 3.5

Map and Mapping Tables:
Mapping tables and Render browsed DN relative to policy option

Reformat Operation Attribute:
Reformat Operation Attribute

As you can see there are some really powerful tokens in the toolkit provided by DirXML Script. Each new release brings new features, and even in 'old' un-updated features, I still learn something new with time. (Usually pointed out to me by someone smarter than me, or at least someone who reads the docs with way more attention to detail than I do!).

One that recently came up is a truly oldy but goody! Find Matching object. Or do-find-matching-object as it is known in the XML.

First a clip from the documentation from Identity Manager 3.6, which I have to be admit, I had never read in this much detail:

If the destination data store is eDirectory, then the dest-dn attribute for the current operation is set. No query is performed if the current operation already has a non-empty dest-dn attribute, thus allowing multiple <do-find-matching-object> actions to be strung together in the same rule. If only a single <instance> is returned and that <instance> is not already associated, then the dest-dn of the current operation is set to the src-dn of the <instance> and the local variable error.do-find-matching-object is not available. If only a single <instance> is returned and that <instance> is already associated, then the dest-dn of the current operation is set to the single character  and the local variable error.do-find-matching-object is set to the src-dn from that <instance>. If multiple <instance> elements are returned then the dest-dn of the current operation is set to the single character � and the local variable error.do-find-matching-object is set to a node-set containing the src-dn's from those <instance>'s..

That snippet is from:
http://www.novell.com/documentation/idm36/policy_dtd/index.html?page=/documentation/idm36/policy_dtd/data/dtddirxmldofindmatchingobject.html

There are a bunch of key things to take out of the docs about this token. First of all its basic operation. This token is a basically a wrapper on a Query function, (the Query token is itself actually a wrapper around a call to the Java destCommandProcessor (or srcCommandProcessor depending on the channel and the direction of the Query, but in this case it is usually the destCommandProcessor)) to try to find an object matching the criteria specified and provided.

This is used in the Matching rule (Subscriber or Publisher channel) to try and take an unassociated user, and link it to an existing user in the other datastore.

What often confuses people is how fail through happens. That is, how do you handle trying one matching pattern, then a second one, then a third one, and so on. Well the docs tell us the story. The first Find Matching object is tested, and if it finds a match, then it sets the operation destination distinguished name (DN). This looks like an XML attribute of the <add> (or <modify>) events. You might see this in Dstrace (For more on Dstrace, see: Guide to Reading DSTRACE Output from Identity Manager and Capturing and Reading Novell Identity Manager Traces), as an event that starts with something like:

<add class-name="User" dest-dn="\TREE\O-NAME\OU-NAME\OBJECT-NAME> or the like.

Well, before the matching rule, on an un-associated object, the dest-dn attribute will not be there yet.

Once do-find-matching-object succeeds at finding a matching object, the attribute will be added to the document. So the way you chain do-find-matching-object rules, is try the most likley to succeed match first. If it succeeds, the following calls to do-find-matching-object will detect the dest-dn in the document and not bother to run. This is a nice efficient twist, which means you only need to query the minimal number of times.

This means you can try as many patterns as you need to try and get a valid match.

What is new and cool in Identity Manager 3.6 is that if more than one match is found, the dest-dn is set to the character xFFFD and a local variable is populated, with the nodeset from the query that shows the multiple src-dn values of the match. The variable is error.do-find-matching-object and can be tested for in a rule, to try and get better matching results.

Basically after the last call to do-find-matching-object in your Matching rule, you can test if the local variable error.do-find-matching-object is available, and if it is, test if the value of XPATH @dest-dn is xFFFD and build a rule to handle this case. Perhaps you want to send an audit event, or email an administrator for human intervention. Perhaps you have a secondary method of narrowing the matching user down, if the first attempts finds more than one. Whatever the path followed, this new feature gives you an easy way to detect it, and start dealing with it.

Some of the other features the documentation talks about are older things. For example, the driver, if it gets to the Matching rule, means the user was not associated. If the user WAS already associated, it would have skipped the Matching rule and gone straight to the Command Transform rule. Thus when Matching does a do-find-matching and finds a user, and the user already has an association value, then something is wrong, and you can test to see if the dest-dn (XPATH of @dest-dn) is equal to the character value xFFFC and if it is, you can try to write some rules to try and handle that error case. Prior to this feature (I do not know when this one appeared) an error would be thrown in the trace, and I suppose if you had auditing enabled, an audit event generated, but could otherwise go unnoticed.

The lesson to take out of this, is that sometimes you really need to RTFM, Read The (expletive deleted) Manual. Alas, it does mean reading it with a lot more focus on detail, than you might otherwise prefer.