Understanding the Default Application Workflow Technology

A request workflow object has two types of state:

The following figure illustrates request workflow states:

Workflow states are:

(None) - the Java-based Identity Server is aware of the workflow definition (because it is flagged as active) but instances of the workflow do not yet exist.

Running - the request workflow service has started an instance of this workflow definition after receiving an appropriate event.

Succeeded - the run of the workflow instance is formally successful; that is, a final activity has succeeded. If this activity contains an application state, the workflow instance inherits it. The request workflow service takes the application state from the calculated value of the final activity or, if there is no value there, the display name of the start condition. If the display name is empty, the application state will be empty, too.

Failed.state - the run of the workflow instance has failed. Check the activity states to see the details. state indicates the following special states:

Failed.Prepare - the state inherited from the relevant activity, which is the activity that an administrator or the request workflow service (for example, by retries) could not resolve before it reached its defined timeout value and entered an error condition.

Failed.Incomplete - the request workflow service discovered a structural error in the workflow definition but the workflow has not yet completed because:
- a startable activity no longer exists
- a running activity no longer exists
- a finished final activity is not available

Failed.Expired - there was either a timeout inherited by the relevant activity or a timeout of the complete workflow.

Failed.Aborted - either a user has cancelled this workflow instance or the timeout was inherited from the relevant activity (a user has cancelled this activity). If a user cancels the workflow, all activities that are still running go to status Failed.Aborted, too.

If parallel activities must all succeed, this state is also reached if one of the parallel activities goes to state REJECTED.

Failed - any other error inherited from the relevant activity

See the section "Request Workflow Error Handling" for more information.

The following figure illustrates the request workflow activity states:

Activity states are:

(None) - the activity instance exists but the start condition is not yet satisfied.

Running - the activity instance is running due to a satisfied start condition.

Succeeded - the run of this activity instance was successful.

Failed.Prepare - an exception occurred during the participant constraint calculation that is not ConstraintViolationException.

Failed.Temporary - the activity determined that the error that occurred is only temporary (for example, the network is temporarily unavailable). If retries are configured for this activity, the request workflow service starts the activity after the Wait before retry period to resolve the error. If no retries remain, the activity goes to status Failed.Expired.

Failed - the run of this activity instance failed due to a non recoverable error and no Error sub activity is configured.

WaitInError - the run of this activity instance failed due to a non-recoverable error and an Error sub activity is configured. This error activity is used to send a notification to the administrator, who can resolve the problem and resume the workflow, or cancel the workflow if he cannot resolve the problem.

Failed.Aborted - a user cancelled this activity.

Cancelled - the request workflow service canceled this (parallel) activity because another user approved this step.

Failed.Expired - the run of this activity instance failed due to a timeout or a Failed.Temporary condition. In this case, the request workflow service checks whether retries are configured. If they are, it restarts the activity. If the activity sub-structure contains a pre-step, it reminds the relevant user that there is still a task to do. If retries are not configured, the workflow engine sets the activity state to Failed.Expired and determines whether an escalations step is configured and still available. If no, the activity is completed and remains in the Failed.Expired state. If yes, the escalation definition is evaluated and a new activity is started.

See also the section "Request Workflow Error Handling" for more information.

The workflow calculates participants in an activity by evaluating:

Checks for expired workflows and activities.

The filter for workflow instances is:

The filter for activity instances is:

This type of the full checker runs every 30 minutes by default.

Checks all instances in state running for these conditions:

The filter to search for these instances is:

By default, this type of the full checker is disabled. If it is enabled, it is started automatically about 1 minute after server start.

You can change the full checker intervals in the server.xml for request workflows under this path:

install_path*\ids-j-domain-S*n*\extensions\com.siemens.idm.requestworkflow\server.xml*

where domain is the domain for which the IdS-J server is running and S*n is the server number (counts per domain). For example, *ids-j-My-Company-S1. See the section on "Naming Schemes" in the section "Managing Java-based Servers" in the DirX Identity Connectivity Administration Guide for a discussion of the naming schemes used for DirX Identity services.

Search for the <schedules> tag:

You can set the full check interval for expiration checks with the parameter <period> in milliseconds. By default, 1800 000 ms = 30 min are set.

You can also set the full check interval for all running workflows with the parameter <checkallinterval> in milliseconds. By default, this mode is disabled.

If you want to run with a large number of running workflows, we recommend using these settings:

and

DirX Identity’s concept for nationalization of dynamic Web Pages and also mail content is based on the Java concept for nationalization. A text element can keep one or more message items that are replaced during runtime with text that corresponds to the user’s requested language.

An example for a mail body within a request workflow activity is:

If the English language is requested, this generic text definition is resolved as follows:

For example, the definition

is resolved to

This is an automatically generated mail. Please do not reply.

Note that message items can contain variables, for example ${workflow.subject.cn} that are replaced during runtime with the corresponding value, in this case the common name of the subject. For more information about this concept, see the section "Using Variable Substitution" in the DirX Identity Application Development Guide.

Some fields within DirX Identity support nationalization. Typical fields are the subject or the body of a mail definition.

To determine whether a field supports nationalization, use the Identity Manager to view the description of the individual field in the online help. Alternatively, you can click in a field and view the context menu, which may show you the menu items of the nationalization wizard.

In read mode, one menu item is available:

Show resolved text - click this item to resolve all message items to the language definitions defined by the Default Language field in the domain object.

In edit mode, these menu items are visible:

Insert a message - the nationalization wizard opens and presents the central message item tree under Configuration → Nationalization. Select a message item object in the language of your choice and then select a message from the list of message items. The wizard inserts the corresponding message item at the cursor location.

Insert a message relative - the nationalization wizard opens and presents the local message items for this workflow. Select a message item object in the language of your choice and then select a message from the list of message items. The wizard inserts the corresponding message item at the cursor location.

Show resolved text - click this item to resolve all message items to the language definitions defined by the Default Language field in the domain object.

To optimize nationalization message management, you can define messages at two locations:

Use both methods to structure your message catalog. Try to reuse messages as much as possible.

DirX Identity provides three methods for customizing request workflow nationalization:

Local message items - you can copy a request workflow together with its local nationalization items. You can change the local items because they are copies of the original objects. You can also extend them with other locales.

Central default message items (under the path Nationalization) - you can extend the existing default message items with additional locales but you cannot change the delivered default message items.

Custom default message items (under the path Nationalization → Customer Extensions) - if you need additional central message item definitions, define them under this folder. Use folders to structure the items accordingly. Set up items for all required locales.

You can use the built-in features of the Identity Manager to create and maintain message items, particularly if you create new workflow definitions with the corresponding message items in the primary language.

Use an external nationalization editor primarily to

The export file format is comma-separated values (CSV). You can use any tools that allow you to edit CSV files correctly.

The following sections explain how to export and import nationalization information and how to edit the items with Microsoft Excel.

Exporting Nationalization Information

You can export the complete nationalization information into one file or you can select specific parts of the information:

File → Export Nationalization Items - use this menu item from the menu bar to export all nationalization information into one file. A file selection dialog asks for the file location and name.

Export Nationalization Items - use this context menu item at a message item folder or message item to export a subtree or a single item into a file. A file selection dialog asks for the file location and name.

You can specify the delimiter that is used with the parameter nationalization.csv.delimiter in the file dxi.cfg. By default, we use a semicolon ';'. Note: after changing this file, you must restart the Identity Manager.

The format of the file looks like this if two languages are exported (Excel representation):

The first line is the header line. The field definitions are as follows:

path - the object path of this message item (for example, "Conn:Configuration/Nationalization/Attribute Descriptions"). The last part is the name of the message item (here "Attribute Descriptions").

key - the key in the file (for example, mobile).

language - a column for each language in alphabetical order.

The next lines contain collections of message items (the key and the information for each language). The first line contains the path, while the last line is empty and serves as a separator.

Editing in an External Editor

You can use any editor that allows editing of CSV files. Examples are Microsoft Excel or Microsoft Access.

Before you start editing a large amount of data the first time, we recommend that you test the editor with a small amount of data. Perform an export, edit the data and then import it into DirX Identity. You should then check the following:

If all these issues worked well, you can start editing.

We tested with Microsoft Excel. Here are some hints on how to work with it:

You can perform these operations:

There are some restrictions:

Importing Nationalization Information

To import exported and edited nationalization information files:

Create empty objects - setting this option will create menu items that contain only keys but no language data. This option is useful for creating empty message items that you populate later on in the Identity Manager.

Report object creation as error - setting this option will cause all object creations to be reported as errors. This option is useful if you made changes only in your nationalization information and you want to be warned if you destroyed something.

Note that the import method automatically calculates the delimiter from the header line in the file.

The process used to determine the correct language to use differs depending on the DirX Identity feature.

Web Center Pages

The language in which a Web Center page is displayed (this is valid for static and dynamic pages) is calculated in this sequence:

Notification Resolution

The language that is used to resolve a defined notification object is calculated in this sequence:

DirX Identity handles message items during runtime as follows:

The load procedure resolves message items to absolute paths in a pre-defined folder structure:

For example:

Load Effort for Nationalization

Reading and processing the nationalization information during startup or during Load IdS-J Configuration of the Java-based Server requires some additional time. You can measure this overhead with the following procedure:

The selection methods for creation workflows depend on the calling client:

Workflow Selection from Web Center

Workflow selection depends on the type of license you have.

If you have a Business Suite license, you cannot run request workflows. In this case, the ability to create a user depends on the creation access policies established for this user. For more information, see the section "Policies for Object Creation" in "Managing Access Policies" in "Delegated Administration" in the "Managing Policies" chapter of the DirX Identity Provisioning Administration Guide.

If you have the Professional Suite license, you can create objects in three ways (note that you can set up a mix of these methods within one Web Center application):

a. Object creation via request workflows (default):

If you click, for example, the "Add user"' menu item, the Web Center application retrieves all workflows:

If more than one creation workflow is found, the list is presented to the user for further selection. If only one workflow is found, this workflow is started immediately. If no workflow is found, an error is returned to the user that he is not allowed to execute any creation workflows.

The same algorithm is applied if the creation for a different object type is requested (for example, a Role).

b. Object creation via the Create user by request workflow flag feature:

You can customize Web Center to use the Create user by request workflow flag feature. Collect all necessary information to create an object (for example, user attributes, assignment of privileges) and then save the user object. This results in a start of a request workflow that stores the object later on.

Setting the Create user by request workflow flag at the domain object influences the save operation of the object. Instead of saving the object directly, the save operation is converted to a request workflow start where the entered data is transferred as input parameters in the form of an order object. The corresponding activity of the request workflows defines when to store the object (typically this activity is named Apply changes).

c. Object creation via Creation Access Policies

You can customize Web Center to use Creation access policies. For examples, see the pages set up for the Business Suite license.

Workflow Selection from Identity Manager

Workflow selection depends upon the type of license you have.

If you have a Business Suite license, you cannot run request workflows. In this case, objects are always stored directly when pressing the Save button.

If you have a Professional Suite license, the creation depends on the Create user by request workflow flag at the domain object:

For example, if a user object is to be created, the Identity services retrieve all workflows:

If only one workflow is found, this workflow is started immediately. If more than one workflow or no workflow is found, an error is returned to the user if the Create user directly if no workflow available flag is not set. Otherwise the user entry is created directly.

The same algorithm is applied if the creation for a different object type is requested (for example, a Role).

Workflow Selection from Web Services

Workflow selection depends on the Create user by request workflow flag at the domain object:

For example, if a user object is to be created, the Identity services retrieve all workflows:

If only one workflow is found, this workflow is started immediately. If more than one workflow or no workflow is found, an error is returned to the service if the Create user directly if no workflow available flag is not set. Otherwise, the user entry is created directly.

The same algorithm is applied if the creation for a different object type is requested (for example, a Role).

This section describes the request workflow selection methods for modification workflows.

You can set up Attribute Policies for any object type to define the request workflows for attribute modification. (See the section "Attribute Policies for Users" in "Managing Attribute Policies" in the chapter "Managing Policies" in the DirX Identity Provisioning Administration Guide for details.

If an attribute of an object is changed, the service layer checks the change against the defined attribute policies:

If more than one policy is configured for an object type (for example, one for mail changes and one for department changes), and both attributes are changed, for each affected policy one workflow is started.

If a workflow link is set at the attribute policy, the referenced workflow is started. If no link is set, the workflow being started is selected by evaluating the When Applicable section of all workflows.

This mechanism is performed independently for each affected policy. If no matching workflow is found for a policy when saving the object, an error message is displayed.

If an attribute policy contains multiple attributes and several of them are changed, only one approval workflow is started.

Note that Java-based workflows do not evaluate attribute policies due to performance reasons. They only send events if enabled for an object type.

DirX Identity provides two mechanisms to select the correct workflow for a specific privilege:

The algorithm is slightly different depending on the assignment environment. We distinguish between these types for user-to-privilege assignments:

User-to-Privilege assignment - assignment, modification or removal of a privilege to or from a user (the corresponding operations for the assignment are create, modify, delete)

Segregation of duties (SoD) - an SoD policy requests an approval workflow for a user-to-privilege assignment

Re-approval - requires regular starts of re-approval workflows for a user-to-privilege assignment

Selection of approval for approval of links between privileges is handled in a similar way.

Workflow Selection Algorithm for User-to-Privilege Assignments

The calculation mechanism for workflow selection works as follows:

Calculate all workflows the logged-in user is allowed to execute. You can define the number of workflows for a specific user via access policies. (See the section "Managing Access Policies" in the section "Delegated Administration" in the chapter "Managing Policies" in the DirX Identity Administration Guide for details.)

The next steps depend on the direct workflow assignments at the privilege and the rule definitions in the When Applicable tab of the request workflow definitions:

Workflow Selection Algorithm for SoD

The calculation mechanism for workflow selection works as follows:

Calculate all workflows the logged in user is allowed to execute. You can define the amount of workflows for a specific user via access policies. (See subsection "Managing Access Policies" in section "Delegated Administration" in chapter "Managing Policies" in the DirX Identity Administration Guide for details.)

The next steps depend on the direct workflow assignments at the privilege and the rule definitions in the tab When Applicable of the request workflow definitions:

Workflow Selection Algorithm for Re-Approval

The calculation mechanism for workflow selection works as follows:

Calculate all workflows the logged-in user is allowed to run. You can define the number of workflows for a specific user via access policies. (See the subsection "Managing Access Policies" in the section "Delegated Administration" in the chapter "Managing Policies" in the DirX Identity Administration Guide for details.)

The next steps depend on the direct workflow assignments at the privilege and the rule definitions in the tab When Applicable of the request workflow definitions:

Workflow Selection Algorithm for Approval of Links between Privileges

The calculation mechanism for workflow selection works as follows:

Calculate all workflows the logged in user is allowed to run. You can define the number of workflows for a specific user via access policies. (See the subsection "Managing Access Policies" in the section "Delegated Administration" in the chapter "Managing Policies" in the DirX Identity Administration Guide for details.)

The next steps depend on the direct workflow assignments at the privilege and the rule definitions in the tab When Applicable of the request workflow definitions:

A variable definition looks like this:

It starts with a root object that can be composed of many sub-objects. The last element must be an attribute.

Root element

Root elements are:

server - provides some general variables of the Java-based Server.

workflow - represents the start element of the current workflow instance. From here you can access sub elements and structures.

<empty> - if nothing is specified, the current activity is assumed.

Examples:

This statement retrieves the mail attribute of the subject this workflow handles.

This statement retrieves the mail attribute of the subject’s manager.

This section explains the structures that can occur within request workflows. This has to do with the orders that such a workflow contains.

The general structure is:

Workflow → One subject order → Zero or more resource orders

Note that the resource orders are about assignments and not the objects itself. From here you can access the subject and the real resources:

${workflow.resources[0].dxrassignfrom@…​} - allows accessing the subject (so this is equivalent to the workflow.subject construct).*
${workflow.resources[0].dxrassignto@…​}* - allows accessing the resources.

Examples and how to access information:

User modification: Workflow → User
${workflow.subject.cn} - name of the user
${workflow.subject.mail} - mail address of the user
${workflow.subject.manager.mail} - mail address of the user’s manager
${workflow.subject.dxrLocationLink.manager.sn} - the surname of the location manager

Privilege assignment: Workflow → User → Assignment
${workflow.resources[0].dxrStartDate} - the start date of the assignment
${workflow.resources[0].roleParameter_Project@value} - the value of the role parameter Project.
${workflow.resources[0].roleParameter_Project@oldvalue} - the value of the role parameter Project.
${workflow.resources[0].roleParameter_Project@modified} - indicates the modification of the Project role parameter. The value is either TRUE or FALSE.
${workflow.resources[0].dxrassignfrom@mail} - the mail address of the user (you can use workflow.subject.mail instead).
${workflow.resources[0].dxrassignto@cn} - the name of the privilege.
${workflow.resources[0].dxrassignto@owner.mail} - the mail address of the privilege owner.
${workflow.resources[0].dxrassignto@owner.manager.mail} - the mail address of the privilege owner’s manager.

Multiple privilege assignments: Workflow → User → Assignments
You can use the same definitions as shown for one assignment if you define the index with control constructs.

Access certification: Workflow → Privilege → Users
${workflow.resources[0].dxrStartDate} - the start date of the assignment
${workflow.resources[0].roleParameter_Project@value} - the value of the role parameter Project.
${workflow.resources[0].roleParameter_Project@oldvalue} - the value of the role parameter Project.
${workflow.resources[0].roleParameter_Project@modified} - indicates the modification of the Project role parameter. The value is either TRUE or FALSE.
${workflow.resources[0].dxrassignfrom@description} - the description of the privilege (you can use workflow.subject.description instead).
${workflow.resources[0].dxrassignto@sn} - the surname of the user.
${workflow.resources[0].dxrassignto@mail} - the mail address of the user.
${workflow.resources[0].dxrassignto@manager.mail} - the mail address of the user’s manager.
${workflow.resources[0].dxrassignto@dxrLocationLink.manager.sn} - the surname of the location manager.

Note that in the examples we access a specific object if multiple objects are available (resources[0]). Use control structures to evaluate complete lists of objects.

The Java-based Server reads some variables at startup. The following attributes are available:

Domain - the domain name for which this server works

TechnicalDomain - the technical domain name for which this server works

The available attributes of a workflow instance are:

absoluteDisplayName (string) - the path of the workflow instance. It contains the display name and all preceding folder names separated by "/" . See path for the display name of the workflow definition.

activities (list of objects) - the list of activities.

applicationState (string) - the instance’s (application) logical state. This state is calculated at the end of a workflow run depending on the final or erroneous activity.

context (map) - a hash list of customer-defined variables (name / value pairs). Can be empty.

contextAttributes (map) - a hash list of customer-defined variables (name / value pairs). Can be empty. Note that this is just an alternative to using “context”.

Keep in mind that all (string) context variables are stored as specific attributes in LDAP, too (LDAP attribute: dxmSpecificAttributes). Context variables that are added or modified are in sync with the LDAP attribute. Variables that are deleted from the context are not synchronized to the LDAP attribute. Therefore when deleting a variable from the context you additionally should create an own variable indicating that the original variable is deleted. Then this new variable can easily be processed using "dxmSpecificAttributes".

displayName (string) - the human-readable name of this workflow instance.

endTime (string) - the date and time in ms (calculated from 1.1.1970) at which the workflow run finished.

expirationTime (string) - the date and time at which the workflow instance expires. This is the workflows start time plus the configured timeout value.

initiator (string) - the user that initiated this workflow.

initiatorEntry (object) - the initiator object with all attributes.

path (string) - the path of the workflow definition. It contains the display name and all preceding folder names separated by "/". See absoluteDisplayName for the display name of the workflow definition.

resources (list of objects) - the list of resource objects
Examples: roles, permissions, groups, users.
You can access specific attributes of user to privilege assignments:

Access to a new role parameter value:*
${workflow.resources[0].roleParameter_*name*@value}*

For modifications, you can also access the old value:
${workflow.resources[0].roleParameter_*name@oldvalue}*
Please keep in mind that this expression only works in emails that are sent before the object has been changed in an “Apply Changes” activity.

This flag allows recognition whether the value was changed (you can use it for conditions):*
${workflow.resources[0].roleParameter_*name*@modified}*
The delivered value is either TRUE or FALSE.

Example for role parameter Project:
${workflow.resources[0].roleParameter_Project@value}

You can access specific parameters of accounts (works only if the assignment is of type group):

${workflow.resources[0].dxrassignto@account_*name}*

Example for the description attribute:
${workflow.resources[0].dxrassignto@account_description}

This definition retrieves the description attribute of the primary account.

You can access specific parameters of a target system (works only if the assignment is of type group):

${workflow.resources[0].dxrassignto@targetsystem_*name}*

Example for the description attribute:
${workflow.resources[0].dxrassignto@targetsystem_description}

This definition retrieves the description attribute of the target system.

You can access specific parameters of an assignment:

${workflow.resources[0].controllerLink.attribute}
Example: ${workflow.resources[0].controllerLink.mail}
This definition retrieves the DN of the person(s) that performed the access certification approval.

${workflow.resources[0].userInfo}
This definition retrieves the flag that can be set by the approver during an access certification to indicate that this user shall be informed via e-mail.

${workflow.resources[0].typeOfOrder}
This definition retrieves the type of the order. The possible values are ADD, MODIFY or DELETE.

subject (object) - the subject object of this workflow
Examples: the user to be created, the user to assign a privilege, …​

startTime (string) - the date and time in ms (calculated from 1.1.1970) when the workflow run was started.

state - the workflow state (SUCCEEDED, FAILED, …​).

UID (string) - the workflow instance’s unique ID.

The available attributes of an activity instance are:

activityType (string) - the type of activity, for example: applyChange, enterAttributes, approveCreate, e-mail etc.

activitySubType (string) - currently equal to the activityType.

applicationState (string) - the instance’s (application’s) logical state (for example REJECTED or ACCEPTED).

approvalResult (string) - the approval result of the activity (for example REJECTED or ACCEPTED).

approvers (list of objects) - the list of participants for this activity that really approved/rejected. This attribute represents a list of users. You can access all existing user attributes.

category (string) - one of the categories "operational" or "errorhandler".

context (map) - a hash list of customer-defined variables (name / value pairs). This attribute can be empty.
Example: ${workflow.context.myVar}
retrieves the value of the context variable myVar for further processing.

Keep in mind that all (string) context variables are stored as specific attributes in LDAP, too (LDAP attribute: dxmSpecificAttributes). Context variables that are added or modified are in sync with the LDAP attribute. Variables that are deleted from the context are not synchronized to the LDAP attribute. Therefore when deleting a variable from the context you additionally should create an own variable indicating that the original variable is deleted. Then this new variable can easily be processed using "dxmSpecificAttributes".

endTime (string) - the date and time in milliseconds (ms) (calculated from 1.1.1970) at which the workflow run finished.

escalationLevel (integer) - current escalation level.

0 escalation not yet started
> 0 level of escalation

expirationTime (string) - the date and time at which the workflow instance expires. This is the workflows start time plus the configured timeout value.

immutableJob (object) - the job definition of this activity. It contains these attributes:

baseName (string) - the base name at which the job’s classes and lib directory reside.

className (string) - the class name of the associated job implementation.

extensionsName (string) - the name of the server-extensions where the job resides.

name (string) - the job name.

params (map) - name/value pairs of job-specific information.

interactiveTaskDescription (list of interactiveAttributes) - defines the user task to be performed at the Web interface (for example, to enter attributes). Attributes for interactiveAttributes are:

description - the display name of this attribute at the Web interface.

mandatory - defines mandatory attributes if set to true. Otherwise the value is false.

name - the name of this attribute (typically the LDAP name).

master (string) - the master activity. When calculating approvers and n approvers are found, the master activity is expanded to n activities.

name (string) - identifies the activity within the workflow.

participantEntries (list of objects) - the list of participants for this activity. This attribute represents a list of users. You can access all existing user attributes.

reason (string) - the reason why the approver accepted or rejected the approval request.

startTime (string) - the date and time in ms (calculated from 1.1.1970) at which the workflow run started.

state (string) - the activity state (SUCCEEDED, FAILED, …​).

timeout (string) - the timeout of this activity in milliseconds (ms) (calculated from 1.1.1970).

Control structures allow you to generate more complex text structures. Controls are surrounded by <? statement ?>, where the blank between <? and statement is mandatory. Control structures consist of if/else statements for condition handling, for statements for loop handling, and Java statements for defining your own text structures.

If/Else Statement

The if/else statement allows you to handle conditions. The syntax is:

The condition compares two values, the overall syntax is

operand1 comparator operand2

The comparator is one of:

== | eq | equals - compares whether the two operands are equal.

!= | ne | notequals - compares whether the two operands are not equal.

< | lt - checks whether the first operand is smaller than the second one.

> | gt - checks whether the first operand is greater than the second one.

⇐ | le - checks whether the first operand is smaller than the second one or equal to the second one.

>= | ge - checks whether the first operand is greater than the second one or equal to the second one.

Examples:

The previous statement tests whether the gender attribute of the participant is filled. If yes, it defines the correct salutation for male and female participants. If not, it defines a more general salutation.

For Statement

The for statement allows you to handle loops. The syntax is:

where variable is the name of a placeholder which can be subsequently used and list a list of “ “ delimited values (either constants or delivered by a placeholder whose type is a list).

Examples:

which could result in

Note that the line "- User ${participant.cn} rejected with reason: ${activity.reason}" acts like a template. You can also define several lines as template text.

Java Statement

The Java statement allows you to define your own text structures. The syntax is:

where classX represent Java classes that must implement the interface JavaPlugin.

Example:

is resolved to

Hello here I am!
Hello here I am!

where placeholder.TestPlugin is defined as

Java Function

The Java statement allows you to define your own text structures. The syntax is:

where

class - represents a Java classname that must implement the interface JavaPluginExt.

input - is a string / an expression that is passed to the specified Java class (execute method).

Example:

If input = ${workflow.initiatorEntry.dayOfBirth} and dayOfBirth has the value 19700218230000Z the function retrieves 1970-02-19 as result.

The class com.siemens.idm.jini.util.GeneralizedTime2ISO8601 is defined as:

For approval activities, DirX Identity can run in two modes that depend on the setting of the Reduce Runtime Activities flag that is visible in the Participants tab of a request workflow definition. The meaning of the values is:

false (default) - besides the original master activity one activity for each approver is created. This mode is compatible with versions prior to 8.2A.

true - besides the original master activity it keeps only one common activity that handles all approvers together.

Use the corresponding variables in your mail text to guarantee correct resolution during runtime. For additional information how to fill the address fields see the section Filling the Address Fields.

Reduce Runtime Activities = false

Use the following variable references in mails:

To - use ${participantEntries[0].mail} to send the mail to the (single) participant.

Language - use ${participantEntries[0].preferredLanguage} to select the language for the resulting mail text if you use e-mail nationalization.

Body - use for example ${participantEntries[0].sn} to include the surname of the participant into the mail text.

You can also use these settings with the same result:

To - use ${participantEntries.mail} to send the mail to the (single) participant.

Language - use ${to.preferredLanguage} to select the language for the resulting mail text if you use e-mail nationalization.

Body - use for example ${to.sn} to include the surname of the participant into the mail text.

This allows you to use the same mail text fragments for workflows with Reduce Run-time Activities set or not set.

Reduce Runtime Activities = true / Separate mails = false

This mode creates only one activity for all approvers. Use the following variable references in mails:

To - use ${participantEntries.mail} to add all participants of this activity into this field.

Language - use ${participantEntries[0].preferredLanguage} to select the language for the resulting mail text if you use e-mail nationalization.
Note: if the definition resolves to several languages, English is taken per default.

Body - use for example ${participantEntries.sn} to include all surnames separated with blanks into the mail text. Alternatively you can use the variable ${to.sn} to obtain the same result. If you use ${to[0].sn} you will obtain the sn of the first participant. Use the for statement (for example with the loop variable 'i') and ${to[i].sn} to process all participants as you need it.

Reduce Runtime Activities = true / Separate mails = true

A more comfortable solution is to send separate mails to each of the participants. In this case set the Separate mails flag and use these settings:

To - use ${participantEntries.mail} to add all participants of this activity into this field.

Language - use ${to.preferredLanguage} to select the language for the resulting mail text if you use e-mail nationalization.

Body - use for example ${to.sn} to include the surname into the mail text. You can address any other attribute of the participant here, for example ${to.givenName}.
Using ${to.gender} allows distinguishing text for men and women, for example:

There are various methods to fill the address fields of a mail template (From, To, CC, BCC). This section explains the features and provides some examples.

Read also the section Reduced Run-time Activities because this flag influences mail generation.

Some general rules apply for the field calculation:

Addressing a Single User

In many cases you send the e-mail to exactly one person. In this case you can use the expression:

If the mail attribute contains only one value, it retrieves a single mail address, for example: Nik.Taspatch@My-Company.com

If the mail attribute contains multiple mail addresses, the result is for example: Nik.Taspatch@My-Company.com Niki@gmx.com

Note that the addresses are separated by blanks.

If this expression is set in the To field, the user might get multiple instances of the same mail.

If this expression is set in the From field, the first address is taken, the others are ignored (depends also on the mail server type).

If you want to enforce only one value, you can use the expression:

There is no way to define which value is taken from the list.

Addressing Multiple Users

You can use the expression

to retrieve the mail addresses of all participants. The resulting string could be for example:

Nik.Taspatch@My-Company.com Niki@gmx.com; Lavina.Pitton@My-Company.com ; Retha.Wagner@My-Company.com ;

The addresses of one user are separated by blanks (here for Nik Taspatch), the users are separated by semicolon.

If you use this definition in the To field, you can work with the to variable in conjunction with the Separate mail flag. See the section Reduced Run-time Activities for more information.

You can use semicolon to define multiple expressions in one line, for example:

Defining Conditional Addresses

In some cases you might want to define conditional addresses. This is for example useful in privilege access certification workflows where you want to inform only the users that their privilege assignment is removed. Define a conditional expression:

which is a loop that filters all assignments where the userInfo flag is set to true:

The mail addresses are separated by a semicolon.

Using the “To” Variable

If you use expressions in the To address field that include the substrings “.mail” or “@mail” then a to variable (representing user objects) is set internally. This to variable can then be used in other expressions, too.

For example, in the message body:

Keep in mind that this kind of approach only works if the Separate mails flag is turned on.

You can define participants in many ways. The method described here is easy to understand, powerful and well suited to a directory object structure that works with links.

Select the static method from the drop-down selection in a Participants tab in approval activities. Here you can define a mix of

If an attribute (for example ${workflow.subject.owner}) contains several links, all are used as participants.

Start Objects

There are several start objects for dynamic participant definitions:

workflow.subject - the subject of the request workflow (for example a user, a privilege or a business object)

workflow.resources.dxrassignto - the resource(s) of the request workflow

workflow.initiatorEntry - the initiator of the workflow

previousParticipants - the previous participant (can be used during escalations). Note that you cannot use the participantEntries start object because this is the one that is in calculation.

Methods to set up dynamic definitions are:

One-level Definitions

These definitions use a link attribute at the start object.

${workflow.subject.manager} - retrieves the manager(s) of the subject (uses the manager link to look up the manager DNs)
${workflow.subject.owner} - retrieves all owner of the subject (uses the owner link to look up the owner DNs)
${workflow.initiatorEntry.manager} - retrieves the initiator’s manager.
${workflow.resources.dxrassignto@owner} - retrieves the privilege owner(s).
${workflow.resources.dxrassignto@owner.manager} - retrieves the manager(s) of the privilege owner(s).

Multi-level Definitions

Definitions of this type use a link chain to get the attribute where to retrieve the participants from.

${workflow.subject.manager.manager} - retrieves the manager of the subject’s manager (useful for escalation)
${workflow.subject.dxrLocationLink.manager} - retrieves the manager of the location the subject is assigned to

Relative Definitions

During escalation you can refer to the previous participant(s) of an approval activity.

${previousParticipants.manager} - retrieves the manager(s) of all participants of the previous activity during an escalation
${previousParticipants[0].manager} - gets the manager of the first participant of the previous activity during an escalation

Multiple Definitions

To retrieve participants from different links, use multiple lines in the static table of the Participants tab, for example:

${workflow.subject.manager} - retrieves the manager
${workflow.subject.secretary} - additionally retrieves the secretary
${workflow.subject.sponsor} - and finally evaluates the sponsor link

This section provides some examples of variable substitution as well as valuable tips and tricks.

Representing Fields and Strings

The syntax you use in field and string representations depends on the internal representation of a requested field (whether it is a string or an array of strings) and the location where the field is used.

Example 1:

might be resolved to

Example 2:

is resolved to true if sn = "Smith"

Evaluating the Resource Order Type

Use the attribute typeOfOrder to determine the resource order type for privilege assignments, for example:

The possible values are ADD, MODIFY or DELETE.

Creating Correct Salutations in Email

You can create correct salutation with these statements:

In an international environment, you may want to include the preferredLanguage attribute for correct salutation.

Creating Escalation Specific Bodies in Email

You can create escalation specific mail bodies by evaluating the variable ${escalationLevel}, for example:

The entire workflow configuration is passed to the server as an XML document. The configuration parameters for the job are part of this document. When the server starts the job, it passes am XML configuration object with the <job> element as the parent node. It should conform to the following structure:

basename:

The basename string value tells the server’s class loader the name of the folder in which to search for your job classes. It must be a folder underneath

install_path*/ids-j-domain-S*n/confdb/jobs.

In the above sample, the server assumes your classes are in the following folder:

install_path*/ids-j-domain-S*n*/confdb/jobs/myjob*.

class:

The full class name of your job implementation; that is, the class that implements the interface

com.siemens.idm.api.Job.

params:

The <params> element contains a list of <param> sub-elements with your configuration parameters. For each parameter, you specify its name and the value. It’s the responsibility of your job implementation to evaluate them.

To allow Identity Manager to configure an activity with your job, you must supply a component description. The component description extends an abstract object description of an activity. The activity creation wizard searches for activity component descriptions and presents them in a list.

Adding the Component Description LDAP Entry

You must add your component description LDAP entry underneath the workflow configuration folder in the Identity domain:

cn=Activity Types,cn=Configuration,cn=wfRoot,cn=<your domain>.

We recommend that you create your own subfolder (for example, "cn=Customer Extensions") to clearly separate your configurations from configurations installed with DirX Identity.

Please supply values for the following LDAP attributes. They help to present your activity appropriately in the wizard.

objectclass - needs the values dxmComponentDescription and top.

cn - the naming attribute.

dxmComponentType - needs the value activity for the activity creation wizard, which only presents component descriptions with this attribute value.

dxmType - categorizes the basic activity type. The following values are supported:

automatic: an activity that runs automatically without any human interaction. It is started by the server as soon as the start conditions of the activity evaluate to true. Typically, this is the value you should provide.

notify: an activity that can be used for notifications, especially in case of errors or at the end of a workflow. DirX Identity already supplies e-mail notifications.

people: an activity that requires human interaction. It is not applicable for your job implementation.

dxmActivityType - a string value that helps to further categorize the activity. It is displayed in the selection page of the create activity wizard.

description - the description that is displayed in the selection page of the create activity wizard.

dxmContent - the XML document that represents the component description.

Creating the Component Description XML Document

Use the following template for your own component description:

Leave most of the template unchanged. You only need to insert the name of your component, your job class folder, the class name of your job implementation and for each configuration parameter, a description of the property and its presentation. See also "Defining Configuration Parameters".

Element <componentDescription>, attribute name:

The name of your component description as it is displayed in the column "component" in the selection page of the activity creation wizard.

In the element named job: <element name="job" …​/>:

In <property name="basename":

In the <value> sub-element, enter the name of the subfolder in which the class loader of the IdS-J server searches for the classes of your job implementation.

In <property name="class":

In the <value> sub-element, enter the full class name of your implementation.

In <element name="params", sub-element <properties>:

For each configuration parameter, enter an element <property> with the following attributes:

name: the parameter name, for example, param1.

xmlNotation: always use the value "NameValueProperty".

elementname: always use the value "param".

type: designates the data type of the parameter. Common values are: java.lang.Boolean, java.lang.String.

Provide allowed values as a list of <value> sub-elements. Flag the default value by the attribute default set to true.

The presentation of your configuration parameters in the Identity Manager is specified in the <presentationDescription> element.

The <propertypage> sub-element defines a property page. Make sure that all your parameters are listed in the layout attribute. They are presented in the same order as the list. Pay special attention to the parameter names: they must be prefixed with the XML parent element names in XPath format. For our scenarios, this is always "job/params/". To present your parameters "param1" and "param2" you must enter:

layout="properties: job/params/param1, job/params/param2"

The presentation of your parameters is specified in the <propertyPresentations> element. Enter a <property> sub-element for each of your parameters.

Attribute name:

The name of your property in the same format as used for the <propertypage>. This means: Use "job/params/param1" for parameter "param1"!

Sub-element <label>:

The name of your parameter as it is displayed in the property page.

If you entered a list of allowed values in the <element><property> definition, Identity Manager automatically presents them as a combo box.

When an activity is to be started, the IdS-J server loads a class with the name configured in the <classname> sub-element of the <job>. The server expects that this class has a default constructor and implements the interface com.siemens.idm.api.Job.

This interface requires the following methods:

setConfiguration(IDMJob cfg):

The server calls this method before the run() method to hand over the job configuration.

It passes the configuration in a class that wraps the XML fragment containing the job configuration. The root element is the <job> element with the configuration parameters in its params/param element. See "Reading the Job Configuration" for details.

run(TaskContext ctx, Map modifications):

This method starts the job. The server passes two parameters.

The task context gives read access to the activity and workflow instance, especially to the workflow and activity states, the workflow initiator, the subject and the optional resources.

The job can indirectly modify the workflow by entering the desired modifications into the passed modification map. Use this facility to set the resulting activity state or application state.

Handling Retries

In error situations, the workflow engine re-starts a job according the retry configuration: retry limit and "wait before retry". The engine assumes an error if the job implementation throws an exception. As a result, the job implementation does not need to handle retries. It just throws an exception and relies on the workflow engine to start it again later on. If the job sets an application state (see "Modifying Instance Data" for information on how to do this), it is taken as application state for the activity after the last retry failed.

Activity Timeout

A timeout is indicated to the job via the TaskContext. If the job does not react or does not react in a timely fashion an interrupt for the thread is called. The resulting InterruptedException should not be ignored. For more information, see the Use Case documentation Java Programming in DirX Identity.

Importing Required Libraries

When compiling your class, make sure you have the following jar file on your classpath:

com.siemens.idm.server-api.jar
com.siemens.idm.requestworkflow-api.jar
dxmAPI.jar
dxmUtil.jar
dxmOrder.jar

For the API documentation, consult the following folder on your DVD:

Documentation\DirXIdentity\RequestWorkflows\index.html.

For sample sources, see the following folder on your DVD:

Additions\RequestWorkflows\samples.

The IdS-J server provides a convenience class XmlNodeMapImpl that holds the configuration parameters in a Map. Get a parameter string value using the parameter name as a key. Here is a sample snippet for a string and a boolean parameter:

See also the readConfiguration() method in the sample.

The configuration object passed in the run(…​) method allows us to obtain the activity and the workflow instance object as in the following sample snippet:

This gives us the interface of a standard workflow. Since we are working here with a request workflow, we want the specialized interface, which we get by class casting:

Now we are able to obtain some data from the workflow, such as the initiator, the subject and the resource(s). Here is a snippet that reads the DN of the workflow initiator:

In the following sections, we show how to read the subject and the resources. For reading other properties, see the javadoc of the API.

Reading the Workflow Subject

The workflow subject is the entry that represents

The subject is stored in the workflow instance as an XML object, which we call "Order". An order is basically an SPML request that is extended with some properties such as the activation date, the creator, and so on. There are several types of orders: Add- or Modify-Orders are used with a creation or an "approve-modification" workflow, while an Info-Order represents a subject that is not modified as with a user-assignment approval. Note that you can change an Add- or Modify-Order from within an activity, but not an Info-Order.

You obtain a subject via the request workflow instance:

There are a number of "getters" to read properties such as the DN, the order type (Add, Modify, Info, and so on) or the directory type (user, role, …​) of the order instance. Here are a few samples. For more details, see the API.

Note: if you want to modify the subject and store it persistently for further use in follow-up activities, don’t use the "setter" methods; use the modification object passed in the calling run(…​) method. See the section "Modifying Workflow Instance Data" for more details.

Reading the Workflow Resource(s)

A workflow instance may contain no resources, one resource, or more than one resource. For example, a workflow for creating a (user) object or approving its modification does not need a resource. In a workflow for approving a user-role assignment, the role assignment is the resource.

The resources in a workflow instance are very similar to workflow subjects: they are represented as an "Order".

To work with resources, you have the following alternatives:

To work with resources as orders, you obtain an array of resources from a workflow instance by issuing:

The following code snippet shows how to read attributes from a resource and set some value. For the complete code, see the sample delivered with DirX Identity.

To work with resources as strings:

Note: if you want to modify the resource and store it persistently for further use in follow-up activities, don’t use the setter methods. Use the modification object passed in the calling run(…​) method. See the section "Modifying the Workflow Instance Data" for more details.

Use caution when modifying a subject or a resource in a workflow instance. With a normal class, you expect to use the setter methods to store new or modified values. You can do this for orders, too, but the changes are not stored back in the workflow instance; they are lost when your job ends. To store your changes in the workflow instance and make them available to downstream activities, you must return them to the workflow engine as modifications.

An empty modifications map is passed to your job as parameter of the "run" method call:

Use this map to return your changes and make them persistent. Put the changed objects into the map using some predefined keys. The following snippets are taken from the sample job implementation delivered with DirX Identity and demonstrate how to store the changes for a subject or a resource as an order or an XML string:

There are other standard keys. You find them as static properties of the RequestWorkflowInstance interface. A very important key is KEY_ACT_APPLICATION_STATE to set the application state of an activity. Use it to set the activity state explicitly. A workflow designer can then easily configure different downstream activities depending on the state of your job implementation. The following sample sets the application state to success:

For more details on changing an order see the section Reading and Changing Orders.

You can use the workflow context to store application-specific information in a request flow activity and then read it later on in a downstream activity. The context allows you to store custom properties as you would in a Java map. You obtain the context from the request workflow instance as shown in the following snippet (for details, see "Reading the Workflow Instance Data"):

The following snippet shows how to put a property named "testtest" with the ID of the Java Virtual Machine into the context:

Don’t forget to set the modified context at the workflow!

Obtaining a property from the context is as easy as reading it from a map:

Subjects and resources in a workflow instance are orders. The section "Reading the Workflow Instance Data" shows how to obtain them from the workflow. Orders implement the interface com.siemens.dxm.api.order.Order.

An order is either of type InfoOrderRequest, AddOrderRequest, ModifyOrderRequest or DeleteOrderRequest (short: info order, add order, etc). The type depends on the workflow type and on the data with which the workflow was created. In a workflow with resources (that is, assignments for a subject user) the subject is always an info order. An info order contains only a number of attributes for the subject, no modifications. If the workflow is for creating an object (for example, creating a user), for approving subject attributes or for deleting an object, the order is of type add, modify or delete respectively.

Use the method getType to determine the type of the order. With getID, you obtain the object’s DN and with getValues(*propertyname)*, you get the values of an property as a string array. For more details, examine the appropriate API.

The following methods are provided for changing an order:

setSubjectDN(*dn)* / setResourceDN(*dn)*:

Sets the identifier (the distinguished name) of the subject with respect to the resource.

setProperty(*name,* value*)*:

Sets or changes attributes controlled in an order. Note that the behavior depends on the type of the order. For:

Info Order:

This method simply sets the value for the attribute. Changes are NOT stored in the subject entry in LDAP, they reside only in the workflow.

If the value is empty, or an empty String ("") or an array of length 0, the old attribute value is removed from the order.

Add Order:

Attribute changes are stored in the workflow and the apply Change activity stores them in the new subject / resource entry in LDAP.

If the value is empty, or an empty String ("") or an array of length 0, the old attribute value is removed from the order.

Modify Order:

Attribute changes are stored in the workflow and the apply Change activity stores them in the updated subject / resource entry in LDAP.

Modify orders are different from add orders in that they contain modifications for attributes. An attribute modification contains an operation. This means a setProperty overrides the property modification. Therefore, the name attribute is evaluated differently from the other order types:

It is expected in the format "*operation",* "*property-name"* where operation is add, replace or delete, name is the name of the property as you use it in getProperty or getValues.

Samples:

setProperty("add-description", "New Description")

adds the value "New Description" to the attribute"description".

setProperty("delete-mail", "sample@gmx.de")

deletes the value "sample@gmx.de" from the attribute "mail".

As in the add and info order, an empty value deletes the modification. For example:

setProperty("delete-mail", "") or setProperty("delete-mail", null)

deletes the modification previously produced with setProperty("delete-mail", "sample@gmx.de").

A setProperty("*name",* value*)* is not expected here. As empty values delete modifications, only a setProperty("*name"," ")* can be accepted for the modification.

When you have compiled your job classes and have produced a jar file, you must then deploy it to the IdS-J server. The class loader of the server searches the job-specific classes in a separate folder for your job underneath the server’s "confdb/jobs" folder. Suppose we have a job named "sampleJob". We need to create the folder

install_path*/ids-j-domain-S*n*/confdb/jobs/sampleJob/lib*

You need to place all the jar files your job needs underneath the lib subfolder. This is the jar file of your job implementation and optionally other third-party jar files that your job requires (and which are not yet available in the confdb/common/lib folder). If the class loader doesn’t find a class here, it searches in the confdb/common/lib folder.

Sometimes custom implementations need an LDAP connection to the Identity domain. There are two methods to obtain this information. We recommend using the job interface described in the following sections. The DomainSessionAccessor method is deprecated.

A job interface is available that provides access to the Identity domain, the subject and resource orders, and the job configuration parameters.

Implementing the Job

You need to derive your job class from the class com.siemens.idm.jobs.BasicJob. This class provides an extended run interface that supplies a SvcSession object that is managed in a session pool, subject- and resource orders and a map of configuration parameters.

The Interface

You need to implement the following interface:

A Sample Job

A sample job is provided on the DVD in the folder Additions → RequestWorkflows → samples (class SampleJobWithSession). It shows how to read job configuration parameters, to search objects in LDAP and to set the application state.

Deployment

The basic class com.siemens.idm.jobs.BasicJob is deployed in the jar file orderImpl.jar. Consequently, you can deploy your jar file to confdb/jobs/order/lib.

You can obtain the connection parameters from the IdS-J server using the static method getSessionClone() of the singleton DomainSessionAccessor. Here is a code snippet that shows how to perform this task:

Because this method clones the session, it can create memory problems and thus this method is deprecated. We recommend using the job interface described above.

ApplyChange activities are used in a request workflow to apply the changes stored in the subject and/or resource orders to the data store. The applyChange activities allow you to add a user hook that is called before and after the application of each order. You can use this user hook to modify the data before the change is applied or to change the order after the change is processed. Changed orders are written back to the workflow instance and can be read in successive activities.

Configuring the User Hook

To configure a user hook, enter its fully-qualified class name in the Class name text entry field of the activity’s Parameters tab. If you want to use the sample user hook, you must enter the class name com.siemens.idm.jobs.sample.SampleApplyChangesUserhook here.

The Interface

The user hook must be written in Java. It must implement the following interface:

A context object is passed to the user hook methods. The context object implements the following interface:

A Sample Job

A sample job is provided on the DVD in the folder Additions/RequestWorkflows/samples (class SampleApplyChangesUserhook). It shows how to set a unique ID at the subject order and adds a start date to a resource order before it is applied to the data store.

The postProcess call is not used in the sample; it has an empty body.

Deployment

The interface siemens.dxr.service.order.api.ApplyChangesUserHook is deployed in the jar file dxrServices.jar. You should deploy your jar file to confdb/commons/lib.

When defining a request workflow, select the universal automatic activity template Run socketed job. Connect it with other activities and define the start conditions. Use start conditions based on application state; for details, see the section "Understanding Request Workflow States" in the chapter "Request Workflow Architecture".

The Run socketed job already contains the following predefined configuration parameter names:

Class name for socket job - the parameter is accessible as className in the XML configuration of the job. This parameter is mandatory and must contain a fully qualified class name of a Java class implementing one of the following interfaces:

com.siemens.idm.jobs.socketed.api.CustomSocketJob

com.siemens.idm.jobs.socketed.api.CustomSocketSvcSessionJob

The specified class must be stored in the following folder:

install_path*/ids-j-domain-S*n*/confdb/jobs/socketed/lib*

1. Parameter to be passed to job - the parameter is accessible as paramOne in the XML configuration of the job.

2. Parameter to be passed to job - the parameter is accessible as paramTwo in the XML configuration of the job.

3. Parameter to be passed to job - the parameter is accessible as paramThree in the XML configuration of the job.

4. Parameter to be passed to job - the parameter is accessible as paramFour in the XML configuration of the job.

5. Parameter to be passed to job - the parameter is accessible as paramFive in the XML configuration of the job.

These parameters are optional and can be used to pass any configuration parameter value to the custom socket job. You can pass any value that can be stored as a common string: for example, a path to a file, a number or a boolean value. Note that the name of the parameter cannot be changed and you should document its meaning in the relevant socket job activity implementation. These parameters are also always available only as string constants. You need to convert these strings to the correct types in your socket job class if necessary.

The number of parameters cannot be changed without modifying the component description for the Run socketed activity job (Run socketed job.xml). If necessary, define a new component description. Do not rewrite the default one. See the section "Supplying a Component Description" in the chapter "Implementing a New Activity" for more details.

When running the activity, the IdS-J server will search for a class defined in the mandatory configuration parameter class name for socket job. This class must implement one of these very similar interfaces:

com.siemens.idm.jobs.socketed.api.CustomSocketJob - use this interface when no access to the Identity domain is required, it requires only one method:

executeSocketJob(TaskContext taskCtx, Map<String, Object> modifications, Order subject, Order[] resources, Map<String, Object> parameters, RequestWorkflowInstance wfInstance)

This method contains the main logic of the job. The server passes six parameters.

The task context gives read access to the activity and workflow instance, especially to the workflow and activity states, the workflow initiator, the subject and the optional resources.

The job can indirectly modify the workflow by entering the desired modifications into the passed modification map. Use this facility to set the resulting activity state or application state.

The subject contains the subject order of the request workflow as stored within the task context. It is a convenient way to access it directly.

The resources contain the resource orders of the request workflow as stored within the task context. It is a convenient way to access it directly. Note that the resource orders may be not available for some request workflow types.

The parameters map contains the values for predefined configuration parameters. The values are accessible for key names paramOne, paramTwo, paramThree, paramFour and paramFive as described in the section "Specifying Predefined Configuration Parameters".

The request workflow instance contains the object as it is stored within the task context. It is a convenient way how to access it directly.

com.siemens.idm.jobs.socketed.api.CustomSocketSvcSessionJob – use this interface when you need direct access to the Identity domain; it requires only one method:

executeSocketJob(TaskContext taskCtx, Map<String, Object> modifications, SvcSession session, Order subject, Order[] resources, Map<String, Object> parameters, RequestWorkflowInstance wfInstance)

This method contains the main logic of the job but this time the server passes seven parameters. The signature of the method and its logic are almost the same as the previous interface.

This interface also provides session-representing access to the Identity domain.

Handling States

We recommend using application state when returning a result of the activity to be used as a start condition for a next activity. Use constants from com.siemens.idm.requestworkflow.api.ApplicationState or a custom value and use them in the start conditions. See the section "Modifying the Workflow Instance Data" in the chapter "Implementing a Generic Activity" for more details.

Do not set state (com.siemens.idm.api.Job.STATE) directly. It will be set automatically to Succeeded if no exception occurs or to Failed.Temporary if an unhandled exception is thrown. See the section "Understanding Request Workflow Activity States" in the chapter "Request Workflow Architecture" for more details.

Importing Required Libraries

When compiling your class, make sure you have the following jar files in your classpath:

commons-pool.jar
com.siemens.idm.requestworkflow.jar
com.siemens.idm.requestworkflow-api.jar
com.siemens.idm.server-api.jar
com.siemens.idm.server-config.jar
com.siemens.idm.server-core.jar
dxcLogging.jar
dxiSocketedJob.jar
dxmAPI.jar
dxrServices.jar
ldapjdk.jar
storage.jar

Note that the list might not be complete since it depends on the customer extensions. You may also need to add jar files with missing dependencies to the deployment directory; see the section "Deploying the Job".

The socketed job framework provides methods and keys to access the predefined configuration parameter values:

See also the ParamListingJob class in the sample directory.

The socket job interfaces give you direct access to the request workflow instance, to the subject and to the resources if available. You can also read the participant of the previous people activities or read the initiator of the workflow. See the class ParamListingJob and Utils in the sample directory for these advanced examples.

The socketed job framework is based on common request workflow API. Use the methods described in the section "Modifying the Workflow Instance Data" in the chapter "Implementing a New Activity" for more details.

The socketed job framework is based on common request workflow API, use the methods described in the section "Read and Write Context Properties" in the section "Implementing a New Activity" for more details.

The socketed job framework is based on common request workflow API. Use the methods described in the section "Reading and Changing Orders" in the section "Implementing a New Activity" for more details.

The jar file containing compiled custom implementation of the socketed job APIs must be placed within the folder install_path*/ids-j-domain-S*n*/confdb/jobs/socketed/lib*. Do not add other jar files to this directory unless it is necessary due to class loader problems. It is mainly necessary when using other third-party dependencies.

When you create or modify a people activity, select the type class from the drop-down list at the top of the Participants tab.

In the "Class" field, enter the full class name of your Java class. For the sample class described here, enter: com.siemens.idm.participants.sample.FindParticipantsSample.

If your class needs configuration parameters, enter them in the "Parameters" table. For each parameter, enter the parameter name into the left column and the value into the right column. Suppose you want to read some data from a file; in this case, you might define a parameter "filename" in the left column and then enter the absolute path name of the file "c:\myconfigdata\findparticipant.properties" in the right column.

See the section "Implementing the Java Class" for information on how to read them in your Java class.

The Java class must provide a default constructor and implement the interface com.siemens.idm.api.custom.Participants. Optionally, it can implement the interface com.siemens.idm.api.custom.ParticipantsExtended: it enables the custom class to obtain a connection to the Identity Store.

Implementing the Participants Interface

For the Participants interface, the only method you need to realize is findParticipants(…​). The IdS-J server passes the following parameters from the workflow and activity instance:

operation - the operation string taken from the workflow definition.

subjecttype - the subject type taken from the workflow definition. In most cases, the subject of the workflow is a user.

subjectDn - the distinguished name of the workflow’s subject.

Note: If there is an escalation, the subjectDN is the DN of the participant of the previous level. For example, in the first escalation level, you get the DN of the original activity participant, in the second level, the DN of the participant of the first level. Nevertheless, you have access to the workflow subject via the activity. For more details, see the section "Reading the Workflow Instance Data". Here are the necessary commands:

com.siemens.idm.api.nodes.IDMActivity activity = _cfg.getActivity();
com.siemens.idm.requestworkflow.api.RequestWorkflowInstance rqwf = (RequestWorkflowInstance) activity.getWorkflow(); com.siemens.dxm.api.order.Order subject = rqwf.getSubject();

properties - a map of configuration parameters taken from the activity definition. See the section "Defining Configuration Parameters" for information on how to specify and set them in the workflow.

activity - the interface to access the activity instance and through it the workflow instance. Your class must return a collection of String objects that represent the distinguished names of the participants.

Implementing the ParticipantsExtended Interface

The ParticipantsExtended interface allows a participant finder to obtain a context, which especially gives access to an LDAP connection to the DirX Identity domain. This interface defines a setter for a ParticipantContext. The com.siewmens.idm.api.custom.ParticipantContext defines the following methods that are to be implemented:

LDAPConnection getLdapConnection() - returns a “netscape.ldap.LDAPConnection”. It is connected to the DirX Identity domain and you use it to retrieve any LDAP entries in the domain. You can also change any LDAP entry, so be careful when using it.

Reading Configuration Parameters

Reading the configuration parameters is very simple: just call the get(…​) method of the properties map and provide the parameter name as the key, as shown in this sample:

String filename = (String)properties.get("filename");

Note that the parameter values are treated as strings.

Returning Participants

The server expects the participants as a collection of strings.

The following code snippet simply constructs a list of DN strings and returns them:

ArrayList<String> res = new ArrayList<String>(1);
res.add("cn=Taspatch Nik,ou=Global IT,o=My-Company,cn=Users,cn=My-Company");
return res;

Importing the Required Libraries

When compiling your class, make sure you have the following jar files in your classpath:

dxmApi.jar
com.siemens.idm.server-api.jar
com.siemens.idm.requestworkflow-api.jar

For the API documentation, consult the following file on your DVD:

Documentation\DirXIdentity\RequestWorkflows\index.html.

When you have compiled your classes and produced a jar file, you must deploy it to the IdS-J server. Place it into the folder:

install_path*/ids-j-domain-S*n*/confdb/common/lib*

Your participants filter implementation should have a default constructor and implement the interface com.siemens.idm.requestworkflow.api.ParticipantsFilter. The only method of the interface is filterParticipants(…​). The additional interface com.siemens.idm.requestworkflow.api.ParticipantsFilterExtended allows you to obtain a context with the LDAP connection to the Identity domain.

Interface ParticipantsFilter:

The only method you must implement is: filterParticipants(…​). The server passes two parameters:

participants: the list of participants calculated so far, each as a distinguished name string.

activity: the current activity for which the participants are to be calculated.

The method returns the list of filtered participants as a collection of strings, each representing a participant’s distinguished name.

The following snippet shows you how to read the workflow initiator’s DN, exclude the initiator from the participants and return the new participant list:

Interface ParticipantsFilterExtended

This interface extends ParticipantsFilter and establishes the ParticipantContext. This allows obtaining an LDAP connection to the DirX Identity domain and thus to execute LDAP operations. You must implement the following methods:

public void setParticipantContext(ParticipantContext ctx): the server passes a com.siemens.idm.api.custom.ParticipantContext. See below.

Interface ParticipantContext

This interface provides the following method:

public LDAPConnection getLdapConnection(): it returns an LDAP connection to the DirX Identity domain.

Writing Logs

You can issue log messages that appear in the server’s log files. The server’s log support com.siemens.idm.jini.util.logging.LogSupport provides the usual log interface, especially the following methods:

log.error(…​): error message

log.warning(…​): warning message

log.info(…​): normal informational message

log.finest(…​): debug message

Your participant constraints implementation should have a default constructor and implement the interface com.siemens.idm.requestworkflow.api.ParticipantConstraints. Optionally it can also implement com.siemens.idm.requestworkflow.api.ParticipantConstraintsExtended. The only method of the interface is checkParticipantConstraints(…​).

Interface ParticipantConstraints

You must implement the only method checkParticipantConstraints(…​*)*. The server passes two parameters:

participants: the list of participants calculated so far, each as a distinguished name string.

activity: the current activity for which the participants are to be calculated.

A participant constraints implementation returns a ConstraintViolationException to notify the server that the participant list does not meet the constraint conditions. In the exception constructor, you can supply the desired resulting activity state and application state along with an error message that will be stored with the activity instance. This allows you to configure subsequent activities that are started in this case.

The following snippet shows you how to make sure that the list contains at least one participant:

If not enough participants are found, the server sets the resulting activity state to "SUCCEEDED" and the activity application state to "REJECTED".

Interface ParticipantConstraintsExtended

This interface extends ParticipantConstraints and establishes the ParticipantContext. This allows accessing the LDAP connection and thus to execute LDAP operations. You must implement the following methods:

public void setParticipantContext(ParticipantContext ctx): the server passes a com.siemens.idm.api.custom.ParticipantContext. See below.

Interface ParticipantContext

This interface provides the following method:

public LDAPConnection getLdapConnection(): it returns an LDAP connection to the DirX Identity domain.

Writing Logs

You can issue log messages that appear in the server’s log files. The server’s log support provides the usual log interface, especially the following methods:

log.error(…​): error message

log.warning(…​): warning message

log.info(…​): normal informational message

log.finest(…​): debug message

A joblet is a Java class source code that is compiled by the Java-based Server (IdS-J) at runtime. The server includes the body of the configured Java source code into a template, compiles it and loads the compilation unit.

The template contains the common parts of the Java source code implementing the com.siemens.idm.jobs.java.Joblet interface:

The leading package line

It is built dynamically including the workflow and activity name.

The common import statements

The class and interface method declaration.

And the trailing closing brackets for the interface method and the class definition.

You must provide the missing parts of the source code in two fields:

Imports: The additional import statements.

For each additional import, supply the full class name without the leading "import" and the trailing ";" strings.

Code: The method body.

See the section "Implementing a Joblet" for details.

A joblet must implement the com.siemens.idm.jobs.java.Joblet interface with the method:

public void run(IDMJob job, TaskContext taskCtx, Map modifications) throws Exception;

The server passes the following parameters when running the joblet:

Job: gives access to the job, which in turns allows reading the activity and the workflow instance.

Task Context: gives access to a map of context properties. It can be used as an application-specific properties container.

modifications: An empty map for returning modifications that are made on the workflow instance. This parameter should not be used in participant filters and constraints!

When implementing a joblet, you only need to provide the additions to the surrounding template: the additional class names to be imported and the body of the run(…​) method.

Note:

The joblets are compiled at runtime using Java 1.4 compiler settings. Do not include Java 5 constructs such as generics or the loop enhancements.

For the API documentation, consult the following file on your DVD:

Documentation\DirXIdentity\RequestWorkflows\index.html.

When you have compiled your filter and constraint classes, you must produce a jar file and then deploy it to the IdS-J server. The class loader of the server searches the filter and constraint classes in its common folder

install_path*/ids-j-domain-S*n*/confdb/common/lib*.

If you need additional jar files, place them into the same folder.

Conceptually, we distinguish between the following types of event-based workflows:

Provisioning Workflows

Typically account or group changes trigger a real-time workflow, as illustrated in the following figure.

Suppose a manager at Web Center or Identity Manager assigns a role to a user. DirX Identity resolves the resulting access rights, creates an account in the Identity Store, puts it into the member list of a group and sends two change events: one for the account, and one for the group. A workflow associated with the target system receives the events and synchronizes the changes in Identity Store with the connected system.

The same process occurs as result of a request workflow. Usually, the last activity in an approval or object creation workflow is the "apply change" activity. It stores the changes requested in the workflow and sends the same change events for accounts and groups as in the previous scenario.

Note that DirX Identity sends the changes only if the flag "Enable Real-time Provisioning" is set to active.

Password Workflows

Real-time provisioning workflows are also involved in password changes. A typical scenario is illustrated in the following figure.

Assume that a user changes her password in the Windows domain. the DirX Identity Windows Password Listener captures the new password at the domain controller and sends an appropriate change event. The "User Password Event Manager" receives the event, searches the Windows account and then the user entry and updates the password in the Identity Store. Then it finds all accounts of the user for which password synchronization is enabled (see the flag at the target system entry) and sends messages that request the password change at the connected systems. These requests are handled by a "set password" workflow. It takes the new password and if required, the current password out of the message and updates them at the connected system.

Nearly the same process occurs if the user changes her password with Web Center. The "User Password Event Manager" workflow finds the user directly with the DN given in the event, updates the password and sends the change requests for the accounts.

A user can also use Web Center to change the password of a privileged account. Web Center sends a password change event for the account, which is processed by the "Account Password Manager" workflow. It updates the password at the account in the Identity Store and sends the same password change request as in the previous scenarios to update the password at the connected system.

Event-based Maintenance Workflows

The maintenance workflows work only with the DirX Identity domain. They are invoked when a domain entry is created or changed, not only accounts or groups but also users, roles, permissions and business objects. Their processing depends upon the entry type, but typically they apply provisioning and consistency rules and check for broken links. The following figure illustrates maintenance workflow operation.

The workflows are triggered by a change event that is published by a number of sources:

The client publishes a change event for an entry if the corresponding entry type is activated in the domain’s event policy. The message topic includes the entry type, which allows the IdS-J server to invoke the appropriate maintenance workflow. The workflow analyzes the changed attributes and performs several maintenance tasks depending on the entry type. For example, the user maintenance workflow:

If in the course of a user resolution an account or a group is modified, the workflow publishes a provision request that triggers a provisioning workflow.

You can also define schedules for Java-based workflows. The IdS-J workflow scheduler starts the workflow at the scheduled times.

A scheduled workflow operates a little bit differently from the way it operates when triggered by an event. It synchronizes all entries from the source to the destination system. For a synchronization workflow, this means that the workflow reads all accounts and groups from Identity Store and updates them one after the other at the connected system.

If you want to define a schedule for cluster workflows (which can provision a set or cluster of homogeneous connected systems), you must specify a search filter for all target systems to be provisioned according this schedule. For each target system, the scheduler starts a workflow instance that provisions only the accounts and groups of this system.

Note that starting a real-time workflow manually or on a schedule may not make sense for all types of workflows. This is especially true for

You can also start a workflow manually in Identity Manager in one of two ways:

Note that starting a real-time workflow manually or on a schedule may not make sense for all types of workflows. This is especially true for

This section explains how to configure a global and a channel-specific user hook.

The global user hook is configured in the XML configuration of a job, which itself is part of an activity configuration. A channel user hook is configured for each channel. Their configuration parameters are the same.

A job is configured as part of an activity within a <workflow> element. The global user hook is part of the controller configuration. The XPath expression of the corresponding XML element reads:
workflow/activities/activity[@name='…​']/job/controller/operation/user hook.

A job configuration collects a number of <port> elements, which itself collect a number of <channel> elements. A channel user hook is a sub-element of the <channel> element. Here the XPath notation:
workflow/activities/activity[@name='…​']/job/port/channel/user hook.

The XML attributes of the <userhook> element include:

classname: The full class name of your user hook Java class. It must implement the IGlobalUserHook or the IUserHook interface.

implementationLanguage: Currently only the value "java" is supported. It’s also the default, if omitted.

data: The source of your user hook Java class.

code: The octets of the compiled unit. This property is loaded by the controller instead of searching a class from the class path. This property will be filled by the Identity Manager in the course of configuration.

Sub-properties of <userhook>: Some properties are denoted as property sub-elements as follows: <property name="…​" value="…​"/>. The following properties are evaluated by the controller:

sourcepath: The full path name of the Java file that contains the source of your user hook implementation. This property is supported for local testing.

A global user hook is called at the beginning and at the end of a job. It must implement the interface com.siemens.dxm.join.api.IGlobalUserHook with the following methods:

setGlobalContext

With this method, the controller passes a reference to the global context. It gives access to the connectors, the configurations of the job, the controller and the user hook and to the current working directory.

prolog:

The method prolog() is called at the beginning of a job, before any entry or channel is handled. It allows you to prepare a job and set any global properties into the job context.

Among other tasks, the global user hook can add its proprietary properties in the global context. The join engine passes the updated global context to each channel user hook. In order to avoid overlap of other property names, use custom prefixes such as org.myorg.mydep.MyProperty.

epilog:

The epilog() method is called at the end of the job. It allows you to close any open resources, such as file or network handles.

The join engine calls the channel user hook in various phases while it processes an entry. A user hook implements the interface com.siemens.dxm.join.api.IUserHook and optionally com.siemens.dxm.join.api.IUserHookExt. The following figure provides an overview of the API operations and when they are called from the join engine:

As shown in the figure, there are the following user hook operations:

prolog:

Before the first entry is processed, the join engine passes the environment properties of the source and the target channel to the user hook. These properties comprise the context properties set by the global user hook and a set of "specific attributes" taken from the following entries of the Connectivity configuration database: channel, connected directory, workflow, global configuration.

This action allows the user hook to open a file or a connection to another system or do some other preparation task. It may add its own properties to the target environment. The join engine reads them from the user hook at several times via the method getTgtEnvironment (see below).

processSourceEntry

After the join engine has read a source entry, it asks the user hook whether to process it. The processSourceEntry method receives the identifier and the list of attributes of the source entry and returns a boolean. In case it is false, the join engine skips processing this entry.

preUpdate

The join engine reads the joined entry from the target system. Then it calls the preUpdate method of the user hook (note: the method of the IUserhook API). As parameters it passes: identifier and attribute list of source and joined entry, references to connectors to source and target system. This action allows the user hook to read additional information from the source or the target, do some processing at the target or some other task before the entry is updated at the target system.

This method returns a boolean. If it is set to false, the join engine skips further processing this entry and continues with the next one.

For a method that is called after the mapping and before the update, see the preUpdate method of the IUserHookExt interface.

getSrcEnvironment

The join engine calls this method several times: before the prolog, before the mapping and before the epilog. It allows the user hook to extend the environment properties related to the source channel by its own proprietary ones.

getTgtEnvironment

The join engine calls this method several times: before the prolog, before the mapping and before the epilog. It allows the user hook to extend the environment properties related to the target channel by its own proprietary ones.

preUpdate (API IUserhookExt)

After the join engine has mapped the source entry to the target entry and before it updates the target entry, it calls the preUpdate method of the user hook, if it implements the interface IUserHookExt.
As parameters, it passes the identifier and attribute list of the source and joined entry, the mapped entry, and references to connectors to source and target system. This action allows the user hook to change the mapped entry, do some processing at the target or some other task before the entry is updated at the target system.

This method returns a boolean. If it is set to false, the join engine discontinues processing this entry and continues with the next one.

getCallDelete

When the join engine encounters a mapped entry with request type DELETE, it first asks the user hook whether a custom delete method must be called. When this method returns true, the join engine calls the user hook method delete(). Otherwise it performs the delete request at the connector using the identifier of the mapped entry.

delete

The join engine calls this method when an entry is to be deleted by the user hook instead of performing the delete request itself; that is, if the getCallDelete method returns true. It passes a reference to the connector for the affected system and the mapped entry. As a result, the user hook can issue its own request at the connector (for example, a modify or extended request) or perform other tasks without the connector.

postUpdate

After the entry has been updated, the join engine calls this method. It passes the identifier and the attributes of the source and the joined entry, the performed update request, the response with its result code and the source and target connector.

The update request and the response can be null if no update was performed because the entry was already up-to-date. These two parameters can also be null if the user-defined delete operation is used; in this case, no information about user-defined update requests and update responses is available; it is even unknown whether an update operation has been executed at all.

This action allows the user hook to perform additional requests for the updated entry both at the source and the target system.

This method returns a boolean. If it is set to false, the join engine discontinues processing this entry and continues with the next one.

epilog

This method is called after all the entries of a channel have been processed. This action allows the user hook to close all pending handles (for example, sockets or files).

For a detailed description of the parameters, see the Java interface documentation in the folder Documentation/DirXIdentity/RealtimeWorkflows.

Review the contents of the Additions\RealtimeWorkflows\samples folder in the product DVD for a sample implementation that demonstrates basic handling.

For details on how to read and set the identifier and attributes of source or target entries, see the section "Evaluating a Mapping Entry".

Deployment

Make sure the jar file containing your user hook implementation is deployed in the correct folder of your IdS-J server, which is:

install_path*/ids-j-domain-S*n*/confdb/common/lib*

It is possible to send an e-mail notification in a user hook. You can find the sample Java-based workflow using the mail notification for account creation in the sample workflows for Extranet Portal, which is the part of the sample My-Company connectivity scenario. See the chapter "Loading the Connectivity Scenario" in the DirX Identity Tutorial for more information about the My-Company scenario. The provided user hook can be found on the DVD as Java class NotifyMailAccountCreationUserHook.java. It implements in particular the method postUpdate, which takes the mail attribute of the account and creates a specially-handled SPMLv1 request; this request is then sent to connector identified by the name "notify". If the provided mail is valid and the notify activity is correctly configured, it sends the notification to that mail address about account creation. Tailor this class to your needs if you intend to use special mail notifications in a Java-based workflow.

Make sure the jar file that contains your user hook class is deployed in the correct folder of your IdS-J Server, which is:

install_path*/ids-j-domain-S*n*/confdb/common/lib*

DirX Identity provides a general user hook class UserHookRunExecutable, which allows running any executable configured in a realtime workflow channel object. It can be used immediately without any extra programming. Specify the class name com.siemens.dxm.join.userhook.common.UserHookRunExecutable in the General tab of the channel and specify the executable name and command line in the channel-specific attributes.

For the preUpdate and the postUpdate user hook methods, you can configure an executable with a command line in the channel-specific attributes post_executable, post_cmdline, pre_executable, pre_cmdline. In the postUpdate case, the executable is only called if the update (add or modify) of the object was successful.

Architecture

The following figure illustrates the architecture of running an executable from a user hook:

Concept

The following features are available:

The following samples are provided:

Command Line Parameters of the Executable

The command line parameters specified in the channel specific attributes post_cmdline and/or pre_cmdline can contain fixed parts and variable parts. The variable parts can reuse all mapping variables by specifying the source, target, env and joinedEntry constructs, like ${source.dxrName}, ${target.homeDirRoot}, ${env.domain}, ${joinedEntry.cn}.

Central (Shared) Script Folder

Beneath each Java-based Server’s repository folder, which can be specified at the Java-based Server object in the Connectivity Expert View, there is a subfolder scripts where the executables can be located. In a distributed Java-based Server environment, this high availability location can be shared by all running instances.

The absolute path of the scripts folder is put into the Java-based Server context and can be accessed from user hooks by the environment variable ${env.scripts}. It can also be specified in the channel-specific attributes; for example, in the post_executable or post_cmdline attribute.

Output File and Error Handling

By default, the executable’s standard output and standard error messages and the exit code are written to the Java-based Server log file. If the executable fails, the user hook preUpdate and/or postUpdate methods return “false” to the join engine according to the user hook API, which causes the join engine to pass an error record to the Audit Connector and to the Monitor View and to stop processing this entry.

You can also define executable return codes that you classify as successful by specifying the specific attributes post_ok_codes and/or pre_ok_codes for executables started in the related user hook methods. The return codes are specified as integer values and must be separated by blanks. If nothing is specified, the return code “0” is regarded as successful by default.

If the executable’s output is to be written to separate files, specify the output file names in the command line as parameters. The executable must interpret these output file names.

If you specify your own output files, we recommend including the Workflow Instance ID in the names of the output files to prevent running workflow instances started through further events from overwriting output files that have already been recorded. The Workflow Instance ID is also contained in the Java-based Server context and can be used by specifying the environment variable ${env.dxm.uh.wfInstID}.

The workflow name is accessible in the environment and must be specified by ${env.dxm.uh.wfName}.

Interrupting Executables

If the activity that starts the executable times out or the Java-based Server shuts down, the Java-based Server sets a cancellation flag. During a "graceful" shutdown period, the running activities (this is a standard task of the controller implementations) check this flag at certain times and finish the process. A good time to perform this task, for example, is after one event has completed in a scheduled synchronization. After the configurable graceful shutdown period has elapsed, the Java-based Server interrupts all running activities. If an executable has not yet finished, the UserHookRunExecutable class catches this interruption and kills the executable, which was started as an asynchronous process.

Killing Executables after a Configurable Time Period

Independently of this interruption scenario, the UserHookRunExecutable class starts the process running the executable asynchronously and asks for the process return value in a loop for a certain time (by default, 90 seconds) and then kills the process if it has not finished in this time frame. You can configure this time in milliseconds in the channel-specific attribute post_timeout for executables started in the postUpdate user hook method or in the pre_timeout specific attribute for executables started in the preUpdate user hook method.

Connection Parameters

If the activity’s connection parameters like server, user or password should be passed as parameters to the executable, you can extend the UserHookRunExecutable class by adding the desired parameters to the command line. For example, the connection parameters of the target connector can be accessed in a user hook the following way:

This coding example is already contained as a comment in the standard UserHookRunExecutable class provided as source code.

The bind parameters in the sample PowerShell scripts delivered with DirX Identity are kept in the scripts. The scripts read the password from a file that contains the password that you have saved encrypted with PowerShell.

A class that realizes the mapping of an identifier must implement the interface com.siemens.dxm.join.api.IMapIdentifier. It consists of one method:

Identifier mapId(MappingEntry source, MappingEntry joined, HashMap<String,Object> environment)

The join engine passes the following parameters:

source: the source entry, or null if no source entry exists, which occurs when validation workflows find entries at the target that have no corresponding source entry.

joined: the joined entry, or null if no joined entry has been found.

environment: a map of environment properties collected by the specific attributes taken from the affected channel, connected directory, activity and workflow entries. User hook implementations can append additional properties.

The identifier mapper must return the new identifier of the mapped entry.

For an example see the file Idmapping.java on the DVD in the folder Additions/RealtimeWorkflows/samples/mappings

For details on how to handle these parameters, see the following sections:

A class that realizes the mapping of an attribute must implement the interface com.siemens.dxm.join.api.IMapAttribute. It consists of one method:

MapResult mapAttr(String tgtAttrname, Request.Type reqType, MappingEntry source, MappingEntry joined, HashMap<String,Object> environment)

The join engine passes the following parameters:

tgtAttrname: the name of the target attribute.

reqType: the proposed request type. The attribute mapper can change it in the returned map result. Allowed types are: Request.Type.ADD, Request.Type.MODIFY, Request.Type.DELETE.

source: the source entry, or null if no source entry exists, which occurs when validation workflows find entries at the target that have no corresponding source entry.

joined: the joined entry, or null if no joined entry has been found.

environment: a map of environment properties collected by the specific attributes taken from the affected channel, connected directory, activity and workflow entries. User hook implementations may append additional properties.

The attribute mapper must return the map result. In the simplest case, it contains only one value for the attribute. But you can also set a series of attribute modifications, a set of operational attributes and also return a changed request type. The request type determines the request to be issued to the target system connector: add a new entry, modify the existing joined entry or delete the existing entry.

A note concerning deleted source entries: normally, the join engine deletes an attribute value in the target entry, if the mapped value is empty or null. If the source entry no longer exists, the mapping routines typically produce empty values for the mapped attributes. However, if you want the target entry just to be modified (for example, set the state to DELETED) or moved (tombstone!), you typically do not want the target attribute values to be deleted. To support this operation, the join engine deletes the attribute values only if the modification operation is set to "delete". By default, it is set to "replace". As a result, if you want a target attribute to be deleted if the source entry no longer exists, it is not sufficient to return an empty value. You must explicitly set the operation in the modification to "delete". The following code snippet provides an example:

For details on how to handle the input parameters, see the following sections:

A class that realizes the post mapping of an entry must implement the interface com.siemens.dxm.join.api.IPostMapping. It consists of one method:

MappedEntry doPostMapping(MappedEntry mappedEntry, Request.Type reqType, MappingEntry source, MappingEntry joined, HashMap<String,Object> environment)

The join engine passes the following parameters:

mappedEntry: the result of the previous attribute and identifier mappings.

reqType: the proposed request type. The attribute mapper can change it in the returned map result. Allowed types are: Request.Type.ADD, Request.Type.MODIFY, Request.Type.DELETE.

source: the source entry, or null if no source entry exists, which occurs with validation workflows when entries at the target are found that have no corresponding source entry.

joined: the joined entry, or null if no joined entry has been found.

environment: a map of environment properties collected by the specific attributes taken from the affected channel, connected directory, activity and workflow entries. User hook implementations may append additional properties.

The post mapping returns the new mapped entry. Post mapping is called after all attribute mappings and the identifier mapping have been performed.

The post mapping can modify all attribute modifications, the identifier, operational attributes and the request type. The request type determines the request to be issued to the target system connector: add a new entry, modify the existing joined entry or delete the existing entry.

For details on how to handle these parameters, see the following sections:

Make sure the jar file that contains your mapping class is deployed in the correct folder of your IdS-J server, which is:

install_path*/ids-j-domain-S*n*/confdb/common/lib*

A source or joined entry is represented as Java class com.siemens.dxm.join.map.MappingEntry. The mapping entry holds the entry’s identifier, list of attributes and operational attributes.

Read Identifier

Each entry has an identifier. It is modelled according the OASIS SPML standard. The identifier has a type (most often DN or generic string), an id value and optionally a list of identifier attributes. The following code snippet shows how to read the identifier value from the joined entry:

Read Attributes from the Source or Joined Entry

Each source and joined entry contains a list of attributes, where each attribute may have a list of values. The values are typically of type string, but may sometimes also be binary. The following code snippet shows how to read the string attribute 'sn' from a source entry. Reading from the joined entry is identical.

Reading a multi-value string attribute is almost the same. You get an array of strings:

The following snippet shows how to get a binary value and assure the attribute’s member type base64:

Note: Use lower-case notation for attribute names. When storing attributes internally in the hash map, the join engine uses the lower-case notation of the attribute name as a key.

For more details on how to handle attribute,s take a look at the Java integration framework.

Read an Operational Attribute

Reading an operational attribute from a source entry is nearly identical to reading a 'normal' attribute. Here a sample snippet for the (fictitious) attribute 'dxrPrimaryKeyOld':

Operational attributes, like the normal ones, can be multi-valued or binary.

Note: Use lowercase notation for attribute names. When storing attributes internally in the hash map, the join engine uses the lowercase notation of the attribute name as a key.

All mapping functions have access to environment properties, which are collected from the respective configuration entries (channel, connected directory, activity, workflow) or set by a global or channel user hook.

The environment properties are simply a hash map of objects identified by their name of type String. The following snippet read the standard property "user_base":

Setting an environment property is also as simple:

In order to avoid naming collisions, we recommend that you use an adequate prefix for your property names that is analogous to the one shown in the example: com.siemens.map.ldap.

The mapped entry is first built up by the identifier mapping and the list of attribute mappings. After that, the join engine passes the result to the post mapping (if configured). The post mapping also has access to the source and the joined entry. It can change the complete mapping entry: the identifier, the attribute modifications, the operational attributes and the request type.

The sections Identifier Mapping and Evaluating a Mapping Entry show how to read the identifier and the source and joined entry. This section shows how to read the mapping entry and modify it.

Identifier

Reading and setting the identifier is simply realized by a getter and a setter method as the following code snippet shows:

See the section on Identifier Mapping for information on how to work with the Identifier.

Attribute Modifications

You can read the modifications for a single attribute or get a map with the modifications of all attributes. Updating the modifications is done on a per-attribute basis as the following snippet shows:

For more details on working with modifications, see "Evaluating a Mapping Entry" and "Setting the Map Result".

Operational Attributes

Reading and modifying the operational attributes is very similar to the attribute modifications. You can either get them all as a map or read them one-by-one. Updating is done on a per-attribute basis:

For more details on working with operational attributes, see "Evaluating a Mapping Entry" and "Setting the Map Result".

Request Type

The post mapping can get the request type from the parameter list or read it from the mapped entry via the getter method. Updating it is done via the corresponding setter method:

The mapping result for an attribute consists of the following items:

Request Type

The request type determines the kind of operation to be issued at the target system connector: ADD, MODIFY or DELETE. For the list of allowed values see the static enumeration in the class com.siemens.dxm.join.util.Request.

Initially, the join engine proposes a value:

In the mapping function, you can change the value according your needs. The following code snippet shows how to set the type to DELETED, which results in a delete request:

Attribute Modifications

The mapping result contains a list of attribute modifications. Each attribute modification needs the attribute name, the modification operation (replace, delete, add) and the attribute value(s). The modifications are applied as they are, if the request is a MODIFY. In case of an ADD, the join engine transforms them to a list of attribute values; that is, it skips the operation. The mapping function does not usually need to be aware of this.

The following code snippet shows how to create a MapResult object, create one attribute modification with the attribute name and the default operation REPLACE, add an attribute value and set the new modification and a request type in the mapping result:

As you can see from the sample, it’s even possible to add a number of modifications for the same attribute or for a list of attributes.

Operational Attributes

The mapping function may append operational attributes to the mapping result. Note that they are specific for a connector or a SPML target service. Here is a short code snippet that shows how to create an operational attribute and add it to the mapping result:

If you want to implement logging, you can use a log support that provides some simple log methods. The following code snippet shows how to obtain the log support and issue a debug log message:

For logging messages with other levels, use the appropriate methods:

The messages are written to the same files as that of the other DirX Identity components.

The Java Eclipse Project dxmTestMapping can help you develop and test your Java mapping classes needed for a specific real-time workflow. The project is delivered on the DirX Identity DVD as a zip file and can be unpacked to any location in the file system. It has all the necessary libraries in its own subfolder and is independent of any installed DirX Identity files.

The mapping can be tested either by running the batch file runTestMapping.bat or by running the Junit-Test TestSample.java. The Junit Test is configured in build.xml, so it is run automatically by starting the build process with mkTestMapping.bat. It can also be started inside the project by configuring a Junit Test with the TestSample class.

In both cases (batch file or Junit Test), the agent framework main class AgtSessionExe is called with the configuration file src.test/confs/sample/conf.xml. The resulting trace and response files can be inspected in the src.test/confs/sample subtree.

The Java Eclipse Project dxmTestMapping consists of the following subtrees and files:

After the single mappings have been tested as described, each channel as it is configured in LDAP can be tested as a whole the following way:

Go to the corresponding LDAP channel, open the Mapping page and insert a new Java source code mapping if it does not yet exist. Go to the Java source mapping LDAP object and import your tested Java source code mapping file (like the EmployeeTypeSource.java mentioned above). Repeat this for all Java source code attribute mapping files belonging to this channel and then export the resolved channel configuration into a file and copy it into the channel part of your standalone conf.xml file.

Now the standalone batch script can be run again to check whether the LDAP configuration is also correct.

The environment property source path which you can see in the conf.xml sample no longer exists in the resolved channel, because at this time the compiled code exists in the channel section. As a result, the source path where the files to be compiled can be found if no byte code exists is no longer needed.

The connector filter is configured as part of the job configuration, which itself is part of an activity configuration. This section describes the XML format of the configuration that is passed to the framework. For the presentation in Identity Manager, see a filter entry beneath a port.

A job configuration contains a number of <port> elements. A <port> contains a <connector> and a list of <filter> and <channel> elements. A <filter> element represents the configuration of a connector filter.

XML attributes of <filter>:

classname: The full class name of the connector filter Java class; mandatory.

name: An optional name of the filter.

Sub-Elements of <filter>:

A <filter> allows only a number of <property> sub-elements. Each <property> supports the following XML attributes:

name: The name of the configuration property; mandatory.

value: The value of the configuration property.

Make sure the jar file that contains your connector filter implementation is deployed in the correct folder of your IdS-J server, which is:

install_path*/ids-j-domain-S*n*/confdb/common/lib*

Notes:

For more details on the interfaces, see the chapter on "Java Connector Integration Framework" in the DirX Identity Integration Framework Guide. You can also find information about reading the configuration and working with requests and responses in this guide. A sample is provided on the product DVD in the folder: Additions\SampleConnectorFilter.

The following figure illustrates the logical structure of the DirX Identity Connectivity standard script.

The control script is the script that starts the whole procedure. It contains all of the variables that control the rest of the procedure. The values of these variables are linked by DirX Identity references to the attributes of objects in the configuration directory. It also loads the central routines from the installation area and the profile, mapping and miscellaneous scripts from the job object.

The control script calls the profile script, which performs the central algorithm. Different profile scripts are delivered to provide different basic algorithms. Most workflows use the standard script Profile Script, while others use the HDMS Export Profile Script or the LDIF Change Profile Script.

One of the most important parts of this algorithm - the mapping script - must be highly configurable, since it is individual to each workflow. The script is divided into a mapping that occurs before the join operation and a post join mapping that occurs after the join operation.

All scripts can call common routines provided by the central script (routines that are common to any workflow) and the common script (routines that are used by this type of workflow).

The profile script calls local routines (hooks). Default routines for these hooks are loaded with the user hooks default script. You can establish your own extensions by providing routines in the user hooks script (they will overload the default routines).

We’ll use an example to explain the physical structure of the Connectivity standard script and its relationship to other objects in the configuration database and the installation area. The following figure illustrates this example.

The job MyMetaCPjob references the MetaCP agent that is of type Meta Controller, which is described by the "Meta Controller-Job.xml" definition. The job also relates to channels (here Channel 1) that access the LDAP directory (for example, MetaStore), which is of type LDAP and is described by the "LDAP-ConnDir.xml" definition.

The mapping script and the user hooks script are local objects of the workflow. They are downloaded to the work area before each workflow run. Only some of the default application workflows initially contain a user hooks script (for example the RACF workflows).

The central script, the common script, the post join default script and the user hooks default script (a template) are located in the installation area of DirX Identity (path: install_path*\lib\centralTcl*). They are part of the installation and will not be downloaded before each workflow run. Because the common script’s size is more than 130 KB, this saves time. For information purposes, a copy of these scripts is shown at the user interface level in the configuration database.

Please note that changing these script copies has no effect! You should instead copy the user hooks default script as an individual user hooks script or post join script under your job object (don’t forget to link it to the job) and modify the routines as required. This user hooks script and all of the other miscellaneous scripts will be downloaded before each workflow run.

The control, profile, common, post join default script and user hooks default scripts (together with the messages script that contains all messages) are located in the central configuration area in the section Tcl → Default. Only the control, profile and messages scripts will also be downloaded before each workflow run.

Warning: You are not allowed to change the central or common scripts (because any changes will be overwritten during update and upgrade installations!). Instead, you can copy a routine you’d like to change to your local user hooks script. This routine overloads the routine from the central script. The advantage of this method is that you can view all of your changes in one place and that an exchange or update of central script will not affect your workflow at all.

The Connectivity standard script’s control script contains all of the variable settings; that is, constants or references to attributes of other objects in the configuration database. These variable settings are grouped into the following sections:

The control script loads the standard scripts in the following sequence:

The control script’s loading logic relies on Tcl’s routine overloading mechanism, in which the last loaded routine is used.

The control flow for the standard script consists of several steps. The prolog step prepares all of the necessary prerequisites. The process entry loop reads entries from the source, maps the entries, then joins the mapped entries and writes them to the target. The epilog step closes all channels and handles and performs notifications if necessary.

The profile script contains only the main logic. All detailed routines are contained in the common script or the central script. The following figure illustrates the profile script algorithm.

Profile Script - Prolog

The prolog step performs the following tasks:

Now the source and target are prepared. Next, the loop on all entries must be performed.

Profile Script - Process Entry Loop

The profile script’s standard entry processing loop (used by the profile.tcl script) performs the following tasks:

The sequence of steps is different depending on the Directory Type.

If Directory Type = LDAP, the following steps are performed:

If Directory Type = FILE, similar procedures are called:

Profile Script - Calculate Action

The profile script’s "calculate action" subroutine calculates the action to be taken based on any change type, source entry status, and target entry conditions, as illustrated in the following figure.

As shown in the figure:

If none of these conditions is met, the action is set to mod.

Profile Script - Entry Handling

Based on the calculated action and the result of the join operation, the entry is handled as shown in the following figure.

As shown in the figure:

After the entry processing, a user hook (uh:LoopExtraFunction) allows you to define user-specific additional processing.

Note: In the loop, an error means that the workflow’s result will be Warning. Otherwise one single erroneous entry would abort the workflow.

Profile Script - Epilog

The profile script’s epilog step performs the following tasks:

Profile Script - Delete Entries

The delete routine is either called from the central processing loop for each entry or from the separate loop at the end for all unmarked entries. The following figure illustrates its logic:

As shown in the figure, the delete routine:

The following set of switches control the script’s operation:

The Connectivity standard script currently implements two basic notification mechanisms:

The Connectivity standard script allows global unique identifiers (GUIDs) to be generated for each entry that is to be imported into the Identity Store. See the "GUID Generation" section for more information. The parameters for this generation are stored in the field variable GUIDparam.

The meta controller can generate a lot of trace information, and you can use the switches Trace Level and Debug Trace to control the granularity of this output. The parameter Max Trace Entries controls the number of hits that are output during a join operation. Trace information can be written into Trace Files or Report Files.

The Statistics switch allows you to control whether or not the meta controller writes standard statistics. If you disable the standard statistics, your script must provide its own statistics.

This set of parameters is necessary to connect correctly to the specific type of the source connected directory. The most important parameters are the Directory Type and the Directory Subtype, which determine the behavior of the connected directory.

The script generally needs the file name of the attribute configuration file, which is controlled via the parameters File Name and Encoding.

If Directory Type = LDAP, the additional parameters are required to perform an LDAP bind. These parameters are: Server Address, Protocol, User, Password, Authentication, Protocol and SSL Connection (see the Service and Bind Profile configuration objects for details).

If Directory Type = FILE, the following parameters are necessary to handle the file correctly: File Name, File Format, File Mode and Encoding (see the section File Item configuration object for details).

The input channel definition allows access to the related connected directory.

The parameter Selected Attributes defines he list of attributes that must be handled.

If Directory Type = LDAP, a Base Object, the Subset definition, a Search Filter optionally together with an OR Filter and whether the result is to be sorted (Sorted List together with the Sort Key and the Sort Order) must be defined (see Export Properties for details).

You can use the switch Read DN Only or Paged Read together with Page Size to optimize memory consumption.

If Directory Type = File, no additional parameters need to be specified in the input channel definition.

This set of parameters is necessary to connect correctly to the specific type of the target connected directory. The most important parameters are the Directory Type and the Directory Subtype, which determine the behavior of the connected directory.

The script needs generally needs the file name of the attribute configuration file, which is controlled via the parameters File Name and Encoding.

If Directory Type = LDAP, the following additional parameters are required to perform an LDAP bind: Server Address, Protocol, User, Password, Authentication, Protocol and SSL Connection (see the Service and Bind Profile objects for details).

If Directory Type = FILE, the following parameters are necessary to handle the file correctly: File Name, File Format, File Mode and Encoding (see the section File Item configuration object for details).

The output channel definition allows access to the related connected directory.

The Selected Attributes parameter defines the list of attributes to be handled.

If Directory Type = LDAP, a Base Object, the Subset definition, a Join Expression (or alternatively Expert Filters) and whether the result should be sorted (Sorted List together with the Sort Key and the Sort Order) must be defined (see Import Properties for details).

You can use the switch Read DN Only or Paged Read together with Page Size to optimize memory consumption.

If Directory Type = File, no additional parameters need to be specified in the output channel definition.

Entry handling parameters are also required to define the behavior at the target connected directory side. This is the Import Mode that controls whether the script works in merge or replace mode.

The Add Entries, Superior Info, and the source and target Add Marking Attribute and Add Marking Value parameters can control the addition of entries.

The Modify Entries, Modify Marking Attribute, Modify Marking Value and Rename Entries switches control entry modification.

The switches Delete Entries, Deletion Mode, the source and target Del Marking Attribute and Del Marking Value and Keep Objects control entry deletion.

DirX Identity provides a pre-configured handling of the operational attributes. By default, dxmOprMaster, dxrStartDate, dxrEndDate and dxrState are used as attribute types if the switch Operational Attributes is on. You can select your preferred set of operational attributes in the user hooks script. The following description works with the standard set of operational attributes.

These attributes are only handled for entry masters depending on the calculated action.

DxmOprMaster Handling

Entry and Expiration Date Handling

Both date values are always set (empty fields cannot occur):

Status Handling

DirX Identity uses a two-step approach to make the configuration of the base object fields in channels easy and consistent. The following figure illustrates this approach.

The Base Object field in an input or output channel can contain values like:

<?$src_base_obj/> or <?$tgt_base_obj/>

These values are reference variables, which almost completely hide the complexity of references. The DirX Identity default applications contain the following reference variables:

<?$src_base_obj/> - occurs in input channels. Points to the source connected directory to the specific attribute base_obj (named Creation / Search Base at the user interface).

<?$tgt_base_obj/> - occurs in output channels. Points to the target connected directory to the specific attribute base_obj (named Creation / Search Base at the user interface).

<?$src_master_name/> - occurs in input channels. Points to the source connected directory to the attribute dxmMasterName (named Master Name at the user interface in the Operational Attributes tab).

<?$tgt_master_name/> - occurs in output channels. Points to the target connected directory to the attribute dxmMasterName (named Master Name at the user interface in the Operational Attributes tab).

<?$tgt_machine_name/> - occurs in output channels. Points to the service object of the target connected directory to the attribute dxmAddress (named IP Address at the user interface).

<?$tgt_server_address/> - occurs in output channels. Points to the service object of the target connected directory to the attribute dxmAddress and dxmDataPort (named IP Address and Data Port at the user interface). Note: This reference does not work for SSL connections.

You can find the definition of these reference variables in the control Tcl script or at the start of the INI files. The definitions are contained in comments because they only set the variable content that is used later on in other places. They are not visible to the Tcl or INI script. Note: another way to hide this information is to use set_nv instead of set for the variable definition, but this technique makes debugging more difficult because you cannot see the evaluated values.

The <?$src_base_obj/> and <?$tgt_base_obj/> reference variables point to the base_obj fields in the connected directories. To make the values here as independent as possible of a specific directory implementation, the values in the base_obj fields can also contain references, for example:

ou=mthb,<?Configuration@SpecificAttributes(BaseNode)/>

The reference to the specific attribute Base Node allows you to set a central definition of the start node in the directory. For example, DirX Directory delivers samples that start with o=My-Company. In the example (which is valid for most workflows in DirX Identity’s default applications), the workflows use ou=mthb,o=My-Company as the base point.

Other variables, such as the Tombstone Base in a connected directory’s Operational Attributes tab, can also use this base value, for example, ou=tombstone,<?Configuration@SpecificAttributes(BaseNode)/>. This method creates very consistent scenarios that can easily be adapted to new situations.

Another example is the setting in the Search Base field of the Import Properties tab of the Ident2ADS workflow: LDAP://<?$tgt_machine_name/>/<?$tgt_base_obj/>. In this case, the search base is built from a constant "LDAP://", then the target machine name, another constant "/" and then the target base_obj.

Fields like Search Filter, OR Filter, Expert Filter or Replace Filter in input or output channels can contain simple or complex LDAP filter expressions, and they can also contain references. For example:

\{dxmOprMaster=<?$src_master_name/>}

This filter searches for all entries that contain the value of the src_master_name reference in the dxmOprMaster attribute. Simply change the Master Name field of your source connected directory to handle another master source. The advantage of these fields is that both the import and export workflows use them. As a result, you don’t need to set two different values in each workflow - one central change is sufficient.

In local GUID generation, a GUID can be generated from a local unique identifier and a unique prefix from the source system. The employeeNumber is a good example of a unique source system identifier. You define this attribute type in the source connected directory’s Local GUID Attribute field.

A unique prefix is necessary for creating a unique identifier for the entire scenario. This prefix must be defined manually. It can be stored in the dxmGuidID attribute value of the source connected directory (GUID Prefix).

In the target connected directory, you must define the GUID Attribute, which stores the GUID values.

DirX Identity Connectivity provides an algorithm that allows for the creation of unique integer numbers. In this case, the highest already used value is stored in a special attribute dxmActualGUIDvalue in the target connected directory object.

To generate a new GUID value, this value is retrieved, increased by one and stored again in the actual GUID value attribute. The algorithm guarantees that double generation of a number is impossible.

Because each add entry operation would require an additional read and a write operation to this actual GUID attribute, it is possible to reserve n GUID values with one read/write operation. If all of these numbers are not used, this method may lead to unused numbers. The highest possible number (2.147.483.647 for Windows) limits this method. You can specify the block size with the GUID Generation Block Size parameter in the job object.

DirX Identity Connectivity provides the following user hooks for implementing user-defined GUID generation:

The following Tcl interfaces are provided in central.tcl:

exec_cmd

Executes a metacp command and terminates on error.

exec_cmd executes a given command and returns the result of the executed command. The global variable debug_trace should be set to one of the values 8, 9, 12, 13 to make command trace information available in the trace file. The command meta initialize should be the very first command that is executed by exec_cmd; otherwise tracing can’t be successfully performed.

When serious errors occur, exec_cmd terminates with exit code 10. exec_cmd does not handle some error situations; for example, the error "METACP 4852" (“object doesn’t exist” in case of a search operation) or the error "METACP 4515" (“no more results in a paged result request”). In these cases, these error codes are returned.

Synopsis:
exec_cmd command directory_subtype

Parameters:
command - the command to be executed
dir_subtype - the directory subtype, for example, RACF

Global variables used:

errorCode - Tcl error code variable

debug_trace - level of debug tracing
0 – no trace
4 – Tcl variable trace to stdout
5 – Tcl variable trace to file
8 – command trace to stdout
9 – command trace to file
12 – Tcl variable trace and command trace to stdout
13 – Tcl variable trace and command trace to file

trace_file - the name of the trace file

notify_not_ok - a flag that indicates whether a notification should be sent in case of errors/warnings

notify_notok_file - a notification file

DEBUG_COMMAND indicates that Tcl commands should be traced

Return values:

result - on success, the result string of the executed command.

errorCode - on error, the error code of the executed command (for errors that are not serious)

Exit codes:
10 on serious errors

Example:

getCurrentTimeGMT

Returns the current time as a GENERALIZED_TIME string.

Synopsis:
getCurrentTimeGMT

Parameters:
None.

Global variables used:
None.

Return values:
time_value - the current system time as a GENERALIZED_TIME string

Example:

int2zulu

Converts a time in seconds into a GENERALIZED_TIME value

Synopsis:
Int2zulu [time_val]

Parameters:
time_val - a time value in seconds (optional); if omitted, the current system time is used.

Global variables used:
None.

Return values:
value - time value as GENERALIZED_TIME string

Example:

trace_out

Writes trace information to the trace file.

trace_out writes the strings given in the parameters string1, string2, … to the trace file, if the global variable debug_trace permits the operation. The parameter mode defines the kind of information that string1, string2, … represent. If the value of mode matches the value of debug_trace, then the trace information will be written. mode is a bit combination of the global variables DEBUG_VARIABLE, DEBUG_COMMAND, DEBUG_LEVEL1, …, DEBUG_LEVEL4.

Synopsis:
trace_out mode string1 [string2 ..]

Parameters:
mode - the type of information to be written
string1, string2 … - a list of strings to be written

Global variables used:
debug_trace - for details, see the description in exec_cmd
DEBUG_IN_FILE - defines that trace information should be written into the trace file; if not set, tracing is sent to stdout
DEBUG_VARIABLE - defines that variable tracing is switched on
DEBUG_COMMAND - defines that command tracing is switched on
DEBUG_LEVEL1 - defines that trace information of level 1 will be written
DEBUG_LEVEL2 - defines that trace information of level 2 will be written
DEBUG_LEVEL3 - defines that trace information of level 3 will be written
DEBUG_LEVEL4 - defines that trace information of level 4 will be written

Return values:
None.

Example:

zulu2int

Converts a GENERALIZED_TIME value to its representation in seconds

Synopsis:
zulu2int time_val

Parameters:
time_val - a GENERALIZED_TIME value

Global variables used:
None.

Return values:
seconds - the time value in seconds

Example:

The following Tcl interfaces are provided in user_hooks_default.tcl:

uh::Delete

Defines a user-specific entry deletion method.

uh::Delete implements a user-defined method of deleting an entry. You define the action to be executed when an entry should be deleted. The routine is used when the deletion_mode switch is set to "User". This routine is used in the default applications during the main loop processing and during the processing of unmarked entries after the main loop.

Synopsis:
uh::Delete tgt_data

Parameters:
tgt_data - an array of attribute values that represent the object to be deleted

Global variables used:
tgt_conn_param - the connection parameters to be used when performing a directory update operation

Return values:
0 in case of success
1 in case of errors

Example:

uh::Epilog

Closes and finalizes everything that is needed after the loop has been processed (for example, the closing of additional files)

Synopsis:
uh::Epilog

Parameters:
None.

Global variables used:
None.

Return values:
0 - on success

return_code - on error

Example:

uh::ErrorHandler

Handles specific errors that were originally returned in "errorCode" (in exec_cmd).

uh::ErrorHandler is called by the exec_cmd procedure when errors occur. Because error operation is different for various directory systems (for example, RACF is very restrictive and very often returns the LDAP error “LDAP_OTHER”), exec_cmd must handle these situations. You should implement uh::ErrorHandler to return “0” for errors that are not serious and that do not prevent the Connectivity standard script from continuing its entry-processing functions, and return “1” for serious errors.

Synopsis:
uh::ErrorHandler command result dir_subtype

Parameters:
command - a command string that has been executed by exec_cmd
result - a result returned by exec_cmd
dir_subtype - a directory subtype, e.g., RACF

Global variables used:
errorCode - Tcl error code variable

Return values:
0 if a specific error has been handled by that procedure
1 if the error has not been handled by that procedure

Example:

uh::GenerateTombstoneDN

Generates a DN when an object that should normally be deleted is moved to a different tombstone branch of the DIT.

uh::GenerateTombstoneDN generates the tombstone DN by exchanging the target search base object with the tombstone base object.

Synopsis:
uh::GenerateTombstoneDN current_dn

Parameters:
current_dn - the DN of the object to be moved to the tombstone branch

Global variables used:
tombstone_base - the base DN of the tombstone branch
tgt_search_param - the target search parameters

Return values:
new_dn - tombstone DN

Example:

uh::Initialize

Initializes the default applications.

uh::Initialize is used to initialize the environment of the default applications. Because it’s the very first statement of the Connectivity standard script, the meta controller’s meta initialize operation has not yet been called, so no tracing can be done in that routine. The routine currently initializes the names of the operational attributes.

Synopsis:
uh::Initialize

Parameters:
None.

Global variables used:
opr - an array of operational attribute names

Return values:
0 - on success
1 - on error

Example:

uh::LoopExtraFilter

Filters entries that are not to be processed in the loop (for example, RACF does not permit entries to be read with a filter condition; filtering must be performed in the central script logic on a per-entry basis).

For entries that should be ignored, the return code of the function should be set to 1; otherwise, 0 should be returned.

Synopsis:
uh::LoopExtraFilter data

Parameters:
data - the name of the Tcl array that holds the source data

Global variables used:
None.

Return values:
0 if the source entry will not be ignored
1 if the source entry will be ignored

Example:

uh::LoopExtraFunction

Performs additional actions for an entry.

uh::LoopExtraFunction allows to perform additional actions for an entry (for example, to write additional log file information into a special file). Both the names of the source data array and the target data array are passed to the routine so that the user can operate on both arrays. In addition, the executed operation is passed in the operation parameter, the result of that operation in the rc parameter.

Synopsis:
uh::LoopExtraFunction source target operation rc

Parameters:
source - the name of the Tcl array that holds the source data
target - the name of the Tcl array that holds the mapped target data
operation - the operation that has been performed for the entry:
“add”: if the entry has been created
“del”: if the entry has been deleted
“mod”: if the entry has been modified
“modifyDN”: if the entry’s name has been changed
“error”: if the entry caused multiple matches
“done”: if the entry doesn’t exist in the DIT

rc - the return code of the directory operation

Global variables used:
None.

Return values:
0 if the source entry will not be ignored
1 if the source entry will be ignored

Example:

set rc [uh::LoopExtraFunction rh_file rh_ldap $action $update_res]

uh::LoopPerformJoin

Performs a user-specific join routine when an entry is exported to FILE. You can use this routine to calculate delta information by comparing the current set of entries with a previous set.

Synopsis:
uh::LoopPerformJoin source target joined_entry num

Parameters:
source name - the Tcl array that holds the source data
target name - the Tcl array that holds the mapped target data
joined_entry - OUT: the array of data fields of the joined entry
num - OUT: the number of matching entries

Global variables used:
None.

Return values:
0 on success
1 on error

Example:

Note: When using name spaces, there might be problems using the variable source and target. As an alternative the following expression can be used:

"rh_<?job@InputChannel-DN@RoleName/>" for source
"rh_<?job@OutputChannel-DN[Anchor=DATA]@RoleName/>" for target

uh::Preprocessing

Prepares everything that’s needed before the profile code is executed. No files or handles are open at this time.

Synopsis:
uh::Preprocessing

Parameters:
None.

Global variables used:
None.

Return values:
0 on success
1 on error

Example:

uh::Prolog

Handles everything that’s needed before the loop is entered (for example, opening additional files or setting additional control variables with references).

Synopsis:
uh::Prolog

Parameters:
None.

Global variables used:
None.

Return values:
0 on success
1 on error

Example:

The following Tcl interfaces are provided in post_join_mapping.tcl:

uh::LoopPostJoin

Performs additional mapping before calling the ADD, DELETE or MODIFY operation. Mappings that are commonly used for ADD, DELETE, and MODIFY operations should be listed in the body of this procedure. Internally, uh::LoopPostJoin calls one of the following subroutines:

The operation-specific mappings should be listed in one of these procedures.

The action parameter is used as an input and an output parameter. When used as an input parameter, it indicates the directory operation that should normally be performed. This operation can change if the situation requires an operation other than the initially calculated one.

Synopsis:
uh::LoopPostJoin source target joined_entry action

Parameters:
source - the name of the Tcl array that holds the source data
target - OUT: the name of the Tcl array that holds the mapped target data
joined_entry - the name of the Tcl array that holds the joined entry
action - IN/OUT: the calculated action, which is one of the following values:
“add” for object creation
“mod” for object modification
“del” for object deletion

Global variables used:
None.

Return values:
0 - indicates successful post mapping
1 - indicates an error in post mapping

Example:

uh::postMappingAdd

uh::postMappingAdd allows you to perform additional mapping procedures before the final directory update operation (which normally is an ADD operation) is called.

The action parameter is used as an input and an output parameter. When used as an input parameter, it indicates the directory operation that should normally be performed. This operation can change if the situation requires an operation other than the initially calculated one.

Synopsis:
uh::postMappingAdd source target action

Parameters:
source - the name of the Tcl array that holds the source data
target - OUT: the name of the Tcl array that holds the mapped target data
action - IN/OUT: the calculated action, which is one of the following values:
“add” for object creation
“mod” for object modification
“del” for object deletion

Global variables used:
None.

Return values:
0 - indicates successful post mapping
1 - indicates an error in post mapping

Example:

uh::postMappingDel

uh::postMappingDel allows you to perform additional mapping procedures before the final directory update operation (which normally is a DELETE operation) is called.

The action parameter is used as an input and an output parameter. When used as an input parameter, it indicates the directory operation that should normally be performed. This operation can change if the situation requires an operation other than the initially calculated one.

Synopsis:
uh::postMappingDel source target joined_entry action

Parameters:
source - the name of the Tcl array that holds the source data
target - OUT: the name of the Tcl array that holds the mapped target data
joined_entry - the name of the Tcl array that holds the joined entry
action - IN/OUT: the calculated action, which is one of the following values:
“add” for object creation
“mod” for object modification
“del” for object deletion

Global variables used:
None.

Return values:
0 - indicates successful post mapping
1 - indicates an error in post mapping

Example:

uh::postMappingMod

uh::postMappingMod allows you to perform additional mapping procedures before the final directory update operation (which normally is a MODIFY operation) is called.

The action parameter is used as an input and an output parameter. When used as an input parameter, it indicates the directory operation that should normally be performed. This operation can change if the situation requires an operation other than the initially calculated one.

Synopsis:
uh::postMappingMod source target joined_entry action

Parameters:
source - name of the Tcl array that holds the source data
target - OUT: name of the Tcl array that holds the mapped target data
joined_entry - name of the Tcl array that holds the joined entry
action - IN/OUT: the calculated action, which is one of the following values:
“add” for object creation
“mod” for object modification
“del” for object deletion

Global variables used:
None.

Return values:
0 - indicates successful post mapping
1 - indicates an error in post mapping

Example:

The default applications use a set of global variables that are defined in control.tcl. Many of these variables can be used in the user hook routines, if not already passed as argument.

The description of the user hook interfaces lists only the global Tcl variables that are currently used by the given routine. Because you can set up very complex user hooks, the description of an interface doesn’t list all of the global variables that are available. It’s up to you to select the relevant variables, if required.

The most important global variables are (in alphabetical order):

Note: When using name spaces, there might be problems using the variable “src_data”. The following expression can be used as an alternative:
"rh_<?job@InputChannel-DN@RoleName/>"

Note: When using name spaces, there might be problems using the variable “tgt_data”. The following expression can be used as an alternative:
"rh_<?job@OutputChannel-DN[Anchor=DATA]@RoleName/>"

The profile script profile.tcl also defines some global variables. These variables are created in the procedures listed in common.tcl while executing the synchronization logic.

The meta controller itself can also generate errors. For information about these errors, refer to the DirX Identity Meta Controller Reference.

Note: Users can exit in the user hooks directly. But before terminating the meta controller, at least meta terminate should be called in order to get a consistent trace file output.

The handles are available after initChannel for the target channel has been called and therefore can be used in the following user hooks:
uh::LoopExtraFilter
uh::LoopExtraFunction
uh::LoopPerformJoin
uh::LoopPostJoin
uh::GenerateTombstoneDN

The handles are available after initChannel for the target channel has been called and therefore can be used in the following user hooks:
uh::LoopExtraFilter
uh::LoopExtraFunction
uh::LoopPerformJoin
uh::LoopPostJoin
uh::GenerateTombstoneDN

In order to perform date-oriented delta handling, each entry in the configuration database must contain a creation and/or a modification date. If another attribute is used for date oriented delta handling all entries must have this attribute set (see the Delta Time Attribute setting for jobs in the Connectivity Administration Guide → Context Sensitive Help → Jobs → Operation → Delta Handling).

You can then extract and process all entries where the delta time attribute has changed since the last delta date, which must be kept in the configuration database under the corresponding job entry.

Note that this type of delta handling cannot detect explicitly deleted entries because they are no longer contained in the directory. Deletions can only be properly handled if they are marked with a specific value (but not deleted) or if they have been moved to a tombstone area.

For password synchronization a special algorithm is used that compensates time differences between client and server machines. The mechanism consists of a client side and workflow side part.

If the client writes a password to a user entry it sets the dxmPwdLastChange attribute to the local time plus a previously calculated offset representing the time difference of the local machine to the machine where the directory server resides (dxmPwdLastChange = localtime + offset).

It then reads the entry and checks whether the absolute difference between the dxmPwdLastChange attribute and the modification timestamp is below a defined limit (see for example the Delta Time attribute of the event manager in the Connectivity Administration Guide → Context Sensitive Help → Jobs → Tcl-based Event Manager - Operation). If the comparison fails the dxmPwdLastChange value is set to the value of the modifyTimestamp and the offset value is adapted. Note that the modification timestamp might be slightly higher than the value of the dxmPwdLastChange attribute because the second write operation differs from the first one.

The client must calculate the offset after startup during handling of the first entry. It writes the password to the first entry and reads the modifyTimeStamp. It compares it with the local time and stores the difference in offset (offset=modifyTS - localtime). For this entry it writes the dxmPwdLastChange attribute with the modifyTimeStamp value.

This algorithm guarantees that the dxmPwdLastChange attribute of the entries differs only within the defined limit even if the client and server machines run with different clock settings. Note that these calculations must be done in GMT time to work properly.

Even if the dxmPwdLastChange is adjusted by the client side algorithm, the standard script provides a mechanism that allows compensating the remaining difference. You can activate this mechanism with the Password Synchronization flag of a meta controller job. Additionally you must set the Delta Time Attribute to "dxmPwdLastChange" and define the compensation time (Password Delta Time). (For details see Connectivity Administration Guide → Context Sensitive Help → Jobs → Operation → Delta Handling.) You should set the Password Delta Time to a value slightly higher than the highest limit of all clients. A good value to start is to set the Delta Time of the clients to 2 seconds and the Password Delta Time to 3 or more seconds.

The workflows retrieve password changes from the directory by using the dxmPwdLastChange attribute as delta time attribute for the DirX Identity delta mechanism. Due to the fact that the dxmPwdLastChange attribute is only exact within some limit (the reason is that the modifyTimestamp attribute is only delivered in seconds) a comparison between the list of retrieved directory entries and a stored delta file in the work area of the password synchronization workflow can be used to identify the real difference. The delta file contains at the beginning the delta_input information and then a set of password changes of the last run. The UID can be any unique attribute that is used for join purposes in the target systems (for example employeeNumber).

The fact that the delta workflow can fail due to various reasons complicates this issue (this results in no update of the delta information in the configuration database). Thus the workflow must keep two delta files in his work area. The file names are fixed: _delta_primary.csv and _delta_secondary.csv

Based on this concept we must distinguish two possible use cases:

Use Case 1: Full transfer - The workflow retrieves all entries from the directory. The delta files must be ignored.

Full password workflow synchronizations can result in many warnings that should be ignored.

Case 2: Delta transfer - The workflow retrieves delta entries from the directory.

The workflow reads all entries based on the delta specification from the directory. In parallel it checks the delta files:

Comparison means that each entry from the source is compared with the delta list via the UID. If a UID is found in this list, the passwords (both encrypted) are compared. If they are equal, this entry was obviously already delivered and is dropped therefore. All other entries are delivered to the target system.

This mechanism guarantees that passwords are not delivered twice to the target system if the workflow runs in delta mode. Thus a warning for an entry must have another reason that the administrator should be sure to check.

If the client writes a password to a user entry it sets the dxmPwdLastChange attribute to the local time plus a previously calculated offset representing the time difference of the local machine to the machine where the directory server resides (dxmPwdLastChange = localtime + offset).

It then reads the entry and checks whether the absolute difference between the dxmPwdLastChange attribute and the modification timestamp is below a defined limit (see for example the Delta Time attribute of the event manager). If the comparison fails the dxmPwdLastChange value is set to the value of the modifyTimestamp and the offset value is adapted. Note that the modification timestamp might be slightly higher than the value of the dxmPwdLastChange attribute because the second write operation differs from the first one.

The client must calculate the offset after startup during handling of the first entry. It writes the password to the first entry and reads the modifyTimeStamp. It compares it with the local time and stores the difference in offset (offset=modifyTS - localtime). For this entry it writes the dxmPwdLastChange attribute with the modifyTimeStamp value.

This algorithm guarantees that the dxmPwdLastChange attribute of the entries differs only within the defined limit even if the client and server machines run with different clock settings. Note that these calculations must be done in GMT time to work properly.

Even if the dxmPwdLastChange is adjusted by the client side algorithm, the standard script provides a mechanism that allows compensating the remaining difference. You can activate this mechanism with the Password Synchronization flag of a meta controller job. Additionally you must set the Delta Time Attribute to "dxmPwdLastChange" and define the compensation time (Password Delta Time). You should set the Password Delta Time to a value slightly higher than the highest limit of all clients. A good value to start is to set the Delta Time of the clients to 2 seconds and the Password Delta Time to 3 or more seconds.

The workflows retrieve password changes from the directory by using the dxmPwdLastChange attribute as delta time attribute for the DirX Identity delta mechanism. Due to the fact that the dxmPwdLastChange attribute is only exact within some limit (the reason is that the modifyTimestamp attribute is only delivered in seconds) a comparison between the list of retrieved directory entries and a stored delta file in the work area of the password synchronization workflow can be used to identify the real difference. The delta file contains at the beginning the delta_input information and then a set of password changes of the last run. The UID can be any unique attribute that is used for join purposes in the target systems (for example employeeNumber).

The fact that the delta workflow can fail due to various reasons complicates this issue (this results in no update of the delta information in the configuration database). Thus the workflow must keep two delta files in his work area. The file names are fixed: _delta_primary.csv and _delta_secondary.csv

Based on this concept we must distinguish two possible use cases:

Use Case 1: Full transfer - The workflow retrieves all entries from the directory. The delta files must be ignored.

Full password workflow synchronizations can result in many warnings that should be ignored.

Case 2: Delta transfer - The workflow retrieves delta entries from the directory.

The workflow reads all entries based on the delta specification from the directory. In parallel it checks the delta files:

Comparison means that each entry from the source is compared with the delta list via the UID. If a UID is found in this list, the passwords (both encrypted) are compared. If they are equal, this entry was obviously already delivered and is dropped therefore. All other entries are delivered to the target system.

This mechanism guarantees that passwords are not delivered twice to the target system if the workflow runs in delta mode. Thus a warning for an entry must have another reason that the administrator should be sure to check.

In order to perform USN-oriented delta handling, each change in the connected directory must be written into a special tree (the "changelog" tree). A unique serial number (USN) identifies each entry in this tree. The content of this entry is the type of change and a reference to the entry that was changed.

You can extract this "changelog" information from the connected directory, analyze the contained information and process the corresponding entries.

This type of delta handling mechanism can handle deletions correctly.

Note: Some implementations only keep the DN of the deleted entry. If you need other information like a global unique identifier for removal of this entry in your target system, you must store the DN in your target system!

In order to perform file-oriented delta handling, an external delta database must exist against which the current state of the directory can be compared (this means that the directory does not support any delta mechanism). The external delta database is usually a file with partial content (hashed entries are also possible).

The agent for the directory must create and maintain these files and handle the compare operation. All types of changes (also deletions) can be processed correctly.

This type of delta-handling mechanism is very time-consuming, especially for large amounts of data.

Normally the value of the field selected is RECENT, but you can select another value for the next run, either FULL or a date which characterizes older delta run results (refer to the previous figure, which shows an example of type FILE).

When the C++-based Server starts the corresponding activity during the next run, it delivers the content of the relevant Info Item field to the agent controller based on the value of the Selected field.

The agent controller performs the delta operation. If it completes successfully, the agent controller returns as a result the current time value with the specific delta information (the USN, date or file name).

DirX Identity stores this information in the Info Items list with the next available item number when it was not a temporary run and resets the Selected field to RECENT.

Note: If a workflow contains jobs that work in delta mode, DirX Identity guarantees that the delta information is only updated when the complete workflow runs successfully (does not return closed.completed.error). Thus the next run of the workflow will start the same delta operation as the previous one (the one that failed). This operation ensures that no data is lost.

Warning: Do not use the Ignore Errors flag of the Activity object for jobs that use delta handling. This could result in serious data loss! (For details on the Ignore Errors flag see the Connectivity Administration Guide → Context Sensitive Help → Tcl-based Workflows → Tcl-based Activity.)

When you define a new job, you must set up DeltaType in the configuration database. Set the field Delta Type in the Delta Handling tab of the job object or use a wizard in the DirX Identity Manager Global View. The Info Items field is automatically initialized to:

USN full Example: 1;FULL=1
DATE full Example: 1;FULL=19800101000000Z
FILE full Example: 1;FULL=

Please note that if you change the DeltaType field at any time later on, DirX Identity Manager will reset the existing Info ltems list to the FULL-entry. The Selected field is set to Recent.

Hint: DirX Identity agents are designed to work with the agent controller to support delta handling in the correct way, but any other agent can also use the delta handling feature of DirX Identity:

The new delta information, which should be stored into the Connectivity configuration, must be written into the first line of the file deltaoutputdata.txt (location must be the work path).