One of the really neat features of Novell Identity Manager is the set of built in functionality. Now much of it is often a simple function, that is pretty commonly used, wrapped into a token with a nicer interface.
Probably the simplest example of that is the noun Source DN() token in Argument Builder. This is pretty trivial to do in XPATH, and in fact there are still lots of time you have to do it the XPATH way, with a simple -dn but once it is a token, it is much easier to read and use in policy.
There are some very nice and complex ones, like the Query token, which provides a really nice and simple to use wrapper around the built in Java classes that come with Identity Manager for Querying the source or destination. It lets you easily specify where to start the query from, the scope, what attributes to match, and what values to return. You can do all that directly with the Java functions, but you have to know the syntax and build the query docs in advance.
Then there is the best example, the Time and Convert Time tokens (noun and verb respectively). The Java time classes are very powerful, but the syntax is somewhat arcane. With the advent of the Time tokens, it becomes amazingly trivial to read time in almost any imaginable format, and convert it to any other possible format, easily and with a really simple interface.
I have written a fair bit about many of the tokens in the past, and you can read more about any that interest you at the links below:
One of the really neat tokens that I have sort of talked about before, is Parse DN. You can see that I have done two previous articles on it:
Parse DN is so powerful because in one token, it handles conversions from most any DN (Distinguished Name) format to another, assuming it is possible.
For example, taking a full LDAP DN in the format cn=jsmith, ou=acme, dc=com and convert it to the internal DN format for Identity Manager com\acme\jsmith or to dot notation jsmith.acme.com and so on.
Alas, without more information, there is no way to know that com\acme\jsmith should become cn=jsmith, ou=acme, dc=com instead of cn=jsmith, ou=acme, o=com or some other combination. Thus unless you have a fully qualified DN to start with, there is information missing that is hard to get that is needed before you can go any further. Heck you can even do the silly forward slash dotted notation that Lotus Domino uses.
As an even neater function, you can just say Source DN or Destination DN format. So you do not even need to know what format either end of the conversion uses, you just need to know that it is the source or the destination you are aiming at. This is a surprisingly subtle but powerful possibility that comes in mighty handy!
When it comes to the fully qualified DN, the good news is you often have an XML attribute qualified-src-dn (which you could select with the XPATH statement @qualified-src-dn if needed) that you can get that data from, but that assumes it is coming from a source that has that information.
All that is great and useful, but what if you come across some silly application that for some reason has its own goofy DN delimiters and patterns.
Well, theres a Parse DN use case for that.
Turns out one of the conversion options is 'custom'. I concede that I had almost never actually run into a practical use for this. Well once a couple of years ago, and Father Ramon suggested a pattern that would have worked, but it turns out I found an easier way to do it. (I wish I remembered all the details now).
As many powerful and complex functionality often turns out, the results look hard to read.
I recently found an example in a driver I was trying to document. The SAP HR driver, that comes from the Compliance Management Platform (CMP) is very different from the previous SAP HR driver configurations. I have a series running where I am walking through the driver, trying to explain some of that really interesting driver. You can read more about it in these articles:
In the Publisher Event Transform, there is a rule that reads the global configuration values (GCV) from the driver, in a less than common fashion. Usually you would just request the GCV via one of the many Global Configuration Value token options. (Or through the use of the ~GCVName~ or $GCVName$ notation in any field that supports it).
In this case, the author of the driver wanted a more subtle approach to do some very cute tricks with node sets and structured GCV's. Structured GCV's are a new addition in Identity Manager 3.6.1 and probably worth an article of their own. Nonetheless, rather than just grab the GCV into a node set variable, he took a different approach. He used the Document token, which I only recently noticed, to read the entire XML document in one move.
Anyway, here is the set local variable where the magic occurs.
<do-set-local-variable name="configValues" scope="driver">
<arg-node-set>
<token-document>
<arg-string>
<token-text xml:space="preserve">vnd.nds.stream:</token-text>
<token-text xml:space="preserve">/</token-text>
<token-parse-dn dest-dn-delims="00,/ =*\" dest-dn-format="custom" src-dn-format="slash">
<token-global-variable name="dirxml.auto.driverdn"/>
</token-parse-dn>
<token-text xml:space="preserve">#</token-text>
<token-text xml:space="preserve">DirXML-ConfigValues</token-text>
</arg-string>
</token-document>
</arg-node-set>
</do-set-local-variable>
You can see that to use the Document() token, he needs to provide a path to the document, which is the DN of the driver, a pound sign (#) and then the attribute of the driver that has the XML (DirXML-ConfigValues).
Along the way, he takes the GCV dirxml.auto.driverdn that provides the current driver DN, so you do not lock yourself into any single driver instance. The engine returns that in backslash notation, in the format of \com\acme\drivers\IDM\DriverName.
The Parse DN is using the custom formatting pattern of 00,/ =*\ which looks worse than mush!
Good news is the docs explain the formatting.
http://developer.novell.com/documentation/dirxml/dirxmlbk/ref/dirxmlscript/token-parse-dn.html
I figured it would be good to put the explanation in here.
src-dn-delims and dest-dn-delims are used to specify custom DN formats. The eight (8) characters that make up the delimiter set are defined as follows:
If RDN Delimiter and Relative RDN Delimiter are the same character, then the orientation of the name is root right, otherwise the orientation is root left.
If there are more than eight characters in the delimiter set, then the extra characters will all be considered to be characters that need to be escaped but will have no other special meaning.
So lets work through our example of 00,/ =*\ using the definition above.
Ok, the first zero tells us it is not typed. In this context, typed means using the CN=, OU=, O=, DC= etc type notation. LDAP format is fully typed as an example. Not typed would be without, like the format that the GCV returns the dirxml.auto.driverdn values, as in the example above \com\acme\drivers\IDM\DriverName.
The next zero tells us not to output Unicode characters in escaped hex format.
Now the difference between item number 3 (Relative RDN Delimiter) and item number 4 (RDN Delimiter) is somewhat confusing, since after all, the R in RDN is Relative. Thus Relative RDN is really Relative Relative Distinguished Name. Like RAM Memory, nice and redundant! To be honest, I had to go get someone to explain this to me, since it makes little sense to me as written.
But basically, the idea behind it is to offer an opportunity to define a way to walk backwards in the DN pathway. That is, in the default Identity Manager DN naming, we use backslash (\) the RDN Delimiter to split up pieces of the DN. But if you have ever used the Map token, or Generate Password token, which refer to a Mapping Table object, or Password Policy respectively by their Distinguished Names, you have an option called "Set DN relative to policy" right after you select them from the directory, you will have seen the DN change from com\acme\drivers\Library\MapTable to ..\..\Library\MapTable which uses the .. to back up a node in the DN path. Thus period (.) is the Relative Relative Distinguished Name. (Wow does it sound silly when you say it that way!)
The other part that is important, is that when the RDN and the Relative RDN are different then the nodes in the DN path are root left, like in slash format. That is, the root most node is to the left. When they RDN and Relative RDN values are the same then it is a root right path, like in an LDAP style path, where the root most node is to your right. Like in navigating waterways, right red returning. (At least in North America, no clue if that is true anywhere else). Ok, not like that, but you get the idea.
So in our example, Relative RDN Delimiter is a comma, which is different, and the RDN Delimiter is a forward slash (/). I am not sure that I can envision exactly how you would indicate a step backwards with two commas, but I think I will let that one pass.
However since they are different that means root left, so the root most node is to the left.
Next up is Name Value Delimiter, which I am told is a little known, little used feature of X.500/LDAP based directories, which is that an object can be named by more than one attribute, or even more than one value of the same attribute. e.g. I could have a user whose rdn was cn=fred uid=fflinstone.
I actually have seen this come through on Dstrace, but I had no idea how it got setup. But I have definitely seen users go by with this kind of naming. I think I know how I could set it in Identity Manager but I have no idea how I would go about setting a user up like this otherwise.
Wildcard character is pretty straight forward, asterisk (Asterix is a little Gaul fellow from the comics. Would you believe, when I did my under grad thesis defense, THIS was a discussion we had? Apparently I had been saying Asterix, not Asterisk to describe the character on the keyboard. Shift 8 on a US keyboard). I am pretty sure Lotus Domino actually uses a different wild card character, but now I cannot find anything to back that comment up.
Finally the Escape Character. This is an important one, since DN's can contain all sorts of goofy characters, in fact, all of the listed special characters used in the definition of the Custom ParseDN string. As you can imagine, you pretty much have to escape each of those, or else.
This is usually seen in a DN path such as an LDAP name in Active Directory (since the default in Active Directory is to use the full name as the leaf most node, so cn=Geoffrey M\. Carman,dc=acme,dc=com would have the period on the middle initial escaped by a backslash.
There is one last feature, characters in the custom formatting string, beyond the first eight characters. This is where you might define additional characters that would need to be escaped, that might differ from the standard escaped characters, or differ from the characters already used in defining the custom formatting string. (Obviously 0 and 1 for the first two values, do not need escaping, they are just representing boolean values. But the rest, ,/ =*\ will be escaped).
In principle, you ought to be able to use this custom formatting string syntax to define most anything you need in terms of picking apart a DN style path. In practice, I have seen very few real world uses for it, mostly because the built in options, cover every occasion I have run across. But it is nice to see that there is an additional option, should you be in one of those other worldly moments, as you find out that the system you are connecting to Identity Manager, has this goofy syntax for DN's that no one else in the world has ever heard of! Take heart, for you have options!
Support
Documentation
Learning Services
Partner Programs