LDAPWiki: DirXML Variable Expansion

Overview#

Here are some interesting details about DirXML Variables Expansion.

This is some excellent details that were provided by "-Father Ramon" in a thread in the user forums.

Within IDM#

Surrounding DirXML Variables with "$" or "~" work quite differently, even though in many cases the results may be the same.

Surrounding with "$" #

Surrounding with "$" happens at runtime and so the DirXML Variables is evaluated in real time. A single or double dollar sign is evaluated at runtime time. That is, when the code is executed the values are evaluated and expanded.

The form of $ expansion is used everywhere else but NOT XPATH. The expression and requires both a leading and trailing $. It is similar to ~expansion in that it results in text replacement rather than a variable reference, but differs in 3 important ways:

It works with Local Variables as well as Global Configuration Variables.
It happens at runtime instead of load time, which means that it is expanded dynamically every time it is executed.
When performed in a regular expression field or replacement text field, it tries to apply escaping to the value such that all the of the meta-characters within it are considered to be literals.

I say try yo because it is a known issue that it does the escaping wrong and ends up replacing the meta-character with the equivalent of \u0000 (e.g. the null character) so you will always end up with a bogus expression if your variable contained literals. I've been trying to convince somebody in a position to do so that this needs to be fixed for about a year and a half now (and that the fix is trivial), but so far with no luck.

Even if it did work correctly, what this means is that using $ expansion always results in an expression that matches the literal value of the variable and can't be used to embed wildcards or other meta-characters.

The end result of that being that you can't construct regular expressions in local variables, and you have to use expansion instead of $ expansion if you want to use a GCV as a regular expression. I think it would be a great enhancement if when they fix the escaping problem, they add some additional syntax to signal that you want to expand in a regex without escaping, maybe something like $!variable!$.

Surrounding with "~" #

Surrounding with "~" works at replaced at driver startup time which is policy load time and replaces the text in-line before the policy is even parsed. This is as if the replacement text was part of the policy. This is essentially equivalent to C/C++ macro expansion of constants created with #define.

Leading with "$"#

The leading "$" is used only in XPATH Expressions. Leading with a "$" in XPATH happens at runtime and so the DirXML Variables is evaluated in real time. A single or double dollar sign is evaluated at runtime time. That is, when the code is executed the values are evaluated and expanded.

Variables in XPATH #

The following can be used in XPATH Expressions:

leading "$" is used only in XPATH Expressions -
Surrounding with "~" - Gets all the Child Nodes Values for ~abc~
Surrounding with "~" with Quotes '~abc' - Gets the string Value for ~abc~

A leading "$" is a DirXML Variables reference and is used on Global Configuration Variables and Local Variables. For example, if you have Global Configuration Variables abc that contains the string "xyz", then the expression:

$abc
results in the string "XYZ"

but the expression

~abc~
results in the expression
"xyz"

Surrounding with "~" works at replaced at driver startup time which is policy load time and replaces the text before the policy is even parsed, so it is as if the replacement text was part of the policy. which is shorthand for:

child::xyz

Which selects all the abc elements that are children of the context node.

To get a string from expansion, you would need.

'~abc~'

which would expand to:

'xyz'

which is a string literal.

More Information#

There might be more information for this subject on one of the following: