Workflow Primer – Part 1

One of the challenges in Identity Manager is that there are so many ways that things can be accomplished, it’s not always clear what the developers intend. In fact, my understanding of how best to use this technology evolved over many years and many projects.

I wanted to write this article to help socialize some of the technology and some of what is supporting it under the hood. For example, there are many parts of the forms engine that are actually simply browser javascript commands. Understanding that can both expand what is possible as well as help avoid pitfalls such as engineering in browser dependencies.


Back in 1997 when DirXML was first being developed, it was a revolutionary mechanism for applying synchronization policies between disparate identity stores. Back then the goal was to fully automate the process of identity object creation between different systems.

While this enabled the definition of policies to fully instrument the creation, placement, management and removal of access, it quickly became clear that this solution exposed a further challenge: defining in detail and with precision what the policy should be. In a large organization, there was not necessarily a clear picture of who needs what from the business perspective.

A lot has happened over the last two decades. The concept of separating decision makers from technical implementers became paramount, the enablement of human intervention in otherwise automated processes, the rise of roles based provisioning as well as the importance of auditing and governance.

While the original metadirectory synchronization engine was the first major foundational building block, another important cornerstone was the development of the IDM Workflow engine. This component enables interactivity with the provisioning process and was also the platform upon which the roles and resources engine was later constructed.

Provisioning Request Definitions (PRDs) are the mechanism which is defined within Identity Manager to encapsulate the workflow process. Some of the use cases it is commonly used for include:

  • Self-request forms

  • Delegated manager administration

  • Enabling non-technical approvers to participate in a technical provisioning process

  • Creating customized access request forms, such as replacing a paper form with a similar web base form

  • Limited scope management tools

  • Interruption of an otherwise automated directory synchronization process with human intervention

When I first started working with the forms component of the workflow engine in Identity Manager, I found it to be a fun but frustrating endeavor. It worked well, and served important purposes, but it seemed to be an onerous task to develop all but the simplest custom workflows.

Over time, as I have grown to understand and appreciate the demands and designs of such technology, I have developed methodologies which I re-used to accelerate the delivery of workflow forms. Today I can build a fairly sophisticated form quickly, by eliminating most of the repetitive grunt work and focusing on the areas that require more customized attention. This cool solution is the documentation of that methodology.

PRD Best Practices

This document is not a comprehensive replacement for the vendor documentation, nor is it going to provide a cookbook for the universe of possibilities for using the workflow engine. The goal is to document the key aspects of a typical provisioning solution which enabled it to be delivered more reliably and rapidly than it could otherwise be implemented.

While the majority of Identity Manager is a point and click, drag and drop effort, some small parts of it need to be glued together using small bits of code. In the case of the workflow forms engine, these are ecmascript (aka Javascript).

The goal of this methodology is to leverage scripts to create re-usable code segments. Reusing code isn’t just a time saver in development, it has a significant effect on the manageability of the finished solution. Since the same code is in use in multiple places, problems can often be easier to track down. And corrections also generally have a more global effect.

Understanding Objects

While this is not intended to be a course in computer science, not all implementers of IDM are programmers. A brief understanding of what objects are is warranted to assure that all our readers can understand what they are looking at.

In simple terms, an object is a variable on steroids. It is designed to represent something more complex than just a single number or string. There are two main collections of elements in an object: Properties and Methods.

Properties are similar to variables. Like variables they have a value and a data type (string, number, flag, etc.) but one object can have many of them. They can also be read only or read-write. Methods, on the other hand, are subroutines (functions), which are may be invoked by referring to the object.

There are a number of core objects that are provided automatically for use within the forms engine. They are:

  • form

  • field

  • event

  • IDVault

These objects provide the methods necessary to implement IDM workflow solutions.

One of my early frustrations in embracing the workflow engine was that it seemed there was no easy way to re-use code. There were scripts but they could not seem to leverage the form, field or identity vault data. The first important revelation I had was that if you need to use these objects within a library script, it is necessary for you to pass a reference to the object when invoking the function from your library as a parameter. This opened up a world of possibilities.

Where does it run?

There are two main parts of the PRD, which appear outwardly similar but are drastically different in implementation and capability. The workflow itself is a back-end function running on a Rhino or Nashorn ecmascript engine. Since this is a back-end function, workflows can leverage true java objects, and therefore most of the data structures are objects such as java.util.Vector and java.util.ArrayList. It has direct access to the identity vault, the entitlement, roles and resources functionality. Running on the back-end immunizes it from browser differences.

By contrast, the forms engine is actually a development environment which creates a set of javascript and web forms that run in a browser. Any access to the identity vault is actually done via a web service call (known as “VDX”). All data is stored in javascript objects and data structures, and it may be necessary to make accommodation for running under different browsers or even browser versions.

One of the challenges in getting your arms around this environment is that these differences are obscured (but not avoided) by the way the two services are interfaced. Similar operations between the two environments need to be treated in similar, but subtly different ways.

Take this example: In both cases, we need to iterate through a list of attribute values to check to see if a user is a member of the group “admins”:


var groupDN = "cn=Admins,o=acme"
var recipient = form.getValue("recipient");

var isAdmin = false;

var groups= IDVault.get(null, recipient, "user", "group");
for (var i=0; i<groups.length; i )
if (groups[i] == groupDN)
isAdmin = true;


var groupDN = "cn=Admins,o=acme"

var isAdmin = false;

var groups= IDVault.get(recipient, "user", "group");
for (var i=0; i<groups.size(); i )
if (groups.get(i).equals(groupDN))
isAdmin = true;

Notable differences include:

  • The value “recipient” is an intrinsic value of the workflow but it is just the value of a form field name recipient in the forms engine.

  • IDVault.get() method takes one less parameter; the first “null” in the forms example is an optional field name. There is nothing corresponding in the workflow engine so it is not included.

  • IDVault.get() in the form returns an ecmascript array. In the workflow it returns a java.util.ArrayList. Therefore, the size of the array in the form is retrieved by the length property, while the size of the ArrayList in the workflow is retrieved by the size() method.

  • Similarly, an individual array element in the form is directly accessible as an indexed value (“groups[i]”) but in the workflow it must be retrieved using the get method (“groups.get(i)”)

  • Also, because the contents of the array in a form are ecmascript strings, equality is tested using the “==” operator. In the workflow, the contents of the ArrayList are java.lang.String objects where equality is tested using the .equals() method.

In the next part of this article, I will discuss the IDM Forms engine.


How To-Best Practice
Comment List
  • Hi,

    To check if the initiator user is the member of Admin group, I have used the below code :
    function compare(){
    var result = false;
    var groupDN1 = “cn=Admin,ou=Groups,o=company”;
    var initiatorDN = initiator; //Initiator DN from workflow start activity
    var groups=IDVault.get(initiatorDN ,’user’,’group’);
    for (var i=0; i<groups.length; i++)
    result = true;

    return result;
    But i am not getting the result. I am having doubt in using and calling the array.
    Could you please help me to resolve this issue?