Tokens of Identity Manager Part 1
I have been working with a client lately that has a large team of developers who have been learning about Identity Manager. They have been providing great fodder for what people getting started with IDM might know or not know about.
This perspective has been really helpful in giving me ideas for a new series of articles that can help out beginners to IDM.
One of my favorite things about Novell Identity Manager is DirXML Script. This is a domain specific language that Novell wrote that turns out to be pretty powerful. You could probably do most everything in XSLT, but usually that is more complicated (to my mind). I had an example, where this really interesting somewhat long (2 or 3 pages) XSLT stylesheet was used to perform a function. While we were looking at the XSLT and discussing how it worked, I rewrote it into 7 DirXML Script tokens. Now I can understand that for those familiar with XSLT, it is harder to switch over to DirXML Script, but since DirXML Script is meant to be the default approach in IDM it seems like the better way to go.
One of the things about the IDM product is that over the years, with each new release new and interesting tokens get added to make things easier.
There are many well known examples of that, which I have addressed in articles before: http://www.novell.com/communities/node/6178/new-idm-36-enhancement-do-find-matching-objec
However, while I have never counted the total number of tokens available, I am sure I have only hit a small number with the listed articles, so lets focus on some of the lesser well known tokens instead.
So I went and counted. There are:
- 29 Noun Tokens
- 16 Verb Tokens
- 19 Conditions
- 57 Actions
Goodness, there are 121 different tokens. This might take a while.
Now there at least three distinct classes of tokens.
- String or Arguments Builder (Verbs and Nouns)
Lets start with the last category, since these are both most commonly used, and yet least commonly used tokens!
String Builder or Argument Builder:
There is a common builder made available from all sorts of tokens, usually anywhere you can provide a string value, or an argument to a token that has a long list of two types of tokens. Nouns and Verbs.
In my series on Common mistakes beginners to IDM make, part 1 ( http://www.novell.com/communities/node/13053/common-mistakes-newcomers-idm-make-part-1 ) I discussed one of the most common mistakes about using Verbs. Verb tokens, like verbs in English are action token. But in the IDM context they need some data to act upon. Thus a verb needs a noun to provide some data. This is done in Argument Builder by using the up and down arrows to move the tokens in the list around and if you move something down, it first nests into the item below it, and you can easily see how a verb with a nested noun is meant to apply. Of course you can have many levels of nesting so that many verbs apply in sequence to the data in the originating noun.
For lack of any better system, I guess I will just start in order.
Amusingly, the first item in the list is Text, as opposed to something with the letter A. In case you are wondering there is actually a reason for this! Aside from the fact it is the most common token to use, it turns out in a field that allows the String/Argument Builder pop up, if you start typing text, it defaults into the first token, which is confidently Text().
Entitlement and Attribute tokens:
There are two families of tokens that are very similar in general use, and are worth talking about together. The Entitlement and Attribute token families. Lets talk about these first.
The String Builder or Argument Builder interface is the same, but used in different times. Sometimes it is meant to build a literal string value. Or else it is meant to build a nodeset in which case it is really Argument Builder, and can be used to select a nodeset of values, often to be used to loop over that nodeset in say a For Each or While loop. (Of course a local variable can be a string or a nodeset so you get the same builder regardless).
Thus there is a whole family (see the eight tokens in the title of this section) of tokens meant to provide a nodeset of values to loop over.
Added Entitlement, Removed Entitlement, and Entitlement are different approaches to let you handle Entitlements, as a nodeset. You can read more about Entitlements in this series I wrote:
Anyway, one event might consist of any number of entitlement changes. Now you might want a code block to do something with all the Added Entitlements, and then another to do something with all the Removed Entitlements. Removed also includes Revoked entitlements, it is called Removed instead of Revoked to maintain consistency with the Removed attribute token naming. These are basically analogues, it's just that Entitlements have an extra state of Revoked, which differs slightly from Removed.
Anyway, using the Added or Removed Entitlements tokens you can implement whatever is supposed to happen when those entitlements are granted or revoked.
The Entitlement token is more like the Source Attribute token, which will query back to eDirectory for the list of Entitlements currently on the object of reference. Alas, you cannot redirect this to another object (like in Source Attribute) since Entitlements are supposed to be object specific. However you can always do the work 'by hand' the 'hard way' by reading back the DirXML-EntitlementRef attribute of the object of interest, and checking each Entitlement to see if it is the one you are interested in.
Also, these tokens only refer to Entitlements specific to this driver, which also would be nice to have some flexibility in. Might be neat to be able to check not just if the object has a specific entitlement in this driver but maybe also in another driver? I can imagine some use cases which would make that useful. Again, you can do it by looking at the DirXML-EntitlementRef, so not that hard, just would be nicer if it was built in.
The Entitlement family of tokens take the Entitlements short name as their parameter. This is specific to this current driver, so although the picker is functionally a DN browser, it only lets you pick Entitlements contained within the current driver. This is neat, as you can have a library based policy that is used in several drivers, and each driver has the same named Entitlements and this should all work when reused.
The Operation Attribute should really be named Added Attribute to make it clearer, since this is a little confusing when considering the Condition token If Operation Attribute, which has a bunch of different modes. For example, if operation attribute can test for available, changing, equal, etc. Available means at least one value is being added (though some removes may be happening at the same time), while Changing means at least one of a remove or add attributes is happening. Thus testing for if operation attribute is changing and then if operation attribute available, you can tell if there is only an add or only a remove.
You can read more about this neat ability in this article:
Anyway, the thing about Operation Token when acting as a Noun in Argument Builder is that it only means the attribute value being added in the current operation. As you can see this is slightly different than in the condition case.
Thus if you need a rule that loops over all added values of an attribute (say Member on a group) then this is the token for you! Removed attribute is much clearer and does what the name says. It provides all the removed attributes as a node set. (Ok the name does not imply a nodeset, but if ever there is the possibility of more than one value, assume a nodeset as the result).
The Attribute token is basically similar to the Entitlements token, in that it will look at the operation attribute for values and if none there look back at Source Attribute, which means if the attribute you need is available, then it does not need to query, but if not it will do the query, saving some code steps and saving unneeded queries in some cases.
The Source and Destination tokens let you look forwards or backwards in the event flow to get the value of an attribute. For these it defaults to the current object, but you can specify either a DN or association value to find a different objects attribute value. If you treat this like a nodeset you can handle one or more values returned. If you treat it like a string, you will work fine for a single value, but if there are two or more values you are likely to get the string values concatenated together into one big mush.
Many of these tokens are basically special cases of the Query token, those that do not just look at the current event document that is. What that means is they query either the source or destination for the attribute you specified. In the case of the Entitlement family, they look specifically at a special case of a single attribute, and know how to handle it's Path syntax formatting to properly filter the results to just this driver's entitlements and to handle granted, revoked, or absent values.
This is a neat token that is rarely needed, but when you do it is mighty handy. This lets you specify a Unicode (double byte) character that you cannot otherwise type. You can use this to enter such a value into a string, or else in a condition test, where if local variable is equal to some special character or the like.
This is an easy one to do without a token, but is convenient to have available. XPATH of @class-name will do the same thing, but it is simple and cleaner to use the Class Name token.
This is a basic token at first glance, it basically performs an XPATH of @dest-dn, which means if there is no dest-dn XML attribute in the current document it is not going to return a value. Alas, it is not some magical token that does a Resolve from Association to DN under the covers, if it needs too. That would be cool, but alas is not the case.
However if does have a built in Parse DN function, which is helpful. After all a destination DN could be in many different formats, depending on what the destination uses. However it is a stripped down Parse DN function, so you can specify the start (0 is the root most element, usually the tree on an eDirectory to eDirectory driver) and then the length, where -1 (negative one) means the very end. You can read more about Parse DN examples and neat stuff in these article:
But basically if you want to parse up, cn=Geoffc,ou=Users,ou=data,dc=acme,dc=com to just get the cn=Users part you would set the start to 3 (if 0 starts at dc=com, 1 at dc=acme, 2 at ou=data, 3 at ou=Users) and then length of just 1, to get one node, that would work. Of course, you could approach it from the other end, where you start at -2 for a length of 1, to get ou=Users as well.
As you can see the Parse DN functionality exposed here, in Source DN, and in the Parse DN token itself is very powerful.
There is one more interesting option, Convert to Source DN format, which is part of the limited functionality, since you cannot specify other then the OTHER format. Since this is Destination DN, the option is to convert to the Source format. The Source DN token will have an option to convert it to the Destination format.
Anyway, stay tuned for more, lots more to work through. My hope is to provide some more useful information than the current documentation provides.