Novell Identity Manager has lots of built in tokens in its custom language, DirXML Script to help make your job a lot easier. Alas, the docs do not always provide enough information. Or perhaps I should say as much information as I would like to see. To try and fix this I have been writing a series of articles describing some of the interesting tidbits available with some of the functionality, that is often missed in the official documentation.
You can read some of those articles at these links:
I have been campaigning within Novell to get them to consider linking to some articles on Cool Solutions from the docs, since they clearly do not have the resources to generate the docs I think are needed. My theory is with a suitable disclaimer, they could easily bulk up the volume of their docs with more useful information from the real world. I have not had too much luck with this, alas, but if others start suggesting it as well it might gain some traction.
There is an interesting subtlety in the Operation Attribute token that is quite important and worth talking about. I wish the docs included this, since it is quite interesting, but hard to find out just from reading.
As discussed in the articles quoted about the Attribute tokens, there are actually four basic tokens.
Source Attribute, which will always go look back at the source data store for the information.
Destination Attribute which will always go to the destination data source.
Operation Attribute which will use the information in the current operation event document.
Attribute which is a neat combination of Source Attribute and Operation attribute, so if there is information about the attribute in the event document it will be used, just like operation attribute, but if not, then a query will be sent to the Source data store.
There are some subtleties in terms of what will be read from cache, and what will always cause a fresh query event, which are worth repeating, since they too are not mentioned in the docs. The Source, Destination, and Attribute tokens will use data from the cache, if within the same Policy object the data had been queried. That is, the lifetime of the cache is a single Policy object processing a single event. I am unclear if that means one event document, or one event, which is an important subtlety as well. You could have a single event document (the <input> node and down) that has multiple <modify> events. Or a <modify> and a <rename> or any other combination that makes sense.
It seems likely that the cache will not persist between events inside the event document, but it is unclear to me at this time.
However, there will also be times where you wish to go around the cache and be confident you are getting fresh data, in which case use the Java query calls, since they are unaware of the cache, whereas the Query token is aware of, and will use the cache.
The above four tokens are the ones I wrote about in other articles, and I sort of missed one more. That is, Removed Attribute. This is a special case of Operation Attribute, as an event can have an <add-value> node or a <remove-value> node. The Operation Attribute noun token would pick up the <add-value> nodes, whereas the Removed Attribute noun token would pick up the <remove-value> nodes.
Now it is worth mentioning at this point that these various tokens take on slightly different forms, and in fact the Attribute, Source, Destination, Operation and Removed types are actually more like concepts, that are used where appropriate.
What I mean by that, is that in the Condition block of a rule, we have some IF tokens, for the main 4 (all but Removed). For the Removed Attribute case you would handle that with a test of if the operation attribute is changing FROM some specific value.
There are a number of test conditions on the Operation Attribute condition token, and I will come back to them in a few moments.
But first there is another entire context for these attribute options, where you can use actions that set, add, remove, clear or strip attributes.
You can set a source attribute which sends a <remove-all-values> node followed by an <add-value> node, which is best to use on known single valued attributes. This way you do not run into any errors at the receiving end of trying to add a second value to a single valued attribute. Each system will indicate this differently. Might be fun to collect examples of all these error codes in one place. Anyone interested in taking up that challenge? You can see various examples of error codes that I have been tracking for the various drivers I work with in these articles:
Active Directory Driver:
SAP HR Driver:
Add an attribute, source or destination will just generated an <add-value> node. This can get you in a lot of trouble if you try to do that to an already filled single valued attribute as discussed above, in the Set attribute option.
The Remove token will remove a specific value from the source or destination as you so choose. Some systems will silently fail, and look like a success if the value you are trying to remove does not actually exist (Active Directory for instance). However others will generate an error, such as the eDirectory driver.
You can clear a source or destination attribute, which sends just a <remove-all-values> node.
From the operation attribute perspective you can Strip Operation Attribute which will remove the attribute from the event document. This will remove the attribute in its entirety, and all instances of it in the event document. That is, if there is an <add-value> and <remove-value>, in other words a changing attribute, then Strip Operation Attribute would remove all of it. If you try to use a strop by XPATH, you need to be sufficiently specific to remove it, which would use different XPATH for an <add> document vs a <modify> document. Like the reformat operation attribute Reformat Operation Attribute
, there is some neat logic under the covers of some of the tokens that is not always obvious.
Additionally there is a Clone Operation Attribute, which allows you to copy whatever Attribute A is doing, into Attribute B in the same document. This is nice as it will copy the <remove-values>, <add-value>, and <remove-all-values> nodes to the new attribute name as well.
There is also Clone By XPATH which is a much more generic token that can do a heck of a lot more, but could be used to copy an attribute in the current event document with the right XPATH expression.
That does it for the Conditions and Action tokens. On to the Nouns in Argument Builder.
There are couple of uses for Argument Builder. It can be used in a for each loop, to specify the node set or set of values to loop over. Additionally it can be used to build a string, in whatever context that makes sense. There are many instances where this editor will pop up, usually when you need to build a string value of some kind.
When used in a for each node, you can use one of the attribute tokens, and the options are Attribute, Source Attribute, Destination Attribute, Operation Attribute (which would be the values being added in the event) and Removed Attributes (The attribute values being removed in the event).
What is kind of neat is that you can use as many tokens as you like, and the results are processed one after another by your loop. That is, you could loop through all Source Attribute Group Membership value and then Destination Attribute Group Membership, and by adding one token after another, the for each loop will work through each set, one after another.
If you get zero results, then you loop zero times. In fact in the Identity Manager 3.0 days, when there was no nested IF token, the way you could simulate an if then token, would be to put your condition in the for each loop. If it was true, and there is a result, then you execute whatever was inside the for each loop. If the value evaluated is false, then it does not execute. The other approach was to cascade rules one after another based on the results of the previous rule. This was because the only condition block available back then was in the beginning of each rule. In both cases it was somewhat unwieldy, and thank goodness we got a nested If then token as this is so much easier to use.
Now back to the condition test of operational attribute options. You will notice that there are many tests for this condition. Of course there is a test for equality. The equality test has the usual set of types of equality compares, like the usual case sensitive and case insensitive compares, for when you need to match a simple specific string.
There is the regular expression equality, which is a ton of fun, since you can do all sorts of cool stuff in Regular Expressions to try and match strings. A couple of other tokens support regular expressions, and possibly the silliest use I ever saw was to reformat date strings in a Replace All token, using Regular Expressions and capture groups.
Additionally there is numeric, and binary which are useful for those kinds of data. Structured is interesting as it lets you specify the components and values you wish to compare.
These modes are common across many of the operators, such as Equals (not equals of course as well), changing to (not changing to), changing from (not changing from), and in fact less than, greater than and their NOT’ed equivalents. In the greater than or less than case, the numeric compare is important as the numbers do not compare the same numerically and alphabetically.
But the most interesting operators in this context are the Available and Changing operations and their negated versions.
An event can have three different types of events on an attribute. There could be a value being added, a value being removed, or a remove all values in the document. What makes it more complex is that there can be any or all of that set of three possibilities in the document.
With careful use of the Operational Attribute token, you can detect the various cases.
The test, if operational attribute is “Changing” is true then it tells you that there is a node with this attribute name in it. It might be an add value, a remove value, or a clear value (remove all values) but it is there in the event document.
However the test if operational attribute is “Available” is true, then there is a value being added in the document.
Thus you can test if operational attribute is changing to know it is in the document, and then in a later test you can check if operational attribute is available to know if one of those changes in the document is an add event.
Then you can loop through Operation attribute to get the added values, and through Removed Attribute to get the values being explicitly removed. Of course if there is no Removed Attribute values then it is a Remove All Values case.
This way you should be able to handle all the possibilities with having to resort to XPATH to try and figure it out.
Of course, you can do this in XPATH conditions. They are moderately trickier only because an <add> document looks a little different than a <modify> document, but I will only address the <add> case, since there is no way to <remove> a value in an <add> document.
Nodeset of values being added:
Nodeset of values being removed:
Test for a clear attribute:
I hope this helps understand some of the hidden subtle bits in these very powerful tokens.
Disclaimer: As with everything else at NetIQ Cool Solutions, this content is definitely not supported by NetIQ, so Customer Support will not be able to help you if it has any adverse effect on your environment. It just worked for at least one person, and perhaps it will be useful for you too. Be sure to test in a non-production environment.