Chapter 15. Integrating Business Processes and Workflows

The embedded workflow and business process engine is provided as part of the standard OpenIDM build.

Install the OpenIDM build, as described in the Installation Guide. Start OpenIDM, and run the scr list command at the console to check that the workflow bundle is active.

-> scr list
...
[  14] [active       ] org.forgerock.openidm.workflow
...

To verify the workflow integration you need at least one workflow definition in the /path/to/openidm/workflow directory. A sample workflow (example.bpmn20.xml) is provided in the /path/to/openidm/samples/misc directory. Copy this workflow to the /path/to/openidm/workflow directory to test the workflow integration.

$ cd /path/to/openidm
$ cp samples/misc/example.bpmn20.xml workflow/

You can verify the workflow integration by using the REST API. The following REST call lists the defined workflows:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/workflow/processdefinition?_queryId=query-all-ids"
  

The sample workflow definition that you copied in the previous step is named osgiProcess. The result of the preceding REST call is therefore something like:

{"result":[
     {"_id":"osgiProcess:1:3",
      "name":"Osgi process"
     }
        ]
}
  

The osgiProcess definition calls OpenIDM, queries the available workflow definitions from Activiti, then prints the list of workflow definitions to the OpenIDM logs. Invoke the osgiProcess workflow with the following REST call to OpenIDM:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST
 "http://localhost:8080/openidm/workflow/processinstance?_action=createProcessInstance"
 --data '{"_key":"osgiProcess"}'
  

The workflow prints the list of workflow definitions to the OpenIDM console. With the default sample, you should see something like this on the console:

script task using resolver: [
  result:[
    [_id:osgiProcess:1:3, name:Osgi process]
  ]
]
script task using expression resolver: [
  result:[
    [_id:osgiProcess:1:3, name:Osgi process]
  ]
]
  

You can set up integration with a remote Activiti engine, as described in the following steps.

Whether you use the embedded Activiti engine, or a remote Activiti engine, you configure the OpenIDM Activiti module in a file named /path/to/openidm/conf/workflow.json. If this file is absent from the configuration, the workflow module is unavailable for use. In the default OpenIDM installation, the workflow.json file assumes an embedded Activiti engine, and has the following configuration:

{
   "enabled"  : "true"
}
  

You can disable the workflow module by setting the "enabled" property in this file to "false".

A sample workflow.json file, with all configurable properties, is provided in /path/to/openidm/samples/misc. To configure an Activiti engine beyond the default configuration that is provided, edit this file as required and copy it to the /path/to/openidm/conf directory.

The sample workflow.json file contains the following configuration:

  {
    "enabled"  : "true",
    "location" : "remote",
    "engine" : {
        "url" : "http://localhost:9090/openidm-workflow-remote-",
        "username" : "youractivitiuser",
        "password" : "youractivitipassword"
    },
    "mail" : {
        "host" : "yourserver.smtp.com",
        "port" : 587,
        "username" : "yourusername",
        "password" : "yourpassword",
        "starttls" : true
    },
    "history" : "audit"
}
  

"history" : "audit"

The following section outlines the process to follow when you create an Activiti workflow for OpenIDM. Before you start creating workflows, you must configure the Activiti engine, as described in Configuring the Activiti Engine.

You can invoke workflows and business processes from any trigger point within OpenIDM, including reacting to situations discovered during reconciliation. Workflows can be invoked from script files, using the openidm.action() function, or directly from the REST interface.

The following sample script extract shows how to invoke a workflow from a script file:

/*
 * Calling 'myWorkflow' workflow
 */

var params = {
 "foo" : "bar",
 "_key": "myWorkflow"
};

openidm.action('workflow/processinstance', {"_action" : "createProcessInstance"}, params);

You can invoke the same workflow from the REST interface by sending the following REST call to OpenIDM:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST
 "http://localhost:8080/openidm/workflow/processinstance?_action=createProcessInstance"
 --data '{"_key":"myWorkflow", "foo":"bar"}'
  

There are two ways in which you can specify the workflow definition that is used when a new workflow instance is started.

You can use the optional _businessKey parameter to add specific business logic information to the workflow when it is invoked. For example, the following workflow invocation assigns the workflow a business key of "newOrder". This business key can later be used to query "newOrder" processes.

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST
 "http://localhost:8080/openidm/workflow/processinstance?_action=createProcessInstance"
 --data '{"_key":"myWorkflow", "_businessKey":"newOrder"}'
  

The Activiti implementation supports filtered queries that enable you to query the running process instances and tasks, based on specific query parameters. For example, the following query returns all process instances with the business key "newOrder", as invoked in the previous section.

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST
 "http://localhost:8080/openidm/workflow/processinstance?_queryId=filtered-query
 &businessKey=newOrder"
  

You can query process instances based on the value of any process instance variable by prefixing the variable name with _var-. For example:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST
 "http://localhost:8080/openidm/workflow/processinstance?_queryId=filtered-query
 &_var-processvariablename=processvariablevalue"
  

The standard Activiti properties can be queried using the Activiti notation, for example, processDefinitionId=managedUserApproval:1:6405. The query syntax applies to all queries with _queryId=filtered-query.

This example uses the Activiti Eclipse BPMN 2.0 Designer to set up an email notification business process. The example relies on an SMTP server listening on localhost, port 25.

Once you have defined the workflow, drag and drop components to create the workflow. This simple example uses only a StartEvent, MailTask, and EndEvent.

[D]

After creating the workflow, adjust the generated XML source code to use the variables inside the <serviceTask> tag shown in the following listing.

<?xml version="1.0" encoding="UTF-8"?>
<definitions
 xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:activiti="http://activiti.org/bpmn"
 xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
 xmlns:omgdc="http://www.omg.org/spec/DD/20100524/DC"
 xmlns:omgdi="http://www.omg.org/spec/DD/20100524/DI"
 typeLanguage="http://www.w3.org/2001/XMLSchema"
 expressionLanguage="http://www.w3.org/1999/XPath"
 targetNamespace="http://www.activiti.org/test">
 <process id="EmailNotification" name="emailNotification">
   <documentation>Simple Email Notification Task</documentation>
   <startEvent id="startevent1" name="Start"></startEvent>
   <sequenceFlow id="flow1" name="" sourceRef="startevent1"
     targetRef="mailtask1"></sequenceFlow>
   <endEvent id="endevent1" name="End"></endEvent>
   <sequenceFlow id="flow2" name="" sourceRef="mailtask1"
     targetRef="endevent1"></sequenceFlow>
   <serviceTask id="mailtask1" name="Email Notification"
     activiti:type="mail">
     <extensionElements>
       <activiti:field name="to" expression="${toEmail}"
       ></activiti:field>
       <activiti:field name="from" expression="${fromSender}"
       ></activiti:field>
       <activiti:field name="subject" expression="Simple Email Notification"
       ></activiti:field>
       <activiti:field name="text">
         <activiti:expression><![CDATA[Here is a simple Email Notification
         from ${fromSender}.]]></activiti:expression>
       </activiti:field>
     </extensionElements>
   </serviceTask>
 </process>
 <bpmndi:BPMNDiagram id="BPMNDiagram_EmailNotification">
   <bpmndi:BPMNPlane bpmnElement="EmailNotification"
     id="BPMNPlane_EmailNotification">
     <bpmndi:BPMNShape bpmnElement="startevent1" id="BPMNShape_startevent1">
       <omgdc:Bounds height="35" width="35" x="170" y="250"></omgdc:Bounds>
     </bpmndi:BPMNShape>
     <bpmndi:BPMNShape bpmnElement="endevent1" id="BPMNShape_endevent1">
       <omgdc:Bounds height="35" width="35" x="410" y="250"></omgdc:Bounds>
     </bpmndi:BPMNShape>
     <bpmndi:BPMNShape bpmnElement="mailtask1" id="BPMNShape_mailtask1">
       <omgdc:Bounds height="55" width="105" x="250" y="240"></omgdc:Bounds>
     </bpmndi:BPMNShape>
     <bpmndi:BPMNEdge bpmnElement="flow1" id="BPMNEdge_flow1">
       <omgdi:waypoint x="205" y="267"></omgdi:waypoint>
       <omgdi:waypoint x="250" y="267"></omgdi:waypoint>
     </bpmndi:BPMNEdge>
     <bpmndi:BPMNEdge bpmnElement="flow2" id="BPMNEdge_flow2">
       <omgdi:waypoint x="355" y="267"></omgdi:waypoint>
       <omgdi:waypoint x="410" y="267"></omgdi:waypoint>
     </bpmndi:BPMNEdge>
   </bpmndi:BPMNPlane>
 </bpmndi:BPMNDiagram>
</definitions>

In Eclipse, select the project, then right click and select Create deployment artifacts to generate the components and package them in a .bar file for deployment in the openidm/workflow directory.

After you deploy the .bar, create a script named openidm/script/triggerEmailNotification.js. The script invokes the workflow.

/*
 * Calling 'EmailNotification' workflow
 */

var params = {
 "_key" : "EmailNotification",
 "fromSender" : "noreply@openidm",
 "toEmail" : "jdoe@example.com"
};

openidm.action('workflow/processinstance', {"_action" : "createProcessInstance"}, params);

You can also invoke the workflow over the REST interface with the following REST command:

$ curl
 --header "X-OpenIDM-Username: openidm-admin" 
 --header "X-OpenIDM-Password: openidm-admin"
 --data '{"_key":"EmailNotification", "fromSender":"noreply@openidm", "toEmail":"jdoe@example.com"}'
 --request POST 
 "http://localhost:8080/openidm/workflow/processinstance?_action=createProcessInstance"
   

To schedule the workflow to be invoked regularly, create a schedule configuration object named openidm/conf/schedule-EmailNotification.json. The following schedule invokes the workflow once per minute.

{
   "enabled" : true,
   "type" : "cron",
   "schedule" : "0 0/1 * * * ?",
   "invokeService" : "script",
   "invokeContext" : {
       "script" : {
           "type" : "text/javascript",
           "file" : "script/triggerEmailNotification.js"
       },
   }
}

This example, provided in openidm/samples/workflow, uses workflows to provision user accounts. The example demonstrates the use of the browser-based user interface to manage workflows.