-
Notifications
You must be signed in to change notification settings - Fork 10
GuideGovernanceWorkflows
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:
-
How to create a workflow
-
Using DTGov supplied supporting Governance Services
-
How to deploy a workflow
-
Configuring a workflow to execute (trigger) when repository content changes
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.
You need to have installed DTGov from JBoss Overlord project or as a part of Red Hat JBoss Fuse Service Works 6 and JBoss Developer Studio along with the Integration Stack plugins:
-
JBoss Developer Studio with the Integration Stack can be installed according to Integration Stack for JBoss Tools and Developer Studio
-
FSW can be obtained from Red Hat JBoss Fuse Service Works and DTGov from JBoss Overlord project can be found at Overlord - JBoss Community.
At the moment DTGov only supports one KieJar for all DTGov workflows, so first thing you need to do, after starting JBDS, is to import the default dtgov workflows into you workspace:
-
In JBDS select File → Import → Maven → Existing Maven Projects and navigate to
<FSW installation>jboss-eap-6.1/data
where the dtgov workflows are located. The Maven integration in JBDS will take care of the rest.
-
At this point you can author new governance workflows in
src/main/resources/SRAMPPackage
folder. To create new BPMN2 Process Diagram select File → New → Other → BPMN2 → Generic BPMN 2.0 Diagram → Process Diagram Type.
-
Once the new process definition is opened in BPMN2 Modeler, make sure you have Custom tasks Modeler palette. If you don’t, right click on dtgov-workflows in Project Explorer → Properties → BPMN2 → Target Runtime → select 'JBoss jBPM 5 Business Process Engine'.
-
Create model a brand new BPMN2 workflow diagram of your own. You can use overlord.demo.SimpleReleaseProcess.bpmn, which is part of the default dtgov-workflows, as an inspiration and sample for configuring DTGov Supporting Services tasks. Official DTGov demos can be found here: https://github.com/Governance/dtgov/tree/master/dtgov-demos
-
Few tips for DTGov workflow modeling:
-
at first, set appropriate process id (will be used by DTGov to pick up the definition from S-RAMP repository) and package name:
-
-
second, create DTGov-specific Process variables in Data Items tab: DeploymentUrl , ArtifactUuid , Response , NotificationUrl , UpdateMetaDataUrl , DTGovUrl (these are used in DTGov Supporting Services):
You can download the guvnor console from the Drools-jBPM project and work on the workflows there. Once you are ready to deploy you will need to export the project and deploy to S-RAMP using a KJar format. Our experience is that this is similar to using the eclipse tooling but there are some differences regarding how to work with custom tasks. We therefor recommend using the eclipse based tooling. (note: this is an opportunity for you to contribute documentation)
For additional information about how to create jBPM processes, please consult the jBPM and Drools documentation.
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" scope="javax.enterprise.context.ApplicationScoped"> <workItemHandlers> <workItemHandler name="HttpClientDeploy" type="new org.overlord.dtgov.jbpm.util.HttpClientWorkItemHandler()"/> <workItemHandler name="HttpClientNotify" type="new org.overlord.dtgov.jbpm.util.HttpClientWorkItemHandler()"/> <workItemHandler name="HttpClientUpdateMetaData" type="new org.overlord.dtgov.jbpm.util.HttpClientWorkItemHandler()"/> </workItemHandlers> </ksession> </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 resources 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’s "Maven Integration" section 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
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.
E-mail templates for notifications can be modified at:
dtgov.war/WEB-INF/classes/governance-email-templates/
Note: more information about the Deployment Service can be found in the Deployment Management chapter of this guide.
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:
-
DeploymentUrl
-
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:
-
NotificationUrl
-
UpdateMetaDataUrl