JBoss.orgCommunity Documentation

DTGov Guide

1. Introduction to DTGov
1.1. Design Time Governance
1.2. Use Cases
1.3. How DTGov Works
1.4. The Sample Process Workflow: "SimpleReleaseProcess"
2. Getting Started
2.1. Prerequisites
2.2. Download, Installation and Configuration
2.3. Check your Installation
2.4. Get to Work
3. User Management
3.1. Overview
3.2. Required Roles
3.3. Adding a User
3.3.1. JBoss EAP 6
3.3.2. JBoss Fuse 6.1
3.3.3. Tomcat 7
3.3.4. Jetty 8
4. Configuring DTGov
4.1. Overview
4.2. Back-End Configuration
4.3. Back-End Configuration Properties
4.4. User Interface (UI) Configuration
4.5. UI Configuration Properties
4.6. Configuring UI Deployment Stages
4.7. Configuring UI Deployment Types
4.8. Configuring Authentication
5. DTGov and S-RAMP
5.1. Overview
5.2. Configuration Properties
5.3. Authentication
6. Governance Workflows
6.1. Overview
6.2. Creating Workflows
6.2.1. Create Workflows using Eclipse Tooling.
6.2.2. Create Workflows using Drools web based tools.
6.3. Deploying Workflows
6.4. DTGov Supporting Services
6.5. Query Configuration
7. Configuring the Notification Service
7.1. Invoking the Notification Service
7.2. Notification Destinations
7.3. Email Templates
7.3.1. S-RAMP Artifact Templates
7.3.2. Classpath Templates
7.3.3. Template Lookup Summary
8. Governance Human Tasks
8.1. Overview
8.2. Using Human Tasks in a Workflow
8.3. Custom Task Forms
8.4. Fail Button
8.5. Customizing the Task API
9. Managed Deployments
9.1. Overview
9.2. Invoking the Deployment Service
9.3. Configuring Deployment Targets
9.4. Undeployment
9.5. Demo
9.5.1. Summary
9.5.2. Requirements
9.5.3. How It Works
9.5.4. Artifact Deployment
9.5.5. Classify as DevTest
9.5.6. Notify Dev
9.5.7. Test Dev
9.5.8. Gateway
9.5.9. Governing Deployments
10. SOA Governance Projects and Organizational Roles
10.1. Introduction
10.2. Demo Maven Project Workflow Integration
10.2.1. Summary
10.2.2. How It Works
10.2.3. Signaling Analysis Docs Complete
10.2.4. Signaling Architecture Docs Complete
10.2.5. Signaling Service implementation Complete

First, we recommend you download the following:

Next, you must follow these steps to install and configure the application:

  1. Download and install your preferred runtime platform. We currently support:

    1. JBoss EAP 6.3
    2. JBoss Fuse 6.1
    3. Tomcat 7
    4. Jetty 8
  2. Download and unpack S-RAMP 0.5.0.Final
  3. Download and unpack DTGov 1.3.0.Final
  4. Run the S-RAMP installer, installing into your installed runtime platform
  5. Run the DTGov installer, installing into your installed runtime platform
  6. Start your application container (e.g. JBoss EAP)
  7. Populate the S-RAMP repository with DTGov seed data

Some psuedo-shell code that might help

mkdir ~/overlord
cd ~/overlord
# Download JBoss EAP 6.3 (e.g. jboss-eap-6.3.0.zip)
#    From - http://www.jboss.org/jbossas/downloads
# Download S-RAMP distribution (s-ramp-0.5.0.Final.zip)
#    From - http://www.jboss.org/overlord/downloads/sramp
# Download S-RAMP distribution (dtgov-1.3.0.Final.zip)
#    From - http://www.jboss.org/overlord/downloads/dtgov
unzip jboss-eap-6.3.0.zip
unzip s-ramp-0.5.0.Final.zip
unzip dtgov-1.3.0.Final.zip
cd s-ramp-0.5.0.Final
ant install
# !!Follow installation instructions here!!
cd ~/overlord/dtgov-1.3.0.Final
ant install
# !!Follow installation instructions here!!
# Start JBoss (~/overlord/jboss-eap-6.1/bin/standalone.sh) - wait for startup to complete
cd ~/overlord/dtgov-1.3.0.Final
ant seed -Ds-ramp.shell.password=ADMIN_PASSWORD

The dtgov.war and dtgov-ui.war applications are deployed to the runtime platform during the installation. The DTGov web UI (http://localhost:8080/dtgov-ui) is provided by dtgov-ui.war. You will see references to these in the server.log at startup and when the services are invoked.

It’s all installed, running, and checked? Now it’s time to use the software! This guide will explain advanced configuration and usage, but you can get started by logging in to the DTGov User Interface as admin:


It’s likely that users will need to customize the system based on their organization’s specific work processes. The Configuring and Governance Workflows chapters should be helpful in describing how to customize the system.

By default DTGov uses the standard EAP Application Realm configuration as its authentication source. This means that adding users is a simple matter of using the existing EAP add-user script. If you are running on Windows you can use the add-user.bat script. Otherwise run the add-user.sh script. Both of these scripts can be found in EAP’s bin directory.

Here is an example of how to add an S-RAMP user using the add-user.sh script:

[user@host jboss-eap-6.x]$ pwd
[user@host jboss-eap-6.x]$ ./bin/add-user.sh

What type of user do you wish to add?
 a) Management User (mgmt-users.properties)
 b) Application User (application-users.properties)
(a): b

Enter the details of the new user to add.
Realm (ApplicationRealm) : ApplicationRealm
Username : fitzuser
Password : P4SSW0RD!
Re-enter Password : P4SSW0RD!
What roles do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[  ]: overlorduser,admin.sramp,dev,test
About to add user 'fitzuser' for realm 'ApplicationRealm'
Is this correct yes/no? yes
Added user 'fitzuser' to file '/home/user/FSW6/jboss-eap-6.x/standalone/configuration/application-users.properties'
Added user 'fitzuser' to file '/home/user/FSW6/jboss-eap-6.x/domain/configuration/application-users.properties'
Added user 'fitzuser' with roles overlorduser,admin.sramp to file '/home/user/FSW6/jboss-eap-6.x/standalone/configuration/application-roles.properties'
Added user 'fitzuser' with roles overlorduser,admin.sramp to file '/home/user/FSW6/jboss-eap-6.x/domain/configuration/application-roles.properties'
Is this new user going to be used for one AS process to connect to another AS process?
e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.
yes/no? no


the above example will create a user who can view and complete Dev and Test environment human tasks. Any other human tasks will not be visible.

# S-RAMP API connection endpoint
# Whether to validate the S-RAMP connection
# What kind of authentication to use (class name)
# Only used when the provider is basic auth
# Only used when the provider is SAML bearer token auth

# Task API connection endpoint
# Implementation of a task client
# Authentication to use when invoking the task API
# Only used when using basic auth
# Only used when using saml bearer token auth

# Deployment lifecycle base classifier
# Classifier to use when querying for all deployments
# This next one is a prefix for any property that will indicate a possible classifier stage that
# should be displayed in the UI.  In the dtgov ui configuration file, multiple properties would
# be specified that begin with this prefix and have a value of the format  {label}:{classifier}
# And another one that is a prefix for any property that will indicate a possible deployment type
# that should be displayed in the UI.  In the dtgov ui configuration file, multiple properties would
# be specified that begin with this prefix and have a value of the format  {label}:{type}

# S-RAMP UI integration properties

In particular, the dtgov-ui.deployment-lifecycle.classifiers.stage and dtgov-ui.deployment-lifecycle.types properties require further explanation. See the following sections for details.

By default, the S-RAMP repository and all of the Design Time Governance REST services are protected by BASIC and SAML Bearer Token authentication mechanisms (allowing clients to use either). Configuring the authentication of the REST services varies depending on application server. In JBoss the authentication is typically configured in the standalone.xml file. This section describes how the various client components can be configured when the server authentication mechanism is changed.

There are several Design Time Governance components that invoke protected REST services, and each component must be configured individually. In each case an authentication provider must be implemented and configured via either dtgov.properties or dtgov-ui.properties. The following are the client components which can be customized in this way:

  • DTGov :: S-RAMP Repository Monitoring (automated process that triggers workflows when repository changes are detected)
  • DTGov :: Governance Services Invoking the S-RAMP API (some of the Governance REST services invoke the S-RAMP API)
  • DTGov UI :: S-RAMP Invokes (the UI displays governance data that it gets from the S-RAMP repository)
  • DTGov UI :: Task Inbox Invokes (the UI queries a pluggable Task API to get human task data for display in the Task Inbox)

In each case, an authentication provider can be specified that will control how authentication information is passed to the service being invoked. The authentication provider must be a Java class that implements a specific provider interface. The classname can be set in the relevant configuration file. The following table provides the relevant details for each component:

ComponentProvider InterfaceConfig PropertyConfig File

DTGov :: S-RAMP Repository Monitor




DTGov :: Governance Services → S-RAMP




DTGov UI :: S-RAMP Invokes




DTGov UI :: Task Inbox Invokes





A reasonable example might be that the Task API is configured to use some alternative authentication mechanism, in which case the DTGov UI must be configured with a different (custom) provider. The following steps will accomplish this:

  1. Create a new Java class that implements org.overlord.dtgov.taskclient.auth.AuthenticationProvider
package org.example.auth;

import org.apache.http.HttpRequest;
import org.overlord.dtgov.taskclient.auth.AuthenticationProvider;

public class CustomAuthenticationProvider implements AuthenticationProvider {
    // Constructor.
    public NoAuthenticationProvider() {
        // Note, you may also choose to have a constructor that accepts an Apache Commons
        // Configuration object, which will allow you to access configuration properties
        // in the dtgov-ui.properties file:
        // org.apache.commons.configuration.Configuration

    // Provide any custom authentication here.
    public void provideAuthentication(HttpRequest request) {
      // Do custom authentication now.
  1. Configure the provider in dtgov-ui.properties
# Optional custom configuration properties
  1. That’s it!

A number of configuration properties drive the integration between DTGov and S-RAMP. In particular note that the DTGov back-end and the DTGov User Interface each have their own separate configuration. This is because the back-end and UI are separate applications that can be independently deployed.

Note that in addition to configuring the DTGov UI itself, the shared Overlord Header functionality (the top header for all Overlord applications) must also be customized so that the tabs in the header point to the right places. This is done by customizing the files installed (for example) in $jboss_home/standalone/configuration/overlord-apps.

DTGov Back-End Configuration

# S-RAMP Connection details

DTGov User Interface Configuration

# S-RAMP API connection endpoint

overlord-apps/*-overlordapp.properties Configuration


Now for some examples. These examples assume that S-RAMP has been installed on server "sramp.example.org" and DTGov has been installed on server "dtgov.example.org".

First let’s make sure the UI Headers are propertly configured. To do this, we want to make sure that the files in overlord-apps are properly configured and copied to both servers (when running in EAP these files are found in $jboss_home/standalone/configuration/overlord-apps). There are two files of importance: srampui-overlordapp.properties, dtgov-overlordapp.properties

Example: srampui-overlordapp.properties

overlordapp.primary-brand=JBoss Overlord
overlordapp.secondary-brand=S-RAMP Repository

Example: dtgov-overlordapp.properties

overlordapp.label=Design Time
overlordapp.primary-brand=JBoss Overlord

Now both servers should know where the appropriate UIs are located. This allows the shared Overlord Header (at the top of all Overlord UIs) to create the appropriate tabs.

Next let’s make sure that the DTGov back-end can properly communicate with the S-RAMP repository. This is done by editing the dtgov.properties file on the dtgov server.

Example: DTGov Back End Configuration


The above configuration uses BASIC authentication when connecting to the S-RAMP repository. It will connect to S-RAMP at "sramp.example.org" (port 8080). Note that the DTGov back-end uses BASIC authentication against the S-RAMP repository because some of the functionality in DTGov occurs on the behalf of a workflow without the security context of an authenticated user. Obviously you must make sure that the user credentials you list in the configuration represent a valid S-RAMP repository user. We recommend creating a "dtgov" or "dtgovworkflow" user in S-RAMP for this purpose. Most likely you will be sharing users/authentication between the two servers in some way, but that is beyond the scope of this documentation.

Now that the back end is configured, we can configure the DTGov UI so it knows where the S-RAMP repository is (as well as where the S-RAMP UI is!). This is done by editing the dtgov-ui.properties file on the dtgov server.

Example: DTGov UI Configuration



The above configuration connects to S-RAMP at "sramp.example.org" (port 8080) and uses SAML bearer token authentication. Please note that both the S-RAMP repository and the DTGov installation must share the same SAML keystore (the keystore contains encryption keys used to sign and verify SAML Assertions). This can be done by making sure that overlord-saml.keystore is the same file for both installations. Also note that the SAML Assertion used in this type of authentication has a time-to-live of only 10 seconds per request. This means that both of your servers must have their system times reasonably well in sync or this time-to-live test may fail.

The configuration also sets up the URL of the S-RAMP browser (UI). This is important because the DTGov UI occassionally creates links directly to the S-RAMP browser. Please note that this latter functionality may be adversely affected by user authentication (if the user must re-authenticate when navigating from the DTGov UI to S-RAMP UI then the right page may not display).

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.

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

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

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:


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"
         xmlns="http://jboss.org/kie/6.0.0/kmodule" >

    <kbase name="SRAMPPackage">
        <ksession name="ksessionSRAMP" scope="javax.enterprise.context.ApplicationScoped">
        		<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()"/>


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:


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:

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

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:

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

The Notification Service is a service included by DTGov to make it easy to send out email notifications to users directly from the workflow. However, it can easily be used to send email notifications by any client that can perform a simple REST API call. This chapter describes how to enable and configure the Notification Service.

First, DTGov must either be configured with an "email" notification destination in the dtgov.properties file or the destination configuration must be left blank so that the default email settings are used. To configure explicit destination settings, the following can be set in the dtgov.properties file:


This allows a mapping of logical group names to real destination email addresses. Note that the toAddresses value is a colon-separated list of real email addresses. Therefore an example configuration might be:


If the governance.email property information is missing from dtgov.properties, then an implicit mapping will be used based on the group name passed to the Notification Service when it is invoked and the following global email settings configured in dtgov.properties:


When these default settings are used, the Notification Service will send the email from the configured from address specified above to the following email address:


The group name is whatever is passed to the notification service and the domain comes from the governance.email.from property in dtgov.properties.

When sending an email notification, the subject and body of the email are generating by leveraging a template. When invoking the Notification Service, the template name is passed as one of the REST path segments. This logical name is used to look up the email template either from the classpath or from the S-RAMP repository.

The resulting template is then processed so that any Ant-style properties found in the template are resolved. A typical email body template might look like this:

Artifact ${uuid} with name '${name}' has been deployed to target ${target}.
Please claim this task, test this deployment and set a pass/fail status at the taskform at



There are two types of templates: one for the email body and one for the email subject. These template files can be located either on the classpath or in the S-RAMP repository.

Whenever a task is created in a governance workflow (using a human task activity as discussed above), the Task Inbox is responsible for presenting the details of the task to relevant users. The Task Inbox allows users to perform human task related actions such as claiming, starting, and completing the tasks assigned to them.

It is important to understand that the Task Inbox must have access to a Form for each type of task it is expected to display. This is accomplished by creating a Task Form XML file for each type of task used in your Governance workflow(s). A Task Form XML file is simply an HTML5 snippet with the presentation markup specific to a task type. The Task Form XML file must be added to the S-RAMP repository that the DTGov system is connected to, so that it can be looked up when DTGov is presenting the task instance to a user.

An example Task Form XML file follows:

      You are hereby notified that a new Schema artifact named
      <b><span data-name="SchemaName">Unknown</span></b> has
      been added to the repository.  Please review it.
    <label class="radio">
      <input type="radio" name="Status" value="pass"></input>
      Schema accepted as valid
    <label class="radio">
      <input type="radio" name="Status" value="fail"></input>
      Schema <em>not</em> accepted

Custom task forms in DTGov will be pulled from the S-RAMP repository when needed and displayed dynamically in the user interface. Any input variables configured in the human task activity (in the governance workflow) will be used as inputs to the form. Inputs can be substituted into the following HTML elements:

  • input type="text"
  • input type="hidden"
  • textarea
  • input type="checkbox"
  • input type="radio"
  • select
  • div
  • span
  • label

For HTML elements with name attributes (e.g. input, select, textarea), the name of the element must match the input variable name. For all other HTML elements the name must be specified in a data-name attribute.

When the user completes or fails a task, the data they entered in the task form is gathered up and submitted to the task engine (and is consequently sent back to the governance workflow).

Once the Task Form XML file is written, it must be added to the S-RAMP repository. The name of the file (and thus the name of the artifact in the S-RAMP repository) must be of the form:


The taskName can be identified and configured when setting up the human task activity in your workflow. For example, if you configure the task name in your workflow to be mycompany.appx.VerifySchema then the Task Form XML file should be added to S-RAMP with a name of mycompany.appx.VerifySchema-taskform.xml.

Invoking the Deployment Service from a Governance Workflow should be a simple matter of using the HttpClientDeploy task defined in the HttpClientWorkDefinitions.wid file as described in the Governance Workflows chapter of this guide. Within a BPMN2 process, the XML markup might look something like this:

<bpmn2:task id="Task_1" drools:taskName="HttpClientDeploy" drools:displayName="Deploy" drools:icon="run-build-install.png" name="Deploy to DEV">
  <bpmn2:ioSpecification id="_InputOutputSpecification_10">
    <bpmn2:dataInput id="_DataInput_47" itemSubjectRef="__NameInputItem" name="Url"/>
    <bpmn2:dataInput id="_DataInput_48" itemSubjectRef="__NameInputItem" name="Method"/>
    <bpmn2:dataInput id="_DataInput_49" itemSubjectRef="__NameInputItem" name="Uuid"/>
    <bpmn2:dataInput id="_DataInput_50" itemSubjectRef="__NameInputItem" name="Target"/>
    <bpmn2:inputSet id="_InputSet_10" name="Input Set 10">
  <bpmn2:dataInputAssociation id="_DataInputAssociation_47">
  <bpmn2:dataInputAssociation id="_DataInputAssociation_48">
    <bpmn2:assignment id="Assignment_1">
      <bpmn2:from xsi:type="bpmn2:tFormalExpression" id="FormalExpression_16">POST</bpmn2:from>
      <bpmn2:to xsi:type="bpmn2:tFormalExpression" id="FormalExpression_17">_DataInput_48</bpmn2:to>
  <bpmn2:dataInputAssociation id="_DataInputAssociation_49">
  <bpmn2:dataInputAssociation id="_DataInputAssociation_50">
    <bpmn2:assignment id="Assignment_14">
      <bpmn2:from xsi:type="bpmn2:tFormalExpression" id="FormalExpression_17">dev</bpmn2:from>
      <bpmn2:to xsi:type="bpmn2:tFormalExpression" id="FormalExpression_18">_DataInput_50</bpmn2:to>

The above task uses the DeploymentUrl and ArtifactUuid parameters that were passed in to the business process when it was invoked. It populates the inputs required by HttpClientDeploy including an input parameter named Target. The Target parameter maps to a configured Deployment Target. The target is a logical name and corresponds to a physical runtime environment configured in the DTGov configuration file (dtgov.properties). See the next section for details.

In order to make logical Deployment Targets available they must be configured in the DTGov configuration file. Typically an organization would configure three or four Deployment Targets, including:

  • dev - the development environment
  • qa - the test environment
  • stage - the staging environment
  • prod - the final production environment

Of course, any number of targets can be configured. Here is an example of how to configure the above four targets in the DTGov configuration file:

governance.targets=  dev|http://www.jboss.org/overlord/deployment-status.owl#InDev|copy|/tmp/dev/jbossas7/standalone/deployments
governance.targets=   qa|http://www.jboss.org/overlord/deployment-status.owl#InQa|copy|/tmp/qa/jbossas7/standalone/deployments
governance.targets= prod|http://www.jboss.org/overlord/deployment-status.owl#InProd|copy|/tmp/prod/jbossas7/standalone/deployments

The format of each target is as follows:


  • LogicalName : used in the BPMN process as described in the previous section as the value of Target
  • Classifier : a classifier that should get added to the binary deployment artifact when deployed to the target environment (and removed when undeployed)
  • DeploymentType : how to deploy to the environment. Valid values as of this writing include copy, rhq, as_cli, maven

Depending on the type of the deployment, additional parameters may be required. In the example above, the copy deployment type requires a folder on the server, which is where it will copy the deployment artifact.

Here are some examples of how to use the other deployment types:

# Deploy using RHQ/JON (username, password, rhq url)
# Deploy using the JBoss AS CLI  (username, password, host, port)
# Deploy to a Maven Repository (maven-url, is-release-enabled, is-snapshot-enabled

For a short video see: http://jboss-overlord.blogspot.com/2013/11/managed-deployments-using-dtgov.html

Be aware that you must supply the maven build with credentials for your S-RAMP repository. This can be done by adding a section to your settings.xml file (or by providing a custom settings.xml on the mvn command line using the -s argument).

For more information see: http://maven.apache.org/settings.html

Your settings.xml file should contain two additional server entries in the servers section:


To get this demo working you must be running the DTGov server and the S-RAMP repository (see documentation for the DTGov and S-RAMP projects to learn how to run the S-RAMP repository).

The first step is to build and deploy all artifacts to S-RAMP using Maven. The demo is configured to run against the default security settings found in the distribution.


Authentication settings in your .m2/settings.xml are required.

$ mvn -Pdemo clean deploy

The -Pdemo flag will enable the demo profile, which tells the Maven distributionManagement to point to your local S-RAMP repository (http://localhost:8080/s-ramp-server/). Therefore you need to be running S-RAMP on port 8080 and deployed as the s-ramp-atom context.

The build should complete successfully and on the server you should see logging along the lines of

09:04:10,929 INFO  [org.overlord.sramp.governance.QueryExecutor] (EJB default - 5) Starting workflow overlord.demo.SimpleReleaseProcess for artifact 44021610-f85e-48bf-9a1c-9adcdbe485b6

At this point there should be a number of artifacts stored in the S-RAMP repository. You can verify that by deploying the "s-ramp-ui" project and then navigating to http://localhost:8080/s-ramp-ui (or the appropriate URL for you).

You should see the following primary artifacts in the S-RAMP repository:

  • dtgov-demos-switchyard-VERSION.jar
  • dtgov-demos-switchyard-VERSION.pom
  • OrderService.wsdl
  • beans.xml
  • orders
  • org.overlord.sramp.demos.switchyard.service.InventoryService
  • org.overlord.sramp.demos.switchyard.service.InventoryServiceBean
  • org.overlord.sramp.demos.switchyard.service.Order
  • org.overlord.sramp.demos.switchyard.service.OrderAck
  • org.overlord.sramp.demos.switchyard.service.OrderService
  • org.overlord.sramp.demos.switchyard.service.OrderServiceBean
  • org.overlord.sramp.demos.switchyard.service.Transformers

Where the OrderService.wsdl, beans.xml, orders as well as some class With the query defined in the dtgov.properties:


it will start a SimpleReleaseProcess workflow when a SwitchYardApplication lands in the repository. You should see a custom property getting created which should look similar to


Note that the definition of the overlord.demo.SimpleReleaseProcess lives in the SRAMPPackage in the dtgov-workflows-VERSION.jar. If you want to update the workflow you need to use eclipse tooling to modify the bpmn, build and upload a new dtgov-worflow.jar to S-RAMP. The GAV settings are defined in the dtgov.properties file.

The workflow (and the deployment ontology) specifies four different environments:

  • dev - development: machine hosting deployed released artifact before they go to QA. Developers can do a quick test to make sure things work on more then just their desk.
  • qa - quality assurance: machine hosting deployed released artifacts so that they can go through the testing process.
  • stage - staging: an environment identical to production where qa’ed artifacts can be tested on the real hardware and with interactions with other systems.
  • prod - production: the final place where the artifacts are deployed and run

    When the _SimpleReleaseProcess_ is instantiated it deploy the artifact to the _dev_ environment.
    The workflow makes a POST call to DeploymentUrl={governance.url}/rest/deploy/{target}/{uuid}
    * {governance.url} is location where the DTGov REST API is hosted; this defaults to 'http://localhost:8080/dtgov'
    and can be overridden in the dtgov.properties.
    * {target} is the name of the deployment target which defined in the dtgov.properties and is
    referenced in the 'Deploy to Dev' task.
    * {uuid} is the UUID of the artifact which is set as a process parameter in the _SimpleReleaseProcess_
    instance at creation time.

In this case, we assume the dev target is defined as

governance.targets=  dev|http://www.jboss.org/overlord/deployment-status.owl#InDev|copy|/tmp/dev/jbossas7/standalone/deployments

where * dev: name of the target * http://www.jboss.org/overlord/deployment-status.owl#InDev: classification when deployed to Dev * copy: use file copy * /tmp/dev/jbossas7/standalone/deployments: deploy directory

We assume there is jbossas7 server running in /tmp/dev/jbossas7, and thus it uses a simple file copy to place the artifact in /tmp/dev/jbossas7/standalone/deployments. The appserver will take of deploying the artifact and on the server we should see logging along the lines of

09:04:11,168 INFO  [org.overlord.dtgov.jbpm.util.HttpClientWorkItemHandler] (EJB default - 5) Calling POST TO: http://localhost:8080/dtgov/rest/deploy/dev/44021610-f85e-48bf-9a1c-9adcdbe485b6
09:04:11,274 INFO  [org.jboss.resteasy.cdi.CdiInjectorFactory] (http-/ Found BeanManager at java:comp/BeanManager
09:04:11,300 INFO  [org.jboss.resteasy.spi.ResteasyDeployment] (http-/ Deploying javax.ws.rs.core.Application: class org.overlord.sramp.governance.services.GovernanceApplication$Proxy$_$$_WeldClientProxy
09:04:12,170 INFO  [org.overlord.dtgov.jbpm.util.HttpClientWorkItemHandler] (EJB default - 5) reply={status=success, target=COPY:/tmp/dev/jbossas7/standalone/deployments/dtgov-demos-switchyard-2.0.0-SNAPSHOT.jar}

The next task Classify #DevTest calls a REST service in DTGov using endpoint using a PUT to:

where * {governance.url} is location where the DTGov REST API is hosted; this defaults to http://localhost:8080/dtgov and can be overridden in the dtgov.properties. instance at creation time.

which adds the #DevTest classification onto the artifact. You can verify by navigating to this details of this artifact in the s-ramp-ui or by using the s-ramp.sh cli. The logging on the server should read

09:04:12,202 INFO  [org.overlord.dtgov.jbpm.util.HttpClientWorkItemHandler] (EJB default - 5) Calling PUT TO: http://localhost:8080/dtgov/rest/update/classification/http%3A*2F*2Fwww.jboss.org*2Foverlord*2Fdeployment-status.owl%23DevTest/44021610-f85e-48bf-9a1c-9adcdbe485b6
09:04:12,414 INFO  [org.overlord.dtgov.jbpm.util.HttpClientWorkItemHandler] (EJB default - 5) reply={artifactName=dtgov-demos-switchyard-2.0.0-20131107.140403-1.jar, artifactCreatedBy=admin, status=success}

The next task in the SimpleReleaseProcess is an email notification. The "Notification Task" calls a REST service in DTGov using a POST to:

where * {governance.url} is location where the DTGov REST API is hosted; this defaults to http://localhost:8080/dtgov and can be overridden in the dtgov.properties. is is set to dev the first go-around. * deployed is the name of the notification template. referenced in the Deploy to Dev task. This info is construct the notification message. instance at creation time.

On the server we should see the following logging

09:04:12,419 INFO  [org.overlord.dtgov.jbpm.util.HttpClientWorkItemHandler] (EJB default - 5) Calling POST TO: http://localhost:8080/dtgov/rest/notify/email/dev/deployed/dev/44021610-f85e-48bf-9a1c-9adcdbe485b6
09:04:12,862 INFO  [org.overlord.dtgov.jbpm.util.HttpClientWorkItemHandler] (EJB default - 5) reply={status=success}

By default an email is sent the server localhost at port 25. By default the TO address used is overlord@example.com. If you don’t want to use example.com then this can be overridden in the dtgov.properties using key governance.email.domain and governance.email.from for the FROM address. It is recommended to use an email alias or group to tie the group email to actual email addresses.

The email contains the following info:

Subject: [Overlord-dev] dtgov-demos-switchyard-2.0.0-20131106.145057-1.jar
 is deployed

Artifact 6eccc2f4-b687-4882-9a05-fc446bbb8a44 with name 'dtgov-demos-switchyard-2.0.0-20131106.145057-1.jar' has been deployed to target dev.
Please claim this task, test this deployment and set a pass/fail status at the taskform at



and Figure Figure 9.2, “Notification Email in FakeSMTP” shows displays the email in the FakeSMTP UI.

Email templates are deployed in the dtgov.war/WEB-INF/classes/governance-email-templates directory. in this case are deployed.subject.tmpl and deployed.subject.tmpl.

In large organizations building and maintaining services is not a one man job, instead it is a process that touches many people in the organization. Figure 10.1, “SOA Governance Roles” is a copy of figure 5.6 on page 95 of the SOA Governance book by Thomas Erl et al.

With this many people and roles involved, how to you manage a project like this? Especially since in a large organization you will have many of these project running simultaneously. We would have loved to implement a full project workflow based on the figure 1 process, but two things are currently standing in our way: time and real world input. Who is going to pick up the challenge?

To get you started we created a Simplied Project Lifecycle Workflow demo that implements just 3 boxes; Requirements gathering, Service Design and Service Implementation, with one role responsible for each stage, which are a Business Analyst, SOA Architect and SOA Developer. Each role can be fulfilled by more then one person. In the demo we assigned all three roles to the admin user so we don’t have to log in and out as different users all time. The demo uses the workflow shown in Figure 10.3, “Project Workflow”. Each column represents one of the phases. The first phase being Business Analysis. The hope is this demo provides you with the building blocks to create the real world implementation we talked about earlier.

Some benefits of using this workflow are:

  • Helps your organization with adoption of SOA by following proven processes. It is clear who is responsible for approval.
  • Provides insight in where your projects are.
  • Helps your organization work together in different teams.
  • Audit features allow full history tracking.
  • Released artifacts are in the repository, the artifact is automatically in escrow this way, and documentation and sources are stored along side the binaries all in one place.

Some optional benefits:

It is possible to send a BPMN event at the end of the workflow (or from anywhere else), which can kick off a release workflow to automate deployment. Though one could also write a governance query looking for a service implementation artifact with classification #ImplPass.
Easy integration with other systems (think bug track systems, or time management systems)

If you want to follow along with the demo you should

  1. Have DTGov running; see http://jboss-overlord.blogspot.com/2013/11/bleeding-edge-governance-getting-started.html.
  2. Install the Eclipse BPMN2 Modeler into your Eclipse IDE, or you can try the early access JBoss Developer Studio.

For a short video see: http://jboss-overlord.blogspot.com/2013/11/soa-governance-projects-and.html

This demo shows how teams can collaborate using a ProjectLifeCycle Workflow. In this example we have a simplified Project workflow with only three phases with their respective teams. Each team delivers a set of deliverables which are uploaded to the repository. Each upload triggers a review of the artifacts. The artifacts are groupedBy an ArtifactGrouping which is represented as a parent in S-RAMP.

This demo contains three submodules:

  • project-requirements: a requirements doc created a Business Analyst.
  • project-service-api: a service design created by a SOA-Architect.
  • project-service-impl: the service implementation created by a SOA Developer.

The overlord.demo.ProjectLifeCycle.bpmn resides in the dtgov-workflow.jar in the SRAMPPackage and this should already be deployed. Also the classification ontologies should already have been installed as part of the data seeding process during install of DTGov. In the s-ramp-ui artifacts screen you can click on Classifiers to check that the Project Review Status is present.

These classifications will be applied by the Classify nodes in the workflow as the project moves through its lifecycle.

You can create and update workflows using the Eclipse BPMN Editor, which can be installed from http://download.eclipse.org/bpmn2-modeler/updates/kepler/ (1.0 or newer). The project starts with a business analyst creating a requirements document, which is then reviewed and approved. On a successful approval a SOA-Architect creates a design, followed with another review meeting and finally a SOA-Developer creates an implementation of the design. When the implementation is reviewed the Service Implementation can be released into a formal QA process. The Deployment Process of an Artifact is covered in the dtgov-switchard demo.

That will enable the demo profile, which will configure the Maven distributionManagement to point to a local S-RAMP repository (http://localhost:8080/s-ramp-server/). Therefore you need to be running S-RAMP on port 8080 and deployed as the s-ramp-atom context.

The build should complete successfully.

At this point there should be a number of artifacts stored in the S-RAMP repository. You can verify that by deploying the "s-ramp-ui" project and then navigating to http://localhost:8080/s-ramp-ui (or the appropriate URL for you).

You should see the following artifacts in the S-RAMP repository:

  • project-requirements-<version>.jar
  • project-requirements-<version>.pom
  • Project-org.overlord.dtgov.demos.project.<version>

The requirements-doc.txt is shipped in the requirements-<version>.jar. Note that you can use other formats if you like. You may have expected the jar and the pom, but what created the Project-org.overlord.dtgov.demos.project.<version> artifact? In the dtgov-demos-project/pom.xml you may have noticed the following section:

      <name>S-RAMP Releases Repository</name>
      <name>S-RAMP Snapshots Repository</name>

This section is active when using the demo profile, and in it we specified an artifact grouping artifactGrouping=Project-${project.groupId}.${project.version}. During the upload this ArtifactGrouping artifact is created along with groupBy relationships to this parent artifacts. The dtgov.properties file defines the following :

governance.queries=/s-ramp/ext/ArtifactGrouping[xp2:matches(@name\, 'Project.*')]|overlord.demo.SimplifiedProjectLifeCycle|UpdateMetaDataUrl={governance.url}/rest/update/{name}/{value}/{uuid}

This starts a overlord.demo.SimplifiedProjectLifeCycle workflow when a ArtifactGrouping with a name that starts with Project lands in the repository. When the workflow is created you should see a new custom property on this artifact which should look like


If you where to delete this property then a new workflow will be started, and a new property will be recreated.

The upload of the requirements also triggered an AnalysisArtifactsComplete signal to the newly created workflow, to signal the workflow that the requirements docs are ready for review. This signal was triggered by upload of the project-requirements/pom.xml. Note that in this pom we have the following properties section


During a MavenPom upload all properties are extracted and added as custom properties, prefixed with maven.property.; so the signal property end up as maven.property.signal with value AnalysisArtifactsComplete. When DTGov discovers this signal property it looks up the accompanying workflow referenced in the Project* ApplicationGroup artifact signals this process instance. After sending the signal the name of the property changes to _maven.property.signal.sent. When the signal is caught by the workflow, it will classify the Project* ApplicationGroup artifact with the #BaInReview classification, and start a Business Analysis Review Meeting task. This task is assigned to the ba role. You can defined roles in the standalone/configuration/overlord-idp-roles.properties. These roles can be referenced in the human task definition as the groupId.

By default the standalone/configuration/overlord-idp-roles.properties looks like


The admin user has all roles. So when logged in as admin you can work on ALL tasks. For this example the ba, arch, and dev roles in use. More roles can be created as needed.

You can work on your tasks by navigating to http://localhost:8080/dtgov-ui#taskInbox. After you’ve reviewed the requirements documents with all stakeholders, you go here to Claim, Start and record the Pass/Fail verdict. For the Business Analysis Review Meeting task you will need the ba role. On a Fail the workflow records the fail and loops back so that a new version can be submitted. On a Pass the workflow records the pass and enters the waiting for architecture docs complete state.