Customizing Object References

If a resolution variable may represent more than one LDAP entry (an array of entries) specifies the attribute "multivalue". This feature is used for the foreach processing instructions.

In the following example the resolution variable activities represents all LDAP entries with the objectclass dxmIDMActivityDefinition under the base object THIS:

<resolutionVariable name="activities" baseVar="THIS" objectclass="dxmIDMActivityDefinition" multivalue="true"/>

To access the entries use the [] operator specifying the index of the array. The array index starts with 0. The following example accesses the second entry of the resolution variable activities and returns the value of the dxmContent attribute:

${DN4ID(activities)[1]@dxmContent}

If you want to sort the result use the attribute

sortAttribute="attribute"

where attribute specifies the attribute that is used to sort the result. Only one attribute can be specified. Sorting is always performed in ascending order. This feature is used with framework filters. To keep the sequence constant a sequence number is specified for every filter. In the following example the dxmSequenceNumber attribute is used to sort the result:

sortAttribute="dxmSequenceNumber"

With the "INCLUDELDAPATTRIBUTE" operation, the content of an LDAP attribute of the same or another LDAP entry can be included:

The "REF" attribute expects a reference to the LDAP attribute. Note that the content of the included LDAP attribute has to be well-formed XML! It again has to be expanded the same way as the parent.

You can use an extended notation:

If PATH is not present the whole XML document is exported.

Specifying PATH means to export the given path and its children. In this example, the element "template" and it’s children are exported.

Path is relative to the root element and path elements are separated by '/'.

Example:

To export the value element specify PATH="template/value"

The operation "FOREACH" and "ENDFOREACH" allow for including values of several LDAP entries defined by a multi-value resolution variable in between a loop:

<?IDMCONF FOREACH channel IN ${channels} ?>

<this will be included for each value of variable ${channels} />

<?IDMCONF ENDFOREACH ?>

The content will be included for each value of the loop variable (here: ${channels}, which is assumed to be multi-value). This construct allows to follow multi-value LDAP references and include the content of a set of referenced LDAP attributes as part of an enveloping XML construct.

The included content is expected to be well-formed XML!

In the following example the multi-value resolution variable activities represents all LDAP entries with object class dxmIDMActivityDefinition under the base object THIS. In this example THIS represents a workflow object, for example a realtime workflow object with usually two activities: join and error.

For each LDAP entry (represented by the variable activity) in the list of all LDAP entries represented by the variable activities, for example returned by a search operation, the dxmContent attribute is expanded via the INCLUDELDAPATTRIBUTE tag, once for the join activity and once for the error activity.

Use the if construct to insert a configuration section depending on an attribute of a resolution variable. The body of the if branch must be a syntactically correct XML structure (for example a complete XML section/tag).The if construct is like the XSLT if construct: there is no else branch.

The syntax is as follows:

<?IDMCONF if-begin test="resolutionVariable operator 'value'"?>*
xmlBopy
<?IDMCONF if-end ?>**

where

In the following example, the connection’s support for SSL depends upon the specific attribute ssl:

Attribute mappings in data-synchronization workflows are formulated as <attrMapping>, <idMapping> or <postMapping> within a XML <mappingDefinition> element. Here is an example:

If the mapping is realized via Java code (mappingType="java"), the Java source code and the compiled unit are placed in extra LDAP entries. They lie underneath the channel entry identified by their attribute name. The compiled unit is found in the LDAP attribute "dxmCompiled" (see /1/). Exceptions: For <idMapping> a fixed Name “dxmIDMapping” and for <postMapping> a fixed name “dxmPostMapping” is used to identify the LDA entries ( because here is no attribute name available).

Such a construct makes the downloading more complex. Most of the XML can be taken as it is. Only if the mapping Type is "java", the corresponding AttributeMapping entry has to be read, and the content of the LDAP attribute "dxmCompiled" inserted as <code> sub-element. Here the resulting element:

Virtually the same is needed for identification mapping <idMapping> …

… and <postMapping>.

This transformation cannot be formulated with the above processing instructions. Therefore we introduce a new one named "INCLUDEATTRMAPP

The "REF" attribute expects a reference to the LDAP attribute, which holds one <mappingDefinition> element. The implementation has to replace the <value> element of all java-based mappings in <attrMapping>, <idMapping> and <postMapping> by the <code> element, which holds the compiled Java code.

DirX Identity holds some attributes as specific attributes at various LDAP entries. Important entries for the real-time workflows are: root node, configuration entry "dxmC=Configuration,dxmC=DirXmetahub", each connected directory and each channel. They are stored in the format "attributeName value".

Mapping in the real-time workflows makes use of a list of environment attributes. They are collected from several entries (listed above) and stored in the following XML format:

The following processing instruction reads these specific attributes and stores them in this XML format:

The "REF" attribute expands to an LDAP attribute in some entry, which contains the attributes in specific format.

The value of some attribute may depend on the value of another property. For example, the target system port usually depends on the SSL flag of the bind profile. The insertCondAtt operation allows you to include referenced content on a condition. Here is an example:

In the example shown here, some attributes of the connection are fixed (pagedRead, password, …). The attributes port and ssl depend on the dxmSSL attribute of the bindprofile. The instruction inserts an attribute of the given name to the enclosing element (here connection). If the test expression matches then the attributevalue is set to the one specified after “true=” otherwise the value of false is taken. If the expression can’t be evaluated as the referenced attribute isn’t present, false is assumed.

The example shown here can be resolved to:

DirX Identity uses the following fixed-value references:

Another type of reference starts at a fixed object (set at runtime for the actual running workflow) and can follow any distinguished name an object contains to another object. This method produced relative references that are very reliable against structural changes in the configuration database.

References of this type have the following syntax:

<?StartObject@DistName@DistName@…​@ValueSpec/>

The available StartObjects are:

Some of these objects are not static; they are determined by the C++-based server at runtime (for example: the current activity that is running at the moment determines the activity start object). The loopVar construct allows for the handling of multi-value attributes (see the section "Loops" for further details).

DistName is a distinguished name in the directory with three possible representations:

ValueSpec can be one of:

Additional specifiers for ValueSpec can be used to handle special situations:

If an attribute at the end of the reference chain contains multiple values, all values are concatenated using the comma as separator.

If an [index] range is defined for creating a substring of the attribute value, each value of the substring is built prior to concatenation of the values.

Example:

SpecificAttributes='a b;c d;e f'
<?Job@SpecificAttributes/> evaluates to 'a b,c d,e f'
<?Job@SpecificAttributes[1:1]/> evaluates to 'a,c,e'

Loop constructs provide a special handling mechanism. These definitions allow the system to extract a variable loopVar which can then be used in a cmdline construct to define exactly how it looks.

<?loop loopVar=<?object…​@multivaluedAttribute/>
cmdline="…​ <?loopVar@object …​@attribute($specifier,$specifier,…​)/> …​"
/loop>

Note that no newline is written at the end of the cmdline. If a newline is required, it must be written as \n. In a cmdline expression, the following quoting applies:

\n → newline
\t → tab
\r → carriage return
\\ → \

In all other cases, \c yields c, the character itself. Note that a cmdline expression ending in \\\n will result in a backslash at the end of the line.

Possible definitions in the cmdline are:

<?loopVar/>
<?loopVar.name/>
<?loopVar.$n/>
<?loopVar[start:_end_]/>
<?loopVar.$n[start:_end_]/>

Additional specifiers for ValueSpec can be used to handle specific situations:

To enhance readability of scripts with references, variables can be defined. First, the variable must be defined at the beginning of the script:

<?set var=any_string/>

where var defines the name of the variable and reference can be any string or reference definition. Then the variable can be used:

<?$var/>

The set statement produces a resolved line as output. Therefore you should place it into a comment line of your configuration file. This is especially useful for debugging. Alternatively you can use the set_non_verbose statement that suppresses the output line completely.

<?set_nv var=any_string/>

The scope of the variable definition is limited to the current object being processed with the reference mechanism. Variables declared in INI file templates are neither known to Tcl scripts, nor to attribute configuration files.

Variables declared in Tcl scripts are accumulated. Since Tcl scripts are processed in the order "Tcl control script", "Tcl mapping script", "Tcl further script", and "Tcl profile script", variables defined in the control script are also known in the mapping script or in the profile script.

In case of recursively-defined tags, the variables are propagated top-down and bottom-up.

Hierarchical references can be used to set up a flexible parameter concept.

Let’s assume a Tcl script needs the parameter base_obj. The reference points to a specific attribute in the output channel of a job.

The referenced attribute can contain again a reference to a central parameter located for example in the central configuration object:

In this case the Configuration object should contain for example an entry "base_obj ou=people,o=pqr". Then this value is delivered to the previous construct (2) and in a second step provided to the Tcl line via (1).

If no entry is available in the Configuration object then the default value "o=pqr" is used from (2).

If the central value shall no longer be used then a fixed value can be entered into (2), for example base_obj c=DE.