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

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

• Merge Authority

In the eight 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 this article I would like to talk about using Variables in Identity manager.

One of the more interesting tools in your Identity Manager arsenal is the Variable. There are a bunch of details related to variables of interest.

There two basic types, Global Configuration Variables that are set in the driver configuration, and require a driver restart to notice any changes, and there are local variables, which are more local.

Local variables will be the focus of this discussion.

Earlier in this article series I discussed how you can reference variables in XPATH, and other tokens that support variable interpolation. You can read more about that in the article: Common Mistakes Newcomers to IDM Make - Part 5

I also discussed some of the types of the built in variables in the first article in this series: Common Mistakes Newcomers to IDM Make - Part 1

But that was focused on the specific use cases for current-node, current-value, and current-op, all of which are very interesting local variables.

As it turns out there are some error variables that become available in certain circumstances. You can see these in Designer, if you look at the tabs carefully. There will be three tabs, usually:

• Policy Scope

• Driver Scope

• Error Variables

This allows you to segregate the variables, based on how they are made available. The Policy scoped are local to this policy and will go away once the policy is finished processing. Driver scoped variables will persist once set, until reset or the driver is restarted.

These are tempting to use as a mechanism to carry data through the policies and policy sets in the event flow, however try to avoid that temptation as they can be set anywhere (in either channel) and potentially could have the underlying data changed without notice. If you need to carry information from one policy or policy set to another, Operation properties are probably a better choice. Of course they too are not perfect as they do not traverse a merge or synthetic add event well. They will appear in an <operation-data> node underneath the main event, as XML attributes, of name='value' format. There are tokens to set operation property and conditions to test if an operation property is available, or equal to some value. In the Argument Builder interface there is a noun token for reading the value of an operation property.

The third tab is Error variables, and these are populated as they are needed.

The list changes depending on the version of Identity Manager as new tokens (and thus new error variables) become available. If you look at the linked image you will see the following error variables:

error.do-add-role
error.do-clear-sso-credential
error.do-remove-role
error.do-send-email
error.do-send-email-from-template
error.do-set-sso-credential
error.do-set-sso-passphrase
error.do-start-workflow

You can see from the naming that they are related to tokens that do something.

The Email example is probably the easiest to understand, as the when you try and send an email using either the Send email or Send email from template tokens, there are many valid error cases that could be returned submitting an email to an SMTP server. In those cases the errors will be recorded in these variables.

This means you can test for errors after calling them to see if you succeeded or failed.

While sending emails might be a common concern, the error.do-start-workflow is a pretty useful one. When you start a workflow this is really a wrapper around a SOAP call to the User Application web interface. Thus you have to present the URL to connect too, the LDAP DN to login as, since the User Application really uses LDAP under the covers. If you use the front end user interface, it knows to look for CN= the name you type or maybe uid= the name, and find the full LDAP DN, but it is really using LDAP to authenticate the user.

However, you do need to populate all the various fields on the Request form of the workflow. To get a better understanding of workflows, you might want to pause and consider reading this pair of articles on how Provisioning Request Definitions are built and where all the bits and pieces go:

• Introduction to Workflows and PRDs in Identity Manager - Part 1

• Introduction to Workflows and PRDs in Identity Manager - Part 2

Basically anything that is available on the Request Form in the user interface, needs to be provided in the Start Workflow token. This process can take a while to get just right as you try it for real, so having the ability to get at the error, perhaps emailing it to yourself when it happens, can make troubleshooting much easier. The other option is to read the logs and find your event and look for an error. I prefer to automate it and have it email me errors so I know it failed.

You can read an example of the sort of errors this token can generate in these articles:

• Introducing the Start Workflow Token - Part 1

• Introducing the Start Workflow Token - Part 2

New in later versions of Identity Manager is the notion of Roles. Like the Start Workflow token, these are just wrappers around a SOAP call to the User Application web interface that calls the Roles SOAP functionality. However it is useful to have an Add and Remove Roles token, alas there is no Noun token to enumerate the Roles which would be quite helpful to know what a user already has.

Thus we get error variables for when an attempt to use the Add or Remove Role tokens have failed for some reason.

Permissions with the User Application Roles model is often the cause, and worth remembering to look into. If you are finding that you cannot connect to the User Application after a fresh install, you might want to consider reading this article, which explains how a seemingly unconnected bug in Designer's handling of DN syntax GCVs could break your User Application: User App Roles Failing to Apply for Administrators

But there is still more to variables than what we have discussed so far. There are some interesting approaches to building variables.

A variable can be declared as one of three options a String, an Object, or a Nodeset.

String is the easiest. It is a string of characters. Nothing special.

A nodeset is a nodeset that lets you build a nodeset of values, or an XML nodeset. That is the contents could just be a series of values, or could be XML itself. I know there are real names for both these cases, but no clue what the real names are.

The key about a nodeset is that you can loop over it with a for each loop. With a nodeset of just values, as you loop, you get each value one after another. If a nodeset that is actually XML, you get a loop over the current context, which can be a smidgen fuzzy at times. However, you can loop over an XPATH statement starting with $VariableName to pick exactly where in the XML you wish to start your loop.

For example, if you set local variable ThisOperation as a nodeset of the local variable current-op you would have the current event XML in the nodeset and could loop through it with XPATH's like:

$ThisOperation/modify-attr
$ThisOperation/add-attr

These would loop you through the various attribute modifying nodes with in.

However, if you need to store and use a bunch of values that you pick out of other data, say group memberships from many users, you can use the nodeset of values approach.

However you collect those values, you could first test is the value you just found is there, with If Local variable ThisValue is not equal to $MyListOfGroups$ (which you defined as a nodeset) then if the value is not there, it will be true, and if it in the list will be false.

If it is not yet in your list, then you could add ThisValue to the list by using a set local variable token for MyListOfGroups as a nodeset to the value of the local variable MyListOfGroups and then the local variable ThisValue.

That is, set the variable to itself, plus another value. When you look in Argument Builder it looks a smidgen odd, in that you have two local variable tokens one after another.

When you do this in a string context, you basically concatenate values onto the end of the string, so you can do the same thing to build a list of values that you could say, email to someone to notify them of groups being removed or added. Usually I would stick in a Text noun, with a carriage return or maybe some kind of delimiter, to make them more readable as a long string. Watch out that a Text noun with a carriage return looks a little funny, in that it displays as an empty node, (since the display is one line high, and a carriage return takes you to line two, it basically looks empty all the time).

This is where people often get confused. How do you add more information to an existing variable? Easily, just set the variable to itself plus the new content. Depending on the context you are using it in, nodeset or string will depend on how the data is added.

Going back to testing your nodeset variable a moment ago, one of the key things you can get away with in a nodeset variable is comparing a single value to the nodeset variable. If it is a nodeset of values, then the single value is compared to all the values and is true if any of them match and false if none of them match.

When you have an XML nodeset, and try the same compare, it will look under the current node for text values to compare against. The most common case where I use this would be a List GCV.

As the name implies a List GCV lets you store a list of values. It can be useful to loop over all the variables, but it can be even more useful to test if some value is in that list.

Thus if you set your GCV into a local variable in a nodeset context then it is available to both loop over and test values against.

Now this is a little confusing, as if you look at the List GCV XML you will see that it is something like:

<value>
	<item>Thing1</item>
	<item>Thing2</item>
	<item>Thing3</item>
</value>

So you might expect that your string you are trying to match should include the nodes or that your loop might include them, but it is nice that engine will just look at the text strings in between the <item> </item> nodes and use those in the compare and in the loop. The thing is this is somewhat unclear or unexpected and definitely not documented.

Thus a nodeset of XML looks and loops a lot like a nodeset of values, in a string context. Confused yet? There all sorts of interesting things that happen when you do them in a string context as compared to a nodeset context.

My favorite example of that is Structured GCVs which you can read much more about in this article: Structured Global Configuration Values in IDM

What you will see there, that is you treat one of these GCVs as a string, you get a string using all the delimiter characters you specified (between instances of the template, between values within each item and so on), but if you treat one of these as a nodeset it is quite different. In that case you end up with a nodeset that looks like the XML from the GCV definition in all its glory, which means you can XPATH through it quite easily to get whatever bit of it you desire.

As you can see variables are really powerful tools in Identity Manager.

If you have any ideas for topics you would like to see addressed, or issues you ran into as you started working on Identity Manager and would like to share with others, let me know and I will happily write it up.