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.

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

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

• Merge Authority

In the eighth article Common Mistakes Newcomers to IDM Make - Part 8 I talked about some of the consequences of multiple servers in a driver set and some of the issues that come from that decision.

In the ninth article Common Mistakes Newcomers to IDM Make - Part 9 I talked about using Variables in Identity manager, in terms of how to add to them, build nodesets, and long strings.

In the tenth article Common Mistakes Newcomers to IDM Make - Part 10 I discussed how you use the XML building tokens. There is a confusing twist that I think I have a simple example that demonstrates both sides nicely.

In this article I would like to address the concept of Association references, in other words, how do DN syntax attributes synchronize.

When working with an object in Identity Manager, say a User or a Group, there are two ways to address it. Via a Source or Destination DN, that is by a full distinguished name which completely identifies the object in the system. Or you can use the Association value.

During an <add> event, the Placement policy set requires you to generated a Destination DN, (set as an XML attribute dest-dn, in the <add> node.). You can set this with a Set Operation Destination DN token, by using Set XML attribute, or even by a Clone by XPATH token. But if you do not do this somehow, when your event exits the Placement Policy set the event will come to an end if you do not have a dest-dn in there.

Now at this point a Destination DN makes sense, since we do not yet have an Association value for this driver and object, so of course we cannot use the Association. In fact, in the successful status event, a sibling event to the <status> node will be an <add-association> node, which returns the Association value, via the shim. The shim itself is coded to know what the Association key is, and to return it in this case. In a Loopback driver, where you want to use an association, you have to specify the value in Policy yourself, since a Loopback driver shim does not actually do anything other than return the document into the Publisher channel.

However, modify events after the object is created and associated, on the Subscriber channel will come with an <association> node, and it has an XML attribute 'state' that reflects the value of the nameSpace component of the DirXML-Associations attribute value. That is, an associated object has a 1, in that part of the structured attribute (Path syntax), a 4 would mean state='migrate' and the others as still supported.

All events coming out of the Publisher channel will have the <association> node with the association value as generated by the shim. This is not saying this object IS associated, but rather, should this user already exist in the Identity Vault, then this is the association value it would have. This is because we store the Association to the driver on the eDirectory object, but do not add any information in the connected system. Therefore coming out of the connected system we have no clue yet if it is associated, only what the association value would be, to do the check.

You can see as comprehensive a list of Association values and what they are based on in this article: Open Call – IDM Association Values for eDirectory Objects

If you find a driver I missed and know what it's association value should be, let me know so I can update the article.

Now when you use a token like Source Attribute or Destination Attribute, you get some targeting information. You can choose to do the action upon the:

current object
Association
DN

Current object just uses whatever information is on the current object (be that a DN in dest-dn for an <add> event, or an Association in a <modify> event) to add one more attribute value.

Association and DN are methods to allow you to specify another object. This can be helpful, since you can use either of the two identifiers, and sometimes the Association value is based either on attribute value, or some combination of other things you can recalculate. So without know the real association value, nor the destination DN, you could build a string that replicates the logic used to generate the Association and have it work.

All that seems pretty straight forward. But what about other attributes that are DN's, as opposed to objects themselves?

Well imagine the case of a Group. It has an attribute Member, which holds a list of DN values. These need to be written to eDirectory with the DN of the eDirectory object. If you try to add a non-existent DN into a DN syntax attribute (be it a typo, or an empty value) then you get a 613 Syntax violation error in return.

Yet clearly in your connected system, the value of the Member attribute is NOT the eDirectory full DN.

Thus there is a trick, if you need to send it through a driver. When you manipulate an attribute, via the tokens (Add Destination Attribute, Set Destination Attribute, Add Source Attribute, Set Source Attribute, etc) the UI in Designer will let you select the syntax type of the value you are adding. It defaults to string which is workable most of the time. It is the second last line, Value Type. You have a bunch of options, string, counter, DN, int, interval, octet, state, structured, teleNumber, time.

Structured is probably the most useful, as all the others basically take whatever you shove into them, but structured is pretty different. This lets you set structured syntax attributes. For example DirXML-Associations uses Path syntax. This has three components, nameSpace, volume, and path. So when you set the Value type to structured, you get a string builder interface, where you get to specify each component, and then a value for it. This might look something like:

<do-set-dest-attr-value name="Example">
	<arg-value type="structured">
		<arg-component name="nameSpace">
			<token-text xml:space="preserve">1</token-text>
		</arg-component>
		<arg-component name="volume">
			<token-global-variable name="dirxml.auto.driverdn"/>
		</arg-component>
		<arg-component name="path">
			<token-text xml:space="preserve">Some association value</token-text>
		</arg-component>
	</arg-value>
</do-set-dest-attr-value>

But if you switch this to DN, then the <value> node generated in the <modify-attr> or <add-attr> event will have an XML attribute type, set to dn and look more like:
<value type='dn'>Some Value</value>

Now when the engine goes to send this to the driver on the Subscriber channel, or when the engine is submitting it to eDirectory, it will go through a line in dstrace that will say something Resolving Association references and try and figure it all out for you and convert the DN value from the eDirectory name to the application name, using the Association of the object to resolve this all out.

Coming from the application, attributes like this will usually have on the <value> node one more XML attribute, 'association-ref' which will be equal to the calculated association value from the driver shim. You can actually play tricks with this. If before the Publisher Event Transformation (so in the Input Transform policy set) you strip by XPATH the association-ref XML attribute then none of them will be resolved, and in fact the engine will just drop them from the event. If you are generating new values for say the Member list, possibly from another source, maybe copying a member list from a template, you can add the association-ref attribute yourself via XPATH a number of different ways.

So how do you get the Association values? Well you could do it the hard way, which is basically re-implement the matching rule and try and figure out the DN in eDirectory based on some data about the object. Then read back the DirXML-Associations, find only those (hopefully just one) relevant to this driver (The volume component will have the driver's DN in it) and then read back the path component and use that value.

You could make it a bit simpler if you instead looked at the returned object in the query and XPATH'ed out the association node, which should have the association value if it is associated to this driver.

Once you have an Association or a DN, you can query in either direction to try and find the matching object and then read out either the src-dn XML attribute or the Association node, depending on what you started with.

Turns out there is a simpler way, the Resolve() token. This is a Verb available le in Argument Builder, so it means you have to nest a noun with some data underneath as discussed in the first article in this series. (A very common rookie mistake! I added a verb token, configured it, and it does nothing. Well yes, you need to feed a verb a noun to act upon the nouns data)

The Resolve token lets you specify DN to Association or Association to DN resolution, and against the Source or Destination. This lets you use one token in both channels on either identifier making it very handy. Of course where you use defines what the source or destination is, since the source in the Subscriber channel is the Identity Vault, and the Source in the Publisher channel is the Application. This can make it a smidgen confusing if you are not paying attention.

One of the minor issues that comes up, specifically with the eDirectory driver, is that if you are in the Publisher channel processing an event from the remote eDirectory (and thus inbound to the Identity Vault), and you want to write back to the source, and you need to resolve an object, you actually need to resolve against the Destination (the Identity Vault eDirectory) because the association you are looking for is for the object of interest, from the perspective of this half of the driver.

The two drivers, half in each tree makes the eDirectory driver the most complicated of them all. The good news is a single driver version is coming in the near future. If you look at the list of updates made in Auto Update 2 for Designer 4.01 one of the items is adding support in Designer for this new type of driver. I imagine that is mostly adding it to the palette of drivers, but I am sure there was probably something else they had to change in Designers underpinnings to get this to work. They also mention that they added support for Packaged JDBC drivers, (which if you were observant you would have noticed did not ship with IDM 4, nor SP1, rather the JDBC driver remains an old configuration file) which will come in a Package update, in what I imagine is a large number of packages, since they will probably have a couple of packages per database type, and they support an awful lot of databases with that one driver.

Thus looks like the issue with the two part eDirectory driver will be getting better in the near future, until then, it still will be common to have the old style eDirectory driver.

There is really only one downside that I know of to the Resolve() token, which is that when it fails to resolve, it errors in a way that stops the event, which is not that very helpful. I would rather it return nothing, and fail silently, or maybe with an error variable? If you are not aware, there are about at least nine error variables available, that store error values from certain tokens.

You can get at them from the Variable selector in Designer, anytime you can pick a variable, look at the top of the pop up box, and there are three tabs in the selector, Policy Scope, Driver Scope, and Error Variables. For example, there is error.do-start-workflow which is immensely helpful as a workflow may fail to start for all sorts of annoying reasons. You can use this variable to perhaps email the error value or send an Audit event so you are notified of what is an otherwise silent failure.

There are several more, for adding or removing a role, three involving modifying SSO (Single Sign On, aka Secret Store) credentials, two for email sending errors, and one for find matching object, from the Matching rule.

Anyway, that's about it for now, if you have any ideas for future articles please let me know.

I think that all this talk about the Resolve() token gave me an idea, and I may spawn this off into a series on lesser known tokens.