I have been writing lots of articles on Identity Manager and recently someone asked if I had a good getting started document. I tried writing it for the forums as a sticky post, and it got upgraded to an Article in the forums, which you can read at: FAQ: Getting started with IDM, what should you read?

Then I added a bunch of XPATH examples: Intro to XPATH

But that does not address a different problem, which is the common mistakes someone just getting started with IDM is likely to make. Reading the forums, some notions come up again and again, and maybe just putting it all together in a series of articles might make it easier for people to find them, and avoid the easy mistakes.

Some of the things are subtle and require a lot of explanation, and others are just simple misunderstandings and lack of clarity on how some of the basic functionality works.

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

Where there is already a good article covering the topic, I will try and link to it, to save rewriting everything again.

Once again some quick references to read, if you have not yet, because reading them will make your life so much better, I cannot stress enough the value of these articles:

David Gersic did an excellent series on what the parts of the fishbone diagram in IDM mean:

• A Guided Tour of Novell Identity Manager - Part 1

• A Guided Tour of Novell Identity Manager - Part 2

• A Guided Tour of Novell Identity Manager - Part 3

Once you understand where things happen in the system, you need to understand how to watch them in action. Fernando Frietas, a nice guy at Novell Support wrote this excellent series on how to read DStrace for IDM:

• Capturing and Reading Novell Identity Manager Traces

• Comprehending IDM Traces - Part 1

• Comprehending IDM Traces - Part 2

If you have any other things you think should be added to the series in terms of common mistakes, comment on this article or post in the forums, and I will write about it. Yes I do take requests.

Getting a driver started the first time:

This one comes from Aaron Burgemeister, who works at Novell Technical Services, and is something he sees a lot on support calls.

The way that Identity Manager works, is by processing events as they happen. When you first turn the driver on, in an existing configuration, the data is inherently not in synchrony. After all, nothing that exists has had an event to link it to something else.

Thus in iManager we have two options, Migrate from Identity Vault, and Migrate from Application. These options let you generate a special event that causes the current state of the object to be read and synchronized according to the policies you defined between the two systems.

The actual mechanics behind how this works is actually kind of interesting but fairly detailed and low level, and not a beginners issue, however if you would like to read more, I tried to address some of the complexity in this article: Migrating users in IDM

But the two directions use slightly different mechanisms. To migrate from the application, you use the GUI picker in iManager to specify a Query event. This is somewhat limited by the user interface, and thus there is a way to do it by hand, using dxcmd, the command line IDM tool. But the results of whatever query you submit this way (via iManager or via dxcmd and sending a command) comes back as an <instance> document, and the engine converts each node to a <sync> event, which is processed and ends up linking up the two objects. Either they match, or else one is created as needed.

Using Migrate from Identity Vault, you get to pick the specific object (or more than one) and each gets a DirXML-Association with the state set to 4 for migrate. (DirXML-Association is a Path syntax attribute with a integer for state (called the nameSpace component), a DN for the driver DN (called volume component), and a string, which holds the actual association value. Since this is multi valued, this one attribute can contain the linkage of one object to all connected systems. Each system has a driver (referenced by the DN) and an association value in there.

If you are interested in what that string might look like, you can read this article I maintain trying to track all the known drivers with what their association values ought to contain: Open Call - IDM Association Values for eDirectory Objects

Thus when you add a new driver to an existing system, one of the first steps you have to do is migrate everybody that needs to be associated by the driver. Other vendors call this a reconciliation, which makes a little more sense as a name for the function.

Designer vs iManagers view of the project:

This is another one from Aaron B, and is basically a misconception about how IDM works.

Originally Console One was the way to manage IDM, when it was still called DirXML, however that quickly moved into iManager as the only to manage it. Novell still supports iManager, but the future is clearly Designer.

ConsoleOne and iManager look at the live system (and thus you need to be able to see them live on the network) and any changes you make, are written out to eDirectory as soon as you click Apply or Ok. However, if you change a driver, the change does not go into affect in the system until you restart the driver.

If you are interested in a list of things that need a driver restart, versus things that do not, take a look at this article: Changes that do not require a driver restart, and errors on starting an Identity Manager driver

However Designer is meant for a totally different use case. As a consultant, (Yes I am available for hire, take a look at our companies (http://www.ciscony.com/) web site if you are interested in our services, or contact me about it) I often need to work when I am not able to connect to the clients system. Designer is a dream come true for this. I connect the first time, grab a copy of the project, work offline as much as needed, and then deliver the changes back via a number of mechanisms. (SVN, Subversion is one approach, where they check their project into an SVN server I can reach, and I sync my changes into it, and they sync it back to deploy to their network, send a Project export, a driver export, or now with IDM 4, a set of changes bundled into a Package).

Thus a very common problem is that a change made in iManager is not shown in Designer, because you did not yet compare to see any differences. When you do use the Compare functionality, you get shown all the differences between your project and the current state in eDirectory. For each difference, you have the choice of updating Designer to match eDirectory or eDirectory to match Designer. (Pull or push). Thus you can get your Designer project back in sync, or update eDirectory to match your project.

Thus if more than one person is working in a IDM system, it is good practice to compare every morning (and possibly more often) to keep up with their changes. Always review the changes you are sending or accepting to watch out for conflicting changes. If two people change a single object, it is hard to reconcile the differences. Someone has to back off, copy their changes, accept the others, then put their changes back in. I.e. You cannot say, I will take this one change in policy object, but not the other. The granularity is not that good.

Case sensitivity issues when specifying shim class:

This is another Aaron B one, and I have not personally seen it, but in the Driver configuration, when you specify a driver shim to be used, that field is a case sensitive string specifying a Java class that will be run. So take care to get the exact spelling and case perfect or else it just isn't going to work.

There is a nice list of the various shim names, hopefully correctly spelled out at the end of the page at this link: http://www.novell.com/documentation/idm401/idm_remoteloader/data/bmiwm6n.html

Do note that with IDM 4, some of the SAP driver shims got changed, and it is important that you pick the correct ones. (The rest have mostly remained the same for quite some time now)

Move token, specify destination container:

This one is from Will Schneider and he notes that a common error is when using the Move token, to specify the target with a full DN. Well turns out the token just wants to know the destination container to move the current object with the current name into. To change the name on the fly as well would require a separate Rename event.

This one can be easily fallen into, if you are used to LDAP, where a modrdn (Modify Relative DN) action can do both in one operation, or just one of the two.

The Attribute tokens:

David Gersic came up with this one, that it would be really nice for people to better understand the various Attribute tokens. There are:

• Destination Attribute

• Source Attribute

• Operational Attribute

• Attribute

I wrote a couple of articles on the topic in reasonable detail, which I will link, but here is a quick summary to hit the high points.

• The different attribute options in Identity Manager

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

Some are obvious and easy. Destination Attribute means, go look in the destination system for this attribute. Note that of course, in an <add> event, this makes no sense, since the destination object does not exist. In a <modify> event, as long as you have an association or destination DN, then it should work.

Source Attribute is the same thing, but looking back to the source tree does make sense, even in an <add> event. This always looks back at the source for the data.

Operational Attribute is actually kind of neat. This is the data about the attribute in the current event document. Now realize that if this is a modify, and there is a <remove-value> and an <add-value> in the event, the Source data might still have more in it.

For example, say you are looking at Telephone Number, which is multivalued, and your IDV has 7 values for it. Then someone changes it by removing one, and adding a number in one event. You would see a remove and add as the Operational Attribute, but the Source Attribute would have the list of 7 and possibly your destination attribute would have the old list of 7. So you can see how it is important to think about which case you really care about.

Operational attribute is great if you need to do something when it is changing. Source/Destination attribute is best when you need the complete set of data.

Now the final token, Attribute is quite interesting. This says, if the attribute is in the current document, then use it (just like Operational Attribute), if not, query back to the source (only works on Source, no destination version of this) to get the values.

Source and Destination attribute by default work on the current object, but could easily point them at another object. Perhaps, you want to get the Managers name. Well you could do a Source or Destination attribute call to get the Full Name attribute, but specify the DN of the object as the value of the Source Attribute manager.

That would look like this in policy (Paste it into a rule in Designer, and you will see how to use the UI to do what I did):

<do-set-local-variable name="Get-From-OtherObject" scope="policy">
	<arg-string>
		<token-src-attr name="Full Name">
			<arg-dn>
				<token-src-attr name="manager"/>
			</arg-dn>
		</token-src-attr>
	</arg-string>
</do-set-local-variable>

Whereas, reading it from the current object would look like:

<do-set-local-variable name="Get-From-Current-Object" scope="policy">
	<arg-string>
		<token-src-attr name="Full Name"/>
	</arg-string>
</do-set-local-variable>

It is the <arg-dn> node that tells you it is looking at another object to provide the DN to use in the token.

If you paste my first example, you will see I used Source Attribute a second time, with Current Object selected. But nothing stops me from using a DN reference there. You can hop about this way as much as you need to get the data you are looking for. It can make your head hurt at time.

One last thing. The Source or Destination changes, depending on the channel you are in of course.

If you are processing an event in the Publisher channel, events are coming out of your application (Source) and going to eDirectory (Destination).

If you are processing an event in a rule in the Subscriber channel, events are coming out of eDirectory (Source) and going to your application (Destination).

Anyway, that's about it for this article, stay tuned for more as I work through the other examples I have handy.

As always, should have some examples of errors you think would be helpful to warn new folk to IDM about, comment or let me know and I will write about them.