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

On to part three!

XPATH:

What to say about XPATH? This is very powerful and capable, but also can be used very simply. When discussing this series in the forums, a suggestion was made to avoid talking about it entirely, as XPATH is not a rookie tool. I accept that argument but am not sure I entirely agree.

If you have looked at many of my articles (The entire collection of 280 can be seen here: http://wiki.novell.com/index.php/Geoffrey_Carman's_personal_collection) you will see where there is a token that does something, I will often try to explain a way to do it via XPATH. Not because I think XPATH is the right way to do it, but rather because I think you will learn something interesting by doing something two different ways.

Thus let me now emphasize the converse. Sometimes it looks like XPATH is the only way to do it, but in reality, with the maturity of DirXML Script in IDM 3.6 and higher (IDM 4 introduced only a single change I know of, a new auto GCV for local server DN) most of the things you used to need XPATH to do in the past are now part of tokens.

For example, in my article on the various Attribute tokens (Source Attribute, Destination Attribute, Operational Attribute, and Attribute):

• The different attribute options in Identity Manager

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

I listed the XPATH equivalents for the various tokens. You can see in those articles that it is WAY easier to just use the tokens these days.

The same is true of the Query token. The Query token is just a wrapper around the query Java class that IDM has shipped with since very early on. However the wrapper is so good, you would almost have to be a fool to continue using the Java class direct. Why take the chance on typos, for complex things, when there is an excellent way to do it in a token? (I of course conceded there are valid use cases for both, but for a beginner, use the token as the valid case is probably way too complex for your needs).

Having said that, XPATH is still useful. For example, doing math in IDM requires XPATH. Doing some slightly more complex string manipulations than current tokens support is relatively easy in XPATH. I am thinking of substring-before and substring-after, whereas there is only a substring token in DirXML Script. (Of course, to take it the other way, you can actually use Regular Expressions in a Replace All token to some string manipulations with capture groups, but that is WAY too complex to consider).

One problem with this suggestion, is that if you do not know there is a token that does what you need, XPATH may be your only option. However, posting in the forum will often get you a suggestion of a token to use instead, or else reading about the various tokens can help. I have tried to help out by writing articles about many of them to supplement the documentation:

• New IDM 3.6 enhancement to do-find-matching-object

• ParseDN Token in Identity Manager and Some of its Limitations

• Examples of using the ParseDN Token in Identity Manager

• The different attribute options in Identity Manager

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

• The Query token in Identity Manager

• Unique Name Token Functionality in IDM 3.5

• Reformat Operation Attribute

• Open Call: What Can You Do in XSLT that You Cannot Do in DirXML Script?

• Using the Time Tokens in IDM 3.5

• IDM 3.5 - Update on New Features

• More about the Veto Command for Scoping Events

• Troubleshooting IF-THEN-ELSE Blocks with IDM Code

• Good Grammar - and IDM Rules

• Mapping tables and Render browsed DN relative to policy option

• Open Call for useful ECMA functions to use in Identity Manager

• DirXML Script Elegance in Coding Contest

• Join and Split tokens in Identity Manager 3.5 and higher

• Using and Copying Email Templates in Identity Manager

• Parse DN Custom DN Delimiter Example

• Explaining GCVs - Part 1

• Explaining GCVs - Part 2

• Structured Global Configuration Values in IDM

• Introducing the Start Workflow Token - Part 1

• Introducing the Start Workflow Token - Part 2

I do not recommend reading them all, but if you are working on an issue, and something in there looks helpful, you can use them as a resource.

Now for some basic examples of using XPATH, I recommend this article, where I tried to list off some common examples of use cases, to help dispel some of the confusion: Examples of using XPATH in Identity Manager

Let me reiterate one key item from that article that confuses EVERYONE starting with XPATH. XPATH is the XML Path language and is used by IDM and many other applications. (Do note IDM only uses XPATH 1.0, not 2.0 so do not go looking for 2.0 functions in it. I am told that 2.0 is way more complex, and is not actually completely backwards compatible so changing too it would break older implementations, thus the hesitancy on Novell's part to provide it).

In a standard XPATH use case, you need to specify the entire path to what you want. In IDM, there is a shortcut implicit in the implementation that causes most of the confusion. I can dispel it with one sentence:

The current context is the event node.

What that means is that the <modify> or <instance> or <add> or <delete> node is where your XPATH should begin.

Thus to select a <modify-attr> node, which is under the <modify> node with XPATH in IDM you do not specify /nds/input/modify/modify-attr, it is just simply modify-attr which looks too simple to be true, but that's the way it works.

This is very easy to demonstrate. In Designer, by any of the XPATH tokens (Condition of if XPATH, Argument Builder XPATH token and so on) there is an XPATH editor. But it is a generic XPATH editor.

You provide a sample XML document, and then have an XPATH window to type in, with results shown below.

I found this immensely frustrating and inconsistent to use, until I understand that magic sentence. The current context is the event node.

In the left hand side, that shows the XML document. You need to select the event node, so that your XPATH shown in the right hand side is relative to the current context. Once you do that, everything starts to work.

Read the article for much more detail. There is so much more to talk about. That article also has links to more articles on much more complex use cases for XPATH which if you are interested should keep you busy for a while and give you lots of fun ideas.

Not restarting eDir after a code change (still using old code).

This one comes from Aaron B at NTS, and is probably much more common than anything else. IDM is a Java application, running in the memory space of eDirectory. Like most Java apps it looks at the filesystem at startup, looks up the various classes into memory (this is the PermGen memory space you might see in settings Java config settings) and then try to use them. If the class is not found, it will try to read the disk again, but there is no way to say, reload this class from disk.

Thus when a driver patch comes out, and the driver is running local (Local to the engine, as opposed to a Remote Loader) then the only way to get the new code into use is not just to restart the driver, but actually to restart all of eDirectory. This can be a bit painful, but due to the use of Java there is no real way around it.

Using Remote Loader instead of running Local:

Most drivers support running in two modes. Local and Remote. Local means the driver shim is running in the engines JVM in eDirectory's memory space. As above, this is a pain when code is changed, as eDirectory needs to be restarted.

A remote loader (of which there are many) can run Java or native code (in the case of the Active Directory driver which is a DLL file) or .NET managed code in IDM 4 (for the Sharepoint driver) or use a non-system JVM (in the case of a bit depth mismatch. Like in SAP where the OS might be 64 bit, but the application is 32 bit, and you need a 32 bit JVM to match the application).

You can read more about the various remote loaders in this article: The Many Faces of Remote Loaders in IDM

There are many benefits to using a remote loader. One major one is that it offloads the application specific processing to some other server. This takes some work away from the engine, which is always a good plan.

Another is that when the code changes, a remote loader restart is not a big deal, in comparison to restarting eDirectory with many drivers running on it.

A perfect example might the JDBC driver. You could run it local or remote, and in the Remote case all the work of converting XDS to SQL commands is done on the Remote Loader server, and only the resulting documents are sent back and forth to the engine.

This also means that your connection to the database can be secured independent of the connection to the engine, allowing for better options in setting up firewall holes. After all, who wants to leave ANY SQL ports open through the firewall? This way you just let the Remote Loader through, and it talks local (that box, or network) to the database instead.

Tracing using ndstrace instead of to a file directly per drive.

DSTrace is the magical debug tool for IDM. You cannot work with IDM without this. It is just not possible. The most common mistake is actually thinking that logging and tracing are the same.

Logging initially was both useless and harmful, because it would write an attribute to the driver object (DirXML-LogEvent I think) and writes to eDirectory are 'slow' compared to other things. With the advent of the various audit tools (NAAS, NSure Audit, Identity Audit, Sentinel, OpenXDAS, etc) now logging can send stuff to the audit collector which can be useful. Alas it is not useful for actual troubleshooting.

DStrace is the tool you want to use.

The best articles on reading and understanding DStrace are by Fernando Freitas, also an NTS support guy:

• Capturing and Reading Novell Identity Manager Traces

• Comprehending IDM Traces - Part 1

• Comprehending IDM Traces - Part 2

There is so much to say on this topic, that I will just defer to others, and suggest you start with Fernando's series.

However there is one thing that is worth calling out by itself. You can use Dstrace via the web interface, on a server console (NDSTRACE.NLM, ndstrace, or DSTRACE.DLM) which is how you would use it to diagnose an LDAP connection problem like in this article: Troubleshooting an External LDAP Application (SAP GRC)

But for IDM you really want to have it tracing each driver to its own file. In the other views, the data is all mushed together and there is no easy way to pick it apart into linear streams. With separate files, that is all taken care of, and you can use simple text tools to look through them. (On Unix like OS's the tool 'less' is the greatest thing since sliced bread for this. It can handle a 30 GB text file and not care. Sure searching for a string at the very end can take time, but better than on any other platform! Try using almost any GUI editor on a 30 GB text file, with 20 million lines in it. An amusing anecdote occurred when we turned on a new driver with hundreds of thousands of identities involved, and someone asked me to look at an error that occurred around like 500 million in the file. That is a bit of a silly example, but 'less' can handle it!)

Well that is about if for this article. If you have any ideas for more common misconceptions or mistakes to call out, please let me know and I will try and write about it. I still have an bunch more topics to work through.