Integrating Business Processes & WorkflowWorkflowBusiness processesKey to any identity management solution is the ability to provide
workflow driven provisioning activities, whether for self-service actions
such as request for entitlements, roles or resources, running sunrise or
sunset processes, handling approvals with escalations, or performing
maintenance.OpenIDM provides an embedded workflow and business process engine
based on Activiti and the Business Process Model and Notation (BPMN) 2.0
standard.The embedded workflow and business process engine is currently
provided as part of a separate, experimental download, the OpenIDM
Experimental Nightly build available
from the download page.You install the experimental download in the same way as standard
OpenIDM. See the Installation
Guide for instructions. After starting OpenIDM, run
the scr list command at the console, and check that the
bundle is active.-> scr list
...
[ 14] [active ] org.forgerock.openidm.workflow.activiti
...Contact ForgeRock at info@forgerock.com for details on support for the experimental
embedded workflow and business process engine.More information about Activiti and the Activiti project can be found
at http://www.activiti.org.About BPMN 2.0 & Activity ToolsBusiness Process Model and Notation 2.0 is the result of consensus
among Business Process Management (BPM) system vendors. The Object Management Group
(OMG) has developed and maintained the BPMN standard since
2004.The first version of the BPMN specification focused only on graphical
notation, and quickly became popular with the business analyst audience.
BPMN 1.x defines how constructs such as human tasks, executable scripts, and
automated decisions are visualized in a vendor-neutral, standard way. The
second version of BPMN extends that focus to include execution semantics,
and a common exchange format. Thus, BPMN 2.0 process definition models
can be exchanged not only between different graphical editors, but also
can be executed as is on any BPMN 2.0-compliant engine, such as the engine
embedded in OpenIDM.Using BMPN 2.0, you can add artifacts describing workflow and business
process behavior to OpenIDM for provisioning and other purposes. For example,
you can craft the actual artifacts defining business processes and workflow
in a text editor such as vi, or using a special Eclipse
plugin. The Eclipse plugin provides visual design capabilities, simplifying
packaging and deployment of the artifact to OpenIDM. See the Activiti BPMN 2.0 Eclipse Plugin documentation for
instructions on installing Activiti Eclipse BPMN 2.0 Designer.Also read the Activiti User Guide section
covering BPMN 2.0 Constructs, which
describes in detail the graphical notations and XML representations for
events, flows, gateways, tasks, and process constructs.Known Issues & LimitationsThe following are known issues and limitation for the experimental
embedded workflow and business process engine.OpenIDM does not include a form generator, making it difficult to
include embedded forms (OPENIDM-468).Error handling needs improvement.This version depends on Activiti 5.8, which does not have the fix
for ACT-583: Processes are not found in the .bar file
if they are below root.To work around this issue, create a directory inside the .bar, and
put the BPMN XML artifact in the directory so that it is properly picked up
by the Process Engine.Invoking Activiti WorkflowsYou can invoke workflows and business processes from any trigger point
OpenIDM offers, including reacting to situations discovered during
reconciliation. Invocation relies on the openidm.action()
function.
/*
* Calling 'myWorkflow' workflow
*/
var map = {
"_action" : "myWorkflow",
"_workflowParams" : {
"foo" : "bar"
}
};
openidm.action("workflow/activiti", map);Example Activiti Workflows With OpenIDMThis section describes two example workflows, one using email
notification, the other involving a sunset process triggered during
reconciliation.Example Email Notification WorkflowThis 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.The example sets up a workflow that can accept parameters used to
specify the sender and recipient of the mail.${fromSender}Used to specify the sender${toEmail}Used to specify the recipientOnce you have defined the workflow, drag and drop components to create
the workflow. This simple example uses only a
StartEvent, MailTask, and
EndEvent.Email notification processThe email notification workflow has a start event, mail task, and
end event.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="no-reply@forgerock.com"
></activiti:field>
<activiti:field name="subject" expression="Simple Email Notification"
></activiti:field>
<activiti:field name="html">
<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.Before you deploy the .bar, work around the issue mentioned above
by adding the XML artifact in the right place in the .bar, for example by
expanding the .bar, moving the
EmailNotification.bpmn20.xml file inside a directory,
and recreating the .bar.After you deploy the .bar, create a script in
openidm/script/invokeEmailNotification.js. The script
invokes the workflow.
/*
* Calling 'EmailNotification' workflow
*/
var map = {
"_action" : "emailNotification",
"_workflowParams" : {
"fromSender" : "noreply@openidm",
"toEmail" : "john.doe@corp.com"
}
};
openidm.action("workflow/activiti", map);Also, create a schedule configuration object in
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/invokeEmailNotification.js"
},
}
}Example Sunset Workflow Triggered By ReconciliationOpenIDM can allow deferred deprovisioning and disabling, such as
needed when an external consultant's contract expires or is up for
renewal. This example shows how OpenIDM can be used to handle such
scenarios.To understand the scenario, consider the target resource and the
authoritative source.Set up a CSV file connector to connect to an authoritative source
file containing the following.
firstName,uid,"lastName","email","employeeNumber",password,"sunrise","sunset","active"
"Darth","DDOE","Doe","doe@...","123456","Z29vZA==","2011-11-30T...","2011-12-23T...","TRUE"The authoritative source contains the field, sunset,
containing a time and date string referring to a time in the future.Set up a simple XML connector to replicate fields in the authoritative
CSV source on a 1-to-1 basis.Define a Sunset Workflow using Activiti Eclipse BPMN 2.0
Designer.Sunset workflow processThe sunset workflow starts by saving the invoke context, prepares
the call to OpenIDM, reads the user, runs an email notification, disables
the account, and ends.Use the following XML artifact.
<?xml version="1.0" encoding="UTF-8"?>
<definitions id="definitions"
xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:activiti="http://activiti.org/bpmn"
targetNamespace="Examples"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.omg.org/spec/BPMN/20100524/MODEL
http://www.omg.org/spec/BPMN/2.0/20100501/BPMN20.xsd">
<process id="sunset" name="sunset usecase">
<startEvent id="start" />
<sequenceFlow sourceRef="start" targetRef="saveInvokeContext"/>
<scriptTask id="saveInvokeContext" scriptFormat="groovy"
activiti:returnVariable="invokecontext">
<script>
<![CDATA[
invokecontext =
org.forgerock.openidm.context.InvokeContext.getContext()
]]>
</script>
</scriptTask>
<sequenceFlow sourceRef="saveInvokeContext"
targetRef="timerintermediatecatchevent1"/>
<intermediateCatchEvent id="timerintermediatecatchevent1"
name="TimerCatchEvent">
<extensionElements>
<activiti:field name="t" expression="${time}"
></activiti:field>
</extensionElements>
<timerEventDefinition>
<timeDate >${time}</timeDate>
</timerEventDefinition>
</intermediateCatchEvent>
<sequenceFlow sourceRef="timerintermediatecatchevent1"
targetRef="idmCall"/>
<serviceTask id="idmCall" activiti:delegateExpression="${openidm}"
activiti:async="true">
<extensionElements>
<activiti:field name="userName" expression="${userName}"
></activiti:field>
<activiti:field name="system" expression="${system}"
></activiti:field>
</extensionElements>
</serviceTask>
<sequenceFlow sourceRef="idmCall" targetRef="readUserAccount"/>
<scriptTask id="readUserAccount" scriptFormat="groovy"
activiti:returnVariable="user" >
<script>
<![CDATA[
out:println '********Sunset date for user ' + userName
org.forgerock.openidm.context.InvokeContext.getContext().
putApprover(invokecontext.getApprover())
org.forgerock.openidm.context.InvokeContext.getContext().
putRequester(invokecontext.getRequester())
org.forgerock.openidm.context.InvokeContext.getContext().
pushActivityId(invokecontext.popActivityId())
user = openidm.read(system + userName);
]]>
</script>
</scriptTask>
<sequenceFlow sourceRef="readUserAccount" targetRef="sendMail"/>
<serviceTask id="sendMail" name="Email Notification"
activiti:type="mail">
<extensionElements>
<activiti:field name="to" expression="${toEmail}"
></activiti:field>
<activiti:field name="from" expression="no-reply@forgerock.com"
></activiti:field>
<activiti:field name="subject" expression="Disabling User"
></activiti:field>
<activiti:field name="text">
<activiti:expression><![CDATA[
The following user has been disabled:
${user}]]>
</activiti:expression>
</activiti:field>
</extensionElements>
</serviceTask>
<sequenceFlow sourceRef="sendMail" targetRef="disableAccount"/>
<scriptTask id="disableAccount" scriptFormat="groovy">
<script>
<![CDATA[
out:println '********Disabling user account ' + userName
user['__ENABLE__'] = false
openidm.update(system + userName, null, user)
]]>
</script>
</scriptTask>
<sequenceFlow sourceRef="disableAccount" targetRef="end"/>
<endEvent id="end"/>
</process>
</definitions>Set up a deferred action during reconciliation by reacting to a
FOUND situation. When called, the script invoked must
return the proper action to the found situation, which in the case of this
example is LINK.Add the following script to
script/triggerSunset.js where you installed OpenIDM,
invoked when reconciliation encounters a FOUND
situation.
/*
* Calling 'sunrise' workflow
*/
var map = {
"_action" : "sunrise",
"_workflowParams" : {
"userName" : target.__UID__,
"system" : "system/xmlfile/account/",
"time" : source.sunset,
"toEmail" : "manager@corp.org",
"fromSender" : "noreply@openidm"
}
};
openidm.action("workflow/activiti", map);
"LINK"Add the following schedule to
conf/scheduler-reconcile_HR_XML.json where you
installed OpenIDM to invoke the script.
{
"enabled" : true,
"type" : "cron",
"schedule" : "0 08 16 * * ?",
"invokeService" : "sync",
"invokeContext" : {
"action" : "reconcile",
"mapping" : {
"name" : "CSV_XML",
"source" : "system/CSV/persons",
"target" : "system/xmlfile/account",
"correlationQuery" : {
"type" : "text/javascript",
"source" : "var myarray = [source.uid];var map = {
'query' : {
'Equals': {'field' : 'name','values' : myarray}
}
};map;"
},
"properties" : [
{
"source" : "firstname",
"target" : "firstname"
},
{
"source" : "uid",
"target" : "name"
},
{
"source" : "lastname",
"target" : "lastname"
},
{
"source" : "email",
"target" : "email"
}
],
"policies" : [
{
"situation" : "CONFIRMED",
"action" : "IGNORE"
},
{
"situation" : "FOUND",
"action" : {
"type" : "text/javascript",
"file" : "script/triggerSunset.js"
}
},
{
"situation" : "ABSENT",
"action" : "IGNORE"
},
{
"situation" : "AMBIGUOUS",
"action" : "IGNORE"
},
{
"situation" : "MISSING",
"action" : "IGNORE"
},
{
"situation" : "UNQUALIFIED",
"action" : "IGNORE"
},
{
"situation" : "UNASSIGNED",
"action" : "IGNORE"
}
]
}
}
}