Creating Java-based Provisioning Workflows

This use case explains how to build the necessary Java-based provisioning workflows for a custom target system type or one of its instances. This is the most complex part of this use case document that requires a sound knowledge base about DirX Identity.

About this Use Case

If a target system template has a reference to a connected directory in the connectivity configuration, the target system wizard copies the necessary connectivity objects (mainly the connected directory and the associated workflows) as specified.

Correct set up of a custom target system template together with all workflows allows connecting a new connected system instance within minutes. Nevertheless this setup must be done thoroughly.

Note that you can use manual provisioning as an alternative solution if you do not or not yet need direct connectivity. In this case use the built-in Service Management target system type as starting point for your custom target system type.

Documentation Hints

You can find additional information related to this use case in the following documents:

Connectivity Administration Guide

  • Managing DirX Identity Connectivity → Managing Connected Directories – describes overall how to manage connected directories in the connectivity configuration.

  • Managing DirX Identity Connectivity → Managing Provisioning Workflows – describes overall how to manage provisioning workflows in the connectivity configuration.

  • Managing DirX Identity Connectivity → About Java-based Configuration Objects

    – describes roughly the Java-based workflows configuration.

  • Managing Connected Directories – describes how to manage connected directories in the connectivity configuration.

  • Managing Provisioning Workflows → Managing Java-based Provisioning Workflows – describes how to configure and copy existing Java-based workflow objects.

Connectivity Reference

Identity Connectors – describes the functionality and configuration of the connectors which are used in the Java-based provisioning workflows.

Application Development Guide

  • Understanding the Default Application Workflow Technology → Understanding Java-based Workflows – provides overall information about configuration and functionality of Java-based provisioning workflows.

  • Using the Default Connectivity Applications – explains the rules when working with the default configuration objects.

  • Using the Target System (Provisioning) Workflows → Understanding the Java-based Target System Workflows – describes functionality and implementation of delivered standard Java-based provisioning workflows. This is the most important documentation part for this use case.

User Interfaces Guide

Using DirX Identity Manager → Using the Connectivity Views → Using the Expert View – contains general information about usage of connectivity expert view which is necessary for this use case.

Use Case Description: Java Programming in DirX Identity

  • Provisioning Workflow Extensions – describes how to implement custom mappings, user hook and filters used by Java-based provisioning workflows.

  • Implementing a Custom Connector – explains how to implement a new connector that may be used in new Java-based provisioning workflows.

Integration Framework

  • Connector Integration Framework → Java Connector Integration Framework – contains detailed information about Java framework that must be typically used when implementing own Java components for Java-based provisioning workflow.

Specific Hints and Guidelines

Creation of a completely new connectivity workflow requires experience with Java-based provisioning workflows:

  • Try to identify the Java-based workflow that fits best as template for the new connectivity workflow you want to create.

  • Consider all necessary aspects of the new connectivity workflow. Most important is that you have a connector ready that implements access to the connected system via the provided API.

  • Be sure that you do not create objects with display names that exist already. Use display names that cannot collide with existing ones especially when working in the connectivity Expert View within the Connectivity Configuration Data/Configuration.

  • This guide expects the existence of a customer specific instance of the Identity Store within Connected Directories/scenario_name/Provisioning/Identity Store. Create it by using the new target system wizard if not yet existing. Do not place any new objects in a directory that contains settings for default objects (contains Default in the path) unless this is mentioned explicitly.

Setup and Configuration

For configuration of Java-based provisioning workflows follow these steps:

  • Create a custom scenario for your custom target system templates

  • Create a new connected directory

  • Create the required Java-based provisioning workflows

  • Refine the copied objects

  • Test the new Java-based provisioning workflows

    Note that there is an alternative way to create Java-based workflows. You can build all objects from scratch in the Expert view but this requires much more expert knowledge and we do not recommend this method.

Creating a Custom Scenario

We recommend creating a scenario with a fixed name to be able to recognize objects that belong to custom target system templates.

This step is only necessary if the CustomTemplates → Provisioning scenario does not exist, that means you have to perform it when you create the first custom target system template in your domain.

In this case perform these steps:

  • Login into the Connectivity configuration.

  • Select the Global view.

  • Select the Scenarios node and choose New → Folder from the context menu.

  • Enter CustomTemplates as name, set a description and click OK.

  • Select the CustomTemplates node and choose New → Scenario from the context menu.

  • Enter Provisioning as name, fill the other attributes and click OK.

A new and empty scenario exists. Additionally we need an Identity Store.

  • Click into the blue empty area and select New Connected Directory from the context menu. A connected directory icon with the name '(new') is created.

  • Right click the icon and perform Configure from the context menu.

  • In the wizard’s Choose a Template step select the Identity Store (from the folder Default/Identity Store).

  • Step through the wizard steps but do not change anything. At the end click Finish to complete the wizard.

The icon is renamed to Identity Store and contains all the information of the original instance. For correct operation, you should link the Identity Store to your already created scenario.

  • In the scenario tree of the Global view click the Provisioning scenario and select Properties from the context menu.

  • Click Edit and set the link in the Identity Store field to your newly created Identity Store (Connected Directories → CustomTemplates → Provisioning → Identity Store → Identity Store). Click OK.

This step is necessary that the target system wizard can recognize the Identity Store later on.

Creating a New Connected Directory

For each custom target system type we need a connected directory that represents the system to provision in the connectivity configuration.

Use an existing connected directory template that is similar to your new connected directory. Add this template to your scenario:

  • Click into the blue empty area and select New Connected Directory from the context menu. A connected directory icon with the name '(new') is created.

  • Right click the icon and perform Configure from the context menu.

  • In the wizard’s Choose a Template step select the template that you want to use as a starting point. Click Next.

  • In the Supply General Information step set the name equal to the name of your already existing custom target system template. Set the other parameters in this step as required.
    Note: here you could also define a new connected directory type if you already created it. If not, you can perform this task later on or you can stay with the current type. Click Next.

  • Fill the relevant parameters in the Set Provisioning Parameters step. Click Next.

  • In the Set Bind Profiles step you can define or redefine bind profiles. Click Next.

  • The next steps are dependent on your selected template. Typically you have to adapt the attribute configuration file according to the real attributes of the new connected directory. Fill all information according to the documentation or online help. At the end of the wizard click Finish.

The new connected directory exists. You can find it in the Expert view in the folder:

Connected Directories → CustomTemplates → Provisioning → Target Scheduled

You can perform additional changes here in the Expert view or you can re-run the wizard in the Global view.

Now we have to link this new connected directory to our already created custom target system template:

  • Click the Provisioning view group and select Domain Configuration.

  • Navigate to the custom target system template in Customer Extensions → Target Systems.

  • Click it and perform Edit.

  • In the Relationships area of the General tab set the link in the Connected Directory field to your newly created connected directory.

This step is necessary that you can later on configure and run provisioning workflows from the Provisioning configuration side.

Creating the New Java-based Provisioning Workflows

The next task is to copy the necessary workflows. First you should create a workflow line between the newly created connected directory and the Identity Store:

  • Click into the blue empty area and select New Workflow Line from the context menu. Click both connected directory icons to create the line.

For each workflow you want to create perform these steps:

  • Select the workflow line and perform New from the context menu. The workflow wizard opens and shows all workflows that fit between these two endpoints. Select the correct template and then click Next.
    Note: if you cannot find the required template, deselect the Matching Endpoints flag. Now you can see all workflows in your connectivity configuration regardless whether they fit the two endpoints or not. Be aware that you have to adapt such a copied template afterwards before it can work correctly.

  • In the General Workflow Parameters step set the correct name for your new workflow and adapt all the other parameters as described in the online help.

  • Step through the other tabs and set all parameters as required. At the end click Finish.

Each workflow is normally copied to the folder

Workflows → CustomTemplates → Provisioning → Target Realtime → type

You can perform additional changes here in the Expert view or you can re-run the workflow wizard in the Global view.

Refining the Objects

The copied connected directory as well as the copied workflows should be adapted further to reflect all requirements.

Refining the Connected Directory

You can redefine almost anything. Consider the following issues:

New Connected Directory Type?

DirX Identity comes with a lot of pre-defined connected directory types (verify this in the Expert view under Configuration → Connected Directory Types). A connected directory type can be used by many connected directory definitions (for example the connected directory type LDAP).

If you need a new one, create it under Configuration → Connected Directory Types. Use an existing connected directory type object, copy it and rename it. Next you can redefine its objects descriptions and wizards in the corresponding subfolders of the connected directory type.

Having the connected directory type created, update the references for Wizard and Directory Type at the new connected directory object which was previously created.

Tab Layout and the Displayed Attributes?

If you want to use other layout for the new connected directory, edit the object description for the related connected directory type. Alternatively you can use the Design Mode for simple adaptations of the layout. For more information see the documentation.

Attribute Configuration?

The attribute configuration of the connected directory reflects the schema of the system to connect. If you have an LDAP type connected directory, you can reload the schema to adapt the attribute configuration. Otherwise you have to enter and maintain all attributes by hand.

Note that the attribute configuration is only necessary for Tcl-based workflows.

Refining the Workflow(s)

The workflow wizard copied all workflow objects correctly and set the corresponding links (for example the links from the ports to the channels). Nevertheless you can adapt everything as required. Consider these issues:

Workflow → General?

Adapt the Is applicable for, the Timeout and the Wizard Parameters sections. See the online help for more information.

Join → General?

Adapt the Error Handling section. See the online help for more information.

Consider also the creation of a new resource family for running the activities of this new Java-based workflow. You can create a new one under Configuration → Resource Families. Create the folder CustomTemplates and then copy an existing resource family, rename it and set it for the activities of the new workflow object (typically error and join activity).

Always check that the configured resource families are deployed for a running Java-based server otherwise the activity cannot run.

Join → Controller?

You can also consider a change of the used controller. See the documentation for further information.

If you intend to use global user hooks for the new workflow, enter the appropriate class name of the implementing class to Controller tab of the join activity.

TS Port → Target System?

If you created a new connector, you have to set the Connector field correctly. You can define new connector definitions under Configuration → Connector Types. As a template use an existing one, copy it and define a component description for it (under the Component Descriptions subfolder). Set the correct class name for the class that implements the connectivity to the new connected directory.

Refining the Channels

The workflow wizard copied already all necessary channels from the selected workflow template on both sides (connected directory and Identity Store). All links were correctly adapted.

Adapt the Channel Structure

Typically four types of the channels should be present for a new connected directory:

  • Channel for account object validation and synchronization

  • Channel for group object validation and synchronization

  • Channel for membership validation and synchronization

  • Channel used for password synchronization (needed only by password sync workflows)

Each channel synchronizes one type of target system specific object if possible. These channels exist typically in pairs. One channel exists at the connected directory definition side. The other corresponding channel exists at the Identity Store side. The password channel exists only at the connected directory side. You can use more channels, if there are more types of objects to be synchronized.

If you need additional channels, copy or create them and configure them accordingly. You have so set up the channels below the connected directory → Channel folder as well as under the Identity Store → Channels folder. Be sure to set up the corresponding and correct folder structure. Link the channel pairs correctly.

If you intend to use password synchronization, set also correctly the Password Primary Channel for the password channel (typically the account channel). Set the Member Channel for the correct channel (the channel that handles objects that store the group membership).

Refining Mappings, Post Mappings and Channel User Hooks

Setup the mappings for the Java-based workflow channels as required. You can also define post mappings and specify the class name of the Java class implementing the channel user hook. Use Java class mapping instead of Java source wherever possible. It allows you to debug Java mappings in a Java IDE. Define a new package name used for Java mappings which must be also defined at the channel object. Use the common naming conventions.

Testing the Workflows

We recommend performing the tests in two steps:

Check Correctness

Check the correctness of the new workflow. Enable Design mode to see the Content resolved tab at the Java-based provisioning workflow object.

View the content of this tab and try to find the characters ### in the displayed XML content. This would mean that some references are incorrectly resolved. That does not always mean that an error occurred, but we recommend evaluating these inconsistencies and fix them if possible.

Live Testing

Now you are ready to perform a live test.

Create a new target system instance that is based on your custom target system template and that comes with the corresponding workflows. Test the workflow using the DirX Identity manager and the Java-based server.

You can debug the global and channel user hooks, the Java class mappings and the post mappings using a Java IDE. This requires the corresponding Java server running in the debug mode. This mode can be enabled by starting the Java Server via the command line using a batch runServer.bat (or .sh). Edit it and uncomment line beginning by REM SET debug (when working with Windows version otherwise use ported settings for UNIX systems). This will enable remote debugging on the pre-configured port 48174. Any Java IDE supporting remote debugging is now able to connect to this port and debug your Java classes used in the new Java-based provisioning workflows.

See the DirX Identity Use Case Document "Java Programming" for more information.