tisdag 22 maj 2018

A emailNotification workflow revisit in IDM 6.0

Workflow continues to be a topic that intrigues people i meet in the field deploying ForgeRock IDM.

This blog post will illustrate out to configure IDM 6.0 to enable the embedded workflow engine, discuss some tools that are available and also build and deploy a simple workflow that can be deployed that sends a simple email Notification.

First off, the workflow module is no longer enabled by default and requires you to configure IDM 6.0 to enable it. By default IDM 6.0 gets deployed using an embedded ForgeRock Directory Server and since the workflow engine can't persist workflow and business process state in the DS, it needs a separate RDBMS. For this purpose, the in-memory database H2 is still embedded and automatically gets utilized for this purpose.

IDM 6.0 does support using a external DS as repo, even in production, but if you are considering using the Workflow module in production, you should also ensure you have a supported RDBMS up and running to manage the persisting of workflows.

The Activiti implementation on IDM 6.0 is unfortunately based on an older version of Activiti and the documentation ForgeRock points out on Alfresco/Activiti's website reference the Activiti Desinger for Eclipise, which is no longer available. Community members have filed a request to get binaries back but so far only the source code is available and should you require this plugin, you need to build it from scratch.

The URL to access the Activiti Desinger is available on GitHub at https://github.com/Activiti/Activiti-Designer.

Despite the Activiti engine not being a par with the latest and greatest from Alfresco/Activiti it is still one of the most important and widely deployed components for ForgeRock IDM.

This Blog post deals with the topic of configuring IDM 6.0 to enable the Workflow engine and to build out a simple email Notification that connects to an SMTP and sends an email. A Launch form will be used where the business process invoking user is able to provide parameters to the workflow.

To follow this little exercise i'm assuming some prerequisites.

1.) ForgeRock IDM 6.0 is installed, up and running. 
Latest version should be available from http://backstage.forgerock.com

2.) You have a Fake SMTP server up and running on localhost. 
You just need a fake service that will accept emails. I would recommend getting FakeSMTP from http://nilhcem.com/FakeSMTP/download.html, install and start this.

3.) That a BPMN 2.0 Editor is installed and can be leveraged. 

Should you require a BPMN 2.0 editor i could recommend the Yaoqiang BPMN Editor that has some nice features and is easy to work with. Yaoqiang BPMN Editor can be found and downloaded for free from https://sourceforge.net/projects/bpmn/files/latest/download?source=typ_redirect

The steps we will do are:

1.) Enable and configure IDM 6.0 to enable the workflow engine.
2.) Create an emailNotification workflow
3.) Deploy and test the workflow in IDM 6.0

Enable and configure IDM 6.0 to enable the workflow engine. 
IDM 6.0 is up and running. Log in as the openidm-admin user and orient yourself via the Admin UI to System Preferences and enable workflow.

This creates two json config files that you can study.

1.  $OPENIDM/conf/workflow.json (This is the location where IDM picks up deployed workflows in .bar file format or .xml format)

    "useDataSource" : "default",
    "workflowDirectory" : "&{idm.instance.dir}/workflow"

2.  $OPENIDM/conf/datasource.jdbc-default.json (DB store for Workflow)

    "driverClass" : "org.h2.Driver",
    "jdbcUrl" : "jdbc:h2:file:&{idm.install.dir}/db/activiti/database;MVCC=FALSE;DB_CLOSE_DELAY=0",
    "databaseName" : "activiti",
    "username" : "sa",
    "password" : {
        "$crypto" : {
            "type" : "x-simple-encryption",
            "value" : {
                "cipher" : "AES/CBC/PKCS5Padding",
                "salt" : "XXXXXXXXXXXXXXXXX==",
                "data" : "XXXXXXXXXXXXXXXXX==",
                "iv" : "XXXXXXXXXXXXXXXXX==",
                "key" : "openidm-sym-default",
                "mac" : "XXXXXXXXXXXXXXXXX"
    "connectionTimeout" : 30000,
    "connectionPool" : {
        "type" : "hikari",
        "minimumIdle" : 1,
        "maximumPoolSize" : 5

Now create $OPENIDM/workflow directory that is being referred to in the $OPENIDM/conf/workflow.json.

The workflow engine is now enabled and the requirements there for you to be able to deploy workflows. 

Create an emailNotification workflow
Now lets create our simple emailNotification workflow. Purpose of this simple process is to provide a launchform that allows the invoking user to provide some parameters. In this simplistic illustration we will offer the user to provide a toEmail parameter. The rest of the data will be static and hard code. Should you want to you can at your own pace experiment with this sample process to expand on the launch form and the email task to include a more dynamic behavior. 

To create this workflow you need a Start Event, a Service Task and an End Event. If you are using the Yaoqiang BPMN Editor you can just drag these activities out and connect the transitions from Start to Service Task to End.

Rename the Service Task to Email Notification.




Now you need to implement a Launch form. We do this in the Service Task that we have renamed Email Notification. Switch to "Source" mode and insert the necessary XML code to provide input via a form field. Our simple form will just provide a text field that takes input for the variable toEmail.

<startEvent id="startevent1" isInterrupting="true" name="Start" parallelMultiple="false">
        <activiti:formProperty id="toEmail" name="To Email:" variable="toEmail" writable="true"/>

Next up we want to set up the Service Task to send emails and define some the required parameters with some static values. 

<serviceTask activiti:type="mail" completionQuantity="1" id="mailtask1" implementation="##WebService" isForCompensation="false" name="Email Notification" startQuantity="1">
        <activiti:field expression="${toEmail}" name="to"/>
        <activiti:field expression="no-reply@forgerock.com" name="from"/>
        <activiti:field name="text">
              <string><![CDATA[Here is a simple Email Notification from ForgeRock IDM.]]></string>
        <activiti:field name="subject">
              <string><![CDATA[Simple Email Notification]]></string>


Now we have fully implemented the necessary components for this exercise and we are ready to deploy and test the workflow. 

Save the file somewhere temporarily and then manually copy the file to $OPENIDM/workflow/.

Make sure the FakeSMTP is up and running. 

Login to the self-service interface of IDM 6.0 and you will discovered that the emailNotification workflow is available at the bottom of the dashboard. Expand details and take it for a spin!

If everything is correctly assembled, you should be getting an email to the specified email address you defined in the launch form when invoking the process. 

-=[ THE END ]=-

Appendix - The actual BPMN definition. 

<?xml version="1.0" encoding="UTF-8"?>
 <process id="EmailNotification" name="emailNotification">
   <documentation>Simple Email Notification Task</documentation>
   <startEvent id="startevent1" name="Start">
    <activiti:formProperty name="To Email:" id="toEmail" variable="toEmail" writable="true" />
   <sequenceFlow id="flow1" name="" sourceRef="startevent1"
   <endEvent id="endevent1" name="End"></endEvent>
   <sequenceFlow id="flow2" name="" sourceRef="mailtask1"
   <serviceTask id="mailtask1" name="Email Notification"
       <activiti:field name="to" expression="${toEmail}"></activiti:field>
       <activiti:field name="from" expression="no-reply@forgerock.com"></activiti:field>
        <activiti:field name="text">
          <activiti:string><![CDATA[Here is a simple Email Notification from ForgeRock IDM.]]></activiti:string>
        <activiti:field name="subject">
          <activiti:string><![CDATA[Simple Email Notification]]></activiti:string>
 <bpmndi:BPMNDiagram id="BPMNDiagram_EmailNotification">
   <bpmndi:BPMNPlane bpmnElement="EmailNotification"
     <bpmndi:BPMNShape bpmnElement="startevent1" id="BPMNShape_startevent1">
       <omgdc:Bounds height="35" width="35" x="170" y="250"></omgdc:Bounds>
     <bpmndi:BPMNShape bpmnElement="endevent1" id="BPMNShape_endevent1">
       <omgdc:Bounds height="35" width="35" x="410" y="250"></omgdc:Bounds>
     <bpmndi:BPMNShape bpmnElement="mailtask1" id="BPMNShape_mailtask1">
       <omgdc:Bounds height="55" width="105" x="250" y="240"></omgdc:Bounds>
     <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 bpmnElement="flow2" id="BPMNEdge_flow2">
       <omgdi:waypoint x="355" y="267"></omgdi:waypoint>
       <omgdi:waypoint x="410" y="267"></omgdi:waypoint>


Inga kommentarer:

Skicka en kommentar