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.1
3.3.2. Tomcat 7
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.3. Deploying Workflows
6.4. DTGov Supporting Services
6.5. Query Configuration
7. Governance Human Tasks
7.1. Overview
7.2. Using Human Tasks in a Workflow
7.3. Custom Task Forms
7.4. Customizing the Task API
8. Deployment Management
8.1. Overview
8.2. Invoking the Deployment Service
8.3. Configuring Deployment Targets
8.4. Undeployment
Bibliography

First, we recommend you download the following:

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

  1. Unpack S-RAMP distribution
  2. Copy the EAP download into the unpacked S-RAMP distro
  3. Copy the ModeShape distribution into the unpacked S-RAMP distro
  4. Run the S-RAMP installer
  5. Unpack the DTGov distribution
  6. Move the "target" folder from the S-RAMP distro to the unpacked DTGov distro
  7. Copy the EAP download into the unpacked DTGov distro
  8. Run the DTGov installer
  9. Start JBoss
  10. Populate the S-RAMP repository with DTGov seed data (ontology + workflow jar)

Some psuedo-shell code that might help

mkdir ~/overlord
cd ~/overlord
# Download JBoss EAP 6.1 (jboss-eap-6.1.0.zip)
#    From - http://www.jboss.org/jbossas/downloads
# Download the ModeShape EAP distro (modeshape-3.2.0.Final-jbosseap-61-dist.zip)
#    From - http://www.jboss.org/modeshape/downloads/downloads3-2-0-final.html
# Download S-RAMP distribution (s-ramp-0.3.0.Final.zip)
#    From - http://www.jboss.org/overlord/downloads/sramp
unzip s-ramp-0.3.0.Final.zip
cp jboss-eap-6.1.0.zip s-ramp-0.3.0.Final
cp modeshape-3.2.0.Final-jbosseap-61-dist.zip s-ramp-0.3.0.Final
cd s-ramp-0.3.0.Final
ant install
cd ..
mv s-ramp-0.3.0.Final/target dtgov-1.0.0.Final
cp jboss-eap-6.1.0.zip dtgov-1.0.0.Final
cd dtgov-1.0.0.Final
ant install
# Start JBoss (target/jboss-eap-6.1/bin/standalone.sh) - wait for startup to complete
ant seed
cd dtgov-data
mvn deploy

The dtgov.war and dtgov-ui.war services are deployed to the during the installation. The DTGov web UI (http://localhost:8080/dtgov-ui) is provided by dtgov-ui.war. You will see references to these services 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:

http://localhost:8080/dtgov-ui (admin/overlord)

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.1]$ pwd
/home/user/FSW6/jboss-eap-6.1
[user@host jboss-eap-6.1]$ ./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.1/standalone/configuration/application-users.properties'
Added user 'fitzuser' to file '/home/user/FSW6/jboss-eap-6.1/domain/configuration/application-users.properties'
Added user 'fitzuser' with roles overlorduser,admin.sramp to file '/home/user/FSW6/jboss-eap-6.1/standalone/configuration/application-roles.properties'
Added user 'fitzuser' with roles overlorduser,admin.sramp to file '/home/user/FSW6/jboss-eap-6.1/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

Tip

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
dtgov-ui.s-ramp.atom-api.endpoint
# Whether to validate the S-RAMP connection
dtgov-ui.s-ramp.atom-api.validating
# What kind of authentication to use (class name)
dtgov-ui.s-ramp.atom-api.authentication.provider
# Only used when the provider is basic auth
dtgov-ui.s-ramp.atom-api.authentication.basic.username
dtgov-ui.s-ramp.atom-api.authentication.basic.password
# Only used when the provider is SAML bearer token auth
dtgov-ui.s-ramp.atom-api.authentication.saml.issuer
dtgov-ui.s-ramp.atom-api.authentication.saml.service
dtgov-ui.s-ramp.atom-api.authentication.saml.sign-assertions
dtgov-ui.s-ramp.atom-api.authentication.saml.keystore
dtgov-ui.s-ramp.atom-api.authentication.saml.keystore-password
dtgov-ui.s-ramp.atom-api.authentication.saml.key-alias
dtgov-ui.s-ramp.atom-api.authentication.saml.key-password

# Task API connection endpoint
dtgov-ui.task-api.endpoint
# Implementation of a task client
dtgov-ui.task-client.class
# Authentication to use when invoking the task API
dtgov-ui.task-api.authentication.provider
# Only used when using basic auth
dtgov-ui.task-api.authentication.basic.username
dtgov-ui.task-api.authentication.basic.password
# Only used when using saml bearer token auth
dtgov-ui.task-api.authentication.saml.issuer
dtgov-ui.task-api.authentication.saml.service
dtgov-ui.task-api.authentication.saml.sign-assertions
dtgov-ui.task-api.authentication.saml.keystore
dtgov-ui.task-api.authentication.saml.keystore-password
dtgov-ui.task-api.authentication.saml.key-alias
dtgov-ui.task-api.authentication.saml.key-password

# Deployment lifecycle base classifier
dtgov-ui.deployment-lifecycle.classifiers.base
dtgov-ui.deployment-lifecycle.classifiers.initial
# Classifier to use when querying for all deployments
dtgov-ui.deployment-lifecycle.classifiers.all
dtgov-ui.deployment-lifecycle.classifiers.in-progress
# 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}
dtgov-ui.deployment-lifecycle.classifiers.stage
# 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}
dtgov-ui.deployment-lifecycle.types

# S-RAMP UI integration properties
dtgov-ui.s-ramp-browser.url-base

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

org.overlord.sramp.client.auth.AuthenticationProvider

sramp.repo.auth.provider

dtgov.properties

DTGov :: Governance Services → S-RAMP

org.overlord.sramp.client.auth.AuthenticationProvider

sramp.repo.auth.provider

dtgov.properties

DTGov UI :: S-RAMP Invokes

org.overlord.sramp.client.auth.AuthenticationProvider

dtgov-ui.s-ramp.atom-api.authentication.provider

dtgov-ui.properties

DTGov UI :: Task Inbox Invokes

org.overlord.dtgov.taskclient.auth.AuthenticationProvider

dtgov-ui.task-api.authentication.provider

dtgov-ui.properties

Example

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.
    @Override
    public void provideAuthentication(HttpRequest request) {
      // Do custom authentication now.
    }
}
  1. Configure the provider in dtgov-ui.properties
dtgov-ui.task-api.authentication.provider=org.example.auth.CustomAuthenticationProvider
# Optional custom configuration properties
dtgov-ui.task-api.authentication.custom.property1=some-value
dtgov-ui.task-api.authentication.custom.property2=some-value
  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
sramp.repo.url
sramp.repo.auth.provider
sramp.repo.user
sramp.repo.password
sramp.repo.validating

DTGov User Interface Configuration

# S-RAMP API connection endpoint
dtgov-ui.s-ramp.atom-api.endpoint
dtgov-ui.s-ramp.atom-api.authentication.provider
dtgov-ui.s-ramp.atom-api.authentication.saml.issuer
dtgov-ui.s-ramp.atom-api.authentication.saml.service
dtgov-ui.s-ramp.atom-api.authentication.saml.sign-assertions
dtgov-ui.s-ramp.atom-api.authentication.saml.keystore
dtgov-ui.s-ramp.atom-api.authentication.saml.keystore-password
dtgov-ui.s-ramp.atom-api.authentication.saml.key-alias
dtgov-ui.s-ramp.atom-api.authentication.saml.key-password
dtgov-ui.s-ramp.atom-api.validating
dtgov-ui.s-ramp-browser.url-base

overlord-apps/*-overlordapp.properties Configuration

overlordapp.href

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.app-id=s-ramp-ui
overlordapp.href=http://sramp.example.org:8080/s-ramp-ui/
overlordapp.label=Repository
overlordapp.primary-brand=JBoss Overlord
overlordapp.secondary-brand=S-RAMP Repository

Example: dtgov-overlordapp.properties

overlordapp.app-id=dtgov
overlordapp.href=http://dtgov.example.org:8080/dtgov-ui/
overlordapp.label=Design Time
overlordapp.primary-brand=JBoss Overlord
overlordapp.secondary-brand=Governance

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

sramp.repo.url=http://sramp.example.org:8080/s-ramp-server/
sramp.repo.auth.provider=org.overlord.sramp.governance.auth.BasicAuthenticationProvider
sramp.repo.user=dtgov
sramp.repo.password=DTG_PASSWORD
sramp.repo.validating=true

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

dtgov-ui.s-ramp.atom-api.endpoint=http://sramp.example.org:8080/s-ramp-server
dtgov-ui.s-ramp.atom-api.authentication.provider=org.overlord.dtgov.ui.server.services.sramp.SAMLBearerTokenAuthenticationProvider
dtgov-ui.s-ramp.atom-api.authentication.saml.issuer=/dtgov-ui
dtgov-ui.s-ramp.atom-api.authentication.saml.service=/s-ramp-server
dtgov-ui.s-ramp.atom-api.authentication.saml.sign-assertions=true
dtgov-ui.s-ramp.atom-api.authentication.saml.keystore=${sys:jboss.server.config.dir}/overlord-saml.keystore
dtgov-ui.s-ramp.atom-api.authentication.saml.keystore-password=KEYSTORE_PASSWORD
dtgov-ui.s-ramp.atom-api.authentication.saml.key-alias=overlord
dtgov-ui.s-ramp.atom-api.authentication.saml.key-password=KEY_PASSWORD
dtgov-ui.s-ramp.atom-api.validating=true

dtgov-ui.s-ramp-browser.url-base=http://sramp.example.org:8080/s-ramp-ui

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

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

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

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:

<form>
  <fieldset>
    <label>Notification</label>
    <p>
      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.
    </p>
    <label>Validation</label>
    <label class="radio">
      <input type="radio" name="Status" value="pass"></input>
      Schema accepted as valid
    </label>
    <label class="radio">
      <input type="radio" name="Status" value="fail"></input>
      Schema <em>not</em> accepted
    </label>
  </fieldset>
</form>

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:

<taskName>-taskform.xml

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:incoming>bpmn20:SequenceFlow_9</bpmn2:incoming>
  <bpmn2:outgoing>bpmn20:SequenceFlow_10</bpmn2:outgoing>
  <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:dataInputRefs>_DataInput_47</bpmn2:dataInputRefs>
      <bpmn2:dataInputRefs>_DataInput_48</bpmn2:dataInputRefs>
      <bpmn2:dataInputRefs>_DataInput_49</bpmn2:dataInputRefs>
      <bpmn2:dataInputRefs>_DataInput_50</bpmn2:dataInputRefs>
    </bpmn2:inputSet>
  </bpmn2:ioSpecification>
  <bpmn2:dataInputAssociation id="_DataInputAssociation_47">
    <bpmn2:sourceRef>DeploymentUrl</bpmn2:sourceRef>
    <bpmn2:targetRef>_DataInput_47</bpmn2:targetRef>
  </bpmn2:dataInputAssociation>
  <bpmn2:dataInputAssociation id="_DataInputAssociation_48">
    <bpmn2:targetRef>_DataInput_48</bpmn2:targetRef>
    <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:assignment>
  </bpmn2:dataInputAssociation>
  <bpmn2:dataInputAssociation id="_DataInputAssociation_49">
    <bpmn2:sourceRef>ArtifactUuid</bpmn2:sourceRef>
    <bpmn2:targetRef>_DataInput_49</bpmn2:targetRef>
  </bpmn2:dataInputAssociation>
  <bpmn2:dataInputAssociation id="_DataInputAssociation_50">
    <bpmn2:targetRef>_DataInput_50</bpmn2:targetRef>
    <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>
    </bpmn2:assignment>
  </bpmn2:dataInputAssociation>
</bpmn2:task>

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=stage|http://www.jboss.org/overlord/deployment-status.owl#InStage|copy|/tmp/stage/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|Classifier|DeploymentType|TypeSpecificParams

  • 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)
governance.targets=rhq|rhquser::rhqpassword::rhqbaseUrl
# Deploy using the JBoss AS CLI  (username, password, host, port)
governance.targets=as_cli|asuser::aspassword::ashost::asport
# Deploy to a Maven Repository (maven-url, is-release-enabled, is-snapshot-enabled
governance.targets=maven|scp://m2.example.com/m2/snapshot-repository::false::true