Skip to content

GuideGovernanceWorkflows

Jump to bottom Edit New page
Eric Wittmann edited this page Jul 22, 2014 · 10 revisions

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

  5. Managing running Workflows (processes)

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.

Create Workflows using Eclipse Tooling.

Prerequisites

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:

Create new governance workflow

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.

Importing workflow project into your eclipse workspace
Figure 1. Importing workflow as maven project into your eclipse workspace
Importing workflow project into your eclipse workspace
Figure 2. Importing workflow as maven project into your eclipse workspace

  • 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.

Choose Generic BPMN 2.0 Diagram
Figure 3. Choose Generic BPMN 2.0 Diagram
Choose Generic BPMN 2.0 Diagram and enter the filename
Figure 4. Choose Generic BPMN 2.0 Diagram and enter the filename.

  • 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'.

Show the custom governance tasks
Figure 5. Show the custom governance tasks

  • 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:

Show the Workflow properties.
Figure 6. Show and set the Workflow properties.

  • second, create DTGov-specific Process variables in Data Items tab: DeploymentUrl , ArtifactUuid , Response , NotificationUrl , UpdateMetaDataUrl , DTGovUrl (these are used in DTGov Supporting Services):

Show the Workflow Data Items.
Figure 7. Show and set the Workflow Data Items.

Create Workflows using Drools web based tools.

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.

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" 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

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.

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.

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 as artifacts in the S-RAMP repository. These artifacts can be created and managed using the Workflow Trigger Query administrative UI found in DTGov. Simply log into the dtgov-ui web application and click on "Manage Workflow Queries" from the dashboard. You should see a screen like this:

Screenshot of the DTGov Workflow Queries Page
Figure 8. Screenshot of the DTGov data in S-RAMP

Use this page to manage the list of workflow trigger queries configured in DTGov.

Tip
 You must be an Overlord Admin to access the DTGov Workflow Trigger Query UI page

You can add new queries or edit existing queries (either by clicking 'Add Query' or by clicking one of the queries in the list). The resulting UI page will look like this:

Screenshot of the DTGov Edit Workflow Query Page
Figure 9. Screenshot of the DTGov data in S-RAMP

All Workflow Trigger Queries must have a name and description. In addition a valid S-RAMP query must be specified. All artifacts that are returned by the query will be processed and a new workflow instance created. The specific workflow that will be triggered must be chosen in the "Workflow" drop-down.

Finally, an optional set of properties can be specified to pass to the workflow. This is primarily useful in passing the various DTGov service URLs to the workflow, although arbitrary property mappings can be made. The following standard properties are supported and can be easily configured (with default values):

  • UpdateMetaDataUrl - the URL to the "Update Meta-Data" DTGov service

  • NotificationUrl - the URL to the "Notification" DTGov service

  • DeploymentUrl - the URL to the "Deployment" DTGov service

When the new process is created, the set of properties specified in the UI will be passed to the process. Additionally, the following standard properties will always be passed to the new process instance upon creation:

  • ArtifactUuid

  • ArtifactName

  • ArtifactVersion

  • ArtifactCreatedBy

  • ArtifactCreatedTimestamp

  • ArtifactLastModifiedBy

  • ArtifactLastModifiedTimestamp

  • ArtifactType

Managing Workflow Instances (Processes)

Once a new workflow instance is triggered for an artifact in the S-RAMP repository, the DTGov system will track the existence and status of that instance. This allows you to see how many workflow instances have been created and how many are currently running. There is a simple UI available in DTGov that provides this functionality. Simply log in to the DTGov UI and navigate to the "Workflows" section (linked off of the DTGov UI Dashboard page).

Tip
 You must be an Overlord Admin to access the DTGov Workflows UI page
Add a custom footer
Clone this wiki locally