Extending Event-based Processing Workflows

This chapter describes how to implement and manage user hooks for event-based processing workflows.

Prerequisites

We assume that you are familiar with Java and with building Java projects and that Ant and a Java compiler are installed and in your path.

Documentation

To understand this issue, we recommend reading the following chapters.

DirX Identity Application Development Guide

Understanding the Default Application Workflow Technology > Understanding Java-based Workflows

Read the entire chapter, especially these sections:

Java-based Workflow Architecture - provides all information for understanding real-time provisioning workflow features and architecture.

Customizing Event-based Maintenance Workflows - explains in detail how to customize event-based maintenance workflows. Here you can find three sections:

Implementing a User Hook for an Event Maintenance Workflow - explains how to create a user hook. The section Configuring a User Hook for an Event-based Maintenance Workflow describes how to configure an implemented user hook.

Using Event Contexts - explains some useful helper methods when working with event-based workflow user hooks.

Deploying a User Hook - describes how to deploy an implemented and configured user hook.

Java Documentation

For the Java documentation of the API, see the folder

Documentation/DirXIdentity/ /EventMaintenanceWorkflows

on the product DVD.

Training

View the webinar that explains this topic:

Event-based Workflows

Note: you can download webinars from our support portal. If you do not have access to the support portal, contact your responsible support organization.

Examples

For a sample implementation, see the folder "Additions/EventMaintenanceWorkflows" on the installation media.

Hints, Tips and Tricks

To write a user hook, we recommend that you follow the same approach as for writing mapping classes and mapping user hooks: first test and debug in your local Eclipse environment, and then run the workflow in IdS-J.

You can run the activity for an event-based maintenance workflow as a framework job. Then the event maintenance controller together with your user hook runs in the Eclipse environment and you can easily debug it.

For running such a job as a unit test in Eclipse, see the hints in the chapter on mapping classes.

Job Configuration

The configuration file should have the following structure:

<job>
    <controller name="EventController"
        className="com.siemens.idm.jobs.ebr.AccountEventController">
        <logging level="5" filename="src.test/confs/ebr/trace.txt">
        </logging>
        <property name="server" value="localhost"/>
		…
	 </controller>
    <connector role="reader"  name="EventFileReader"
	 …
	 </connector>
</job>

The root element <job> contains two child elements:

<controller> configures the event maintenance controller for users, accounts, and so on.

<connector> configures the component, which reads an input event for a file.

You can copy most of the <controller> element from the LDAP activity entry of the appropriate workflow. In Identity Manager, navigate to the event maintenance workflow of the appropriate object type; for example, for accounts. Beneath the workflow, select the join activity and then open the tab with the resolved content. Here you find the XML document that represents the activity configuration. Copy the part with the <job> element to your configuration file. Enter the <logging> element with the log level and the name of the log file.

Use the following XML snippet for the reader configuration in your file:

    <connector role="reader"  name="EventFileReader"         className="siemens.dxm.connector.framework.event.SpmlEventFileReader">
        <connection type="SPML"
            filename="src.test/confs/ebr/request.xml">
            <property name="runInParseMode" value="true" />
            <property name="validate" value="false" />
        </connection>
    </connector>

Adapt the location of the file that contains the input events.

Input Events

The file with the input events has the following structure:

<events>
<addEvent name="dxm.event.SvcTSAccount.cluster='localhost'.resource='cn=My-Company'"
…
</addEvent>

<modifyEvent name="dxm.event.SvcTSAccount.cluster='localhost'.resource='cn=My-Company'"
…
</modifyEvent>
…
</events>

The root element <events> contains one or more event children. They are either <addEvent>, <modifyEvent> or <deleteEvent>.

Each event is the extension of the respective SPMLv1 request and contains the same child elements as the SPML request.

Each event contains the SPML <identifier> and a <source> element and optionally SPML <operationalAttributes>. In addition, the <addEvent> contains SPML <attributes>, while the <modifyEvent> contains SPML <modifications>.

The name attribute of the event reflects the topic of the message. It is not important for this test configuration. The IdS-J server evaluates it to find the appropriate workflow.

Typically the workflow will not evaluate the <source> element, but the user hook may do so if it is of interest which component has produced the event. Here is a sample snippet:

	<source application="joinEngine"
		resource="cn=My-Company"
		cluster="localhost"
	/>

The application attribute contains the name of the sending component. The term joinEngine is used for the provisioning workflows and indicates here that the event was produced because the validation or synchronization workflow changed the LDAP entry.

The most important part will be the <attributes> of an <addEvent> and the <modifications> of a <modifyEvent>. They contain the list of attributes that were changed. The actions of the event controller and the user hook will most likely depend on them.

Here is a snippet of <attributes>:

<spml:attributes>
   <spml:attr name="objectclass">
		<dsml:value>dxrTargetSystemAccount</dsml:value>
		<dsml:value>top</dsml:value>
   </spml:attr>
   <spml:attr name="description">
         <dsml:value>test account created new</dsml:value>
   </spml:attr>
</spml:attributes>

And here is one for <modifications>:

<spml:modifications>
   <spml:modification name="dxrTSState" operation="replace">
           <dsml:value>ENABLED</dsml:value>
   </spml:modification>
</spml:modifications>

A <deleteEvent> does not contain any specific child elements; that is, no <attributes> or <modifications>. It contains the <identifier> with the DN of the deleted entry. Here is a sample snippet:

<spml:identifier type="urn:oasis:names:tc:SPML:1:0#DN">
   <spml:id>cn=Jane Webinar3,cn=accounts,cn=New-LDAP2,cn=Cluster1,cn=DemoCluster,cn=TargetSystems,cn=My-Company</spml:id>
</spml:identifier>