GuideGovernanceWorkflows

Governance Workflows

Overview

One of the most important features of the Overlord: DTGov software is the ability to trigger Governance Workflows based on changes detected in the S-RAMP repository. This chapter discusses this functionality, including:

1. How to create a workflow

2. Using DTGov supplied supporting Governance Services

3. How to deploy a workflow

4. Configuring a workflow to execute (trigger) when repository content changes

Creating Workflows

Overlord: DTGov integrates tightly with the jBPM business process management system. This allows DTGov to utilize any business process that is compatible with jBPM 6. The tooling available to author jBPM compatible business processes is varied and extensive (and is outside the scope of this document). One possibility is using the Eclipse based BPM tools. Another alternative is using the web based Drools authoring tools.

For additional information about how to create jBPM processes, please consult the jBPM and Drools documentation.

Deploying Workflows

All of the workflows and supporting files (images, task forms, etc) should be bundled together into a KIE archive. A KIE archive is simply a JAR with a particular structure assumed by jBPM. For example, your archive file structure might look something like this:

META-INF/kmodule.xml
SRAMPPackage/HttpClientWorkDefinitions.wid
SRAMPPackage/com.mybusiness.deploy.EARLifeCycle.bpmn2
SRAMPPackage/com.mybusiness.deploy.WARLifeCycle.bpmn2
SRAMPPackage/com.mybusiness.validate.NewSchemaReview.bpmn2
SRAMPPackage/run-build-install.png
SRAMPPackage/user-properties.png
SRAMPPackage/audio-input-microphone-3.png

What are all these files?

The kmodule.xml file is a jBPM artifact (it makes this a Kie Archive rather than just a plain old JAR file). This file should have the following content:

<?xml version="1.0" encoding="UTF-8"?>
<kmodule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://raw.github.com/droolsjbpm/droolsjbpm-knowledge/master/kie-api/src/main/resources/org/kie/api/kmodule.xsd"
         xmlns="http://jboss.org/kie/6.0.0/kmodule" >
    <kbase name="SRAMPPackage">
        <ksession name="ksessionSRAMP"/>
    </kbase>
</kmodule>

Next, there is a folder in the archive that maps to the kbase element found in the kmodule.xml file. This folder contains all of the business process resources, primarily the BPMN2 files. There is a file called HttpClientWorkDefinitions.wid which contains the custom work items used by Governance Workflows. It might look something like this:

import org.drools.process.core.datatype.impl.type.StringDataType;
[
  // the HttpClient work item
  [
    "name" : "HttpClientDeploy",
    "parameters" : [
      "Url" : new StringDataType(),
      "Method" : new StringDataType(),
      "Uuid" : new StringDataType(),
      "Target" : new StringDataType()
    ],
    "displayName" : "Deploy",
    "icon" : "run-build-install.png",
  ],

  // the HttpClient work item
  [
    "name" : "HttpClientNotify",
    "parameters" : [
      "Url" : new StringDataType(),
      "DTGovUrl" : new StringDataType(),
      "Method" : new StringDataType(),
      "Uuid" : new StringDataType(),
      "Target" : new StringDataType(),
      "Group" : new StringDataType(),
    ],
    "displayName" : "Notify",
    "icon" : "audio-input-microphone-3.png",
  ],

  // the HttpClient work item
  [
    "name" : "HttpClientUpdateMetaData",
    "parameters" : [
      "Url" : new StringDataType(),
      "Method" : new StringDataType(),
      "Name" : new StringDataType(),
      "Value" : new StringDataType(),
      "Uuid" : new StringDataType(),
    ],
    "displayName" : "UpdateMetaData",
    "icon" : "user-properties.png",
  ]
]

This file also refers to some images files (useful for BPMN editors) which are also included in the package.

Once the workflows are built, they must be deployed into the S-RAMP repository so that the embedded version of jBPM can find them properly. It is recommended that the S-RAMP maven integration is used to do this. The best way is to put all of the business process resouces into a simple JAR style maven project. Then use the S-RAMP maven integration to mvn deploy the project directly into S-RAMP. Please see the Overlord: S-RAMP documentation for details on how this works. The result should be that your Governance workflow JAR (Kie Archive) is uploaded to the S-RAMP repository, complete with relevant maven properties set.

The embedded jBPM engine will pick up the Governance Workflows by pulling the Kie Archive out of the S-RAMP repository and using the content it finds within. It’s worth noting that the maven information of the Kie Archive can be configured in the DTGov back end configuration file (dtgov.properties). The following properties control exactly what Kie Archive artifact the embedded jBPM engine will grab from S-RAMP:

dtgov.workflows.group=com.mybusiness
dtgov.workflows.name=governance-workflows
dtgov.workflows.version=1.0.7
dtgov.workflows.package=SRAMPPackage

DTGov Supporting Services

In order to make it a little easier to author interesting Governance Workflows, DTGov provides a set of useful Governance Services. A list of these services follows:

• Deployment Service - deploys a binary application artifact to a configured target

• Meta-Data Update Service - allows simple modification of an artifact’s meta-data

• Notification Service - provides a simple way to send email notifications

These services can be invoked by using the work items defined above in the HttpClientWorkDefinitions.wid file.

Note: more information about the Deployment Service can be found in the Deployment Management chapter of this guide.

Query Configuration

Currently the only way to trigger the execution of a Governance Workflow is by configuring an S-RAMP query that will be used to monitor the S-RAMP repository for interesting changes. When changes are discovered, a new instance of the configured workflow is created and invoked. This section of the guide describes how to configure these query triggers.

All query triggers are defined in the Governance configuration file (dtgov.properties). The following is an example of this configuration:

governance.queries=/s-ramp/ext/JavaEnterpriseApplication[@maven.artifactId]|com.mybusiness.deploy.EARLifeCycle.bpmn2|DeploymentUrl={governance.url}/rest/deploy/{target}/{uuid}::NotificationUrl={governance.url}/rest/notify/email/{group}/deployed/{target}/{uuid}
governance.queries=/s-ramp/xsd/XsdDocument|com.mybusiness.validate.NewSchemaReview.bpmn2|NotificationUrl={governance.url}/rest/notify/email/{group}/deployed/{target}/{uuid}::UpdateMetaDataUrl={governance.url}/rest/update/{name}/{value}/{uuid}

In the above example, two queries have been configured. The first is a query that will trigger the EARLifeCycle process whenever an EAR artifact is added to the repository. Note that only EAR artifacts added from Maven are targetted. The process will be passed two parameters:

1. DeploymentUrl

2. NotificationUrl

The second query will trigger the NewSchemaReview process whenever a new XML Schema document is added to the repository. This process will be passed two parameters:

1. NotificationUrl

2. UpdateMetaDataUrl