GuideConfiguring

Configuring DTGov

Overview

DTGov has two configurations that can be modified to suit a particular deployment and business. Specifically, the back-end DTGov system (dtgov.war) has a configuration file as does the User Interface (dtgov-ui.war). This chapter describes these two configuration files so that users can configure DTGov for their particular deployment environment and organization’s unique business processes.

Back-End Configuration

The configuration of the back-end system can be modified by making changes to an external configuration file found in the application server’s configuration directory. In JBoss EAP by default the configuration file can be found here:

jboss-eap/standalone/configuration/dtgov.properties

If the file does not exist it can be created and will be picked up by the DTGov app during startup. The location of this file can be overridden by setting the following Java System Property to be the full path to a properties file anywhere on the server’s file system:

governance.file.name

For example, this system property could be configured by adding the following to the script that starts up your application server:

-Dgovernance.file.name=/home/jdoe/config/overlord/dtgov/dtgov.properties

The dtgov.properties configuration file is used to control a number of settings, listed and described in the following section.

Back-End Configuration (EAP)

When running in JBoss EAP this same configuration information is stored in the JBOSS/standalone/configuration/standalone.xml file under the urn:jboss:domain:overlord-configuration:1.0 subsystem. For example:

    <subsystem xmlns="urn:jboss:domain:overlord-configuration:1.0">
      <configurations>
        <oc:configuration xmlns:oc="urn:jboss:domain:overlord-configuration:1.0" name="dtgov">
          <oc:properties>
            <oc:property name="sramp.repo.url" value="${overlord.baseUrl}/s-ramp-server" />
            <oc:property name="governance.url" value="${overlord.baseUrl}/dtgov" />
            <oc:property name="dtgov.ui.url" value="${overlord.baseUrl}/dtgov-ui" />
            <oc:property name="governance.query.interval" value="20000" />
            <oc:property name="dtgov.workflows.group" value="org.overlord.dtgov" />
            <oc:property name="dtgov.workflows.name" value="dtgov-workflows" />
            <oc:property name="dtgov.workflows.package" value="SRAMPPackage" />
            <oc:property name="dtgov.workflows.version" value="1.3.0-SNAPSHOT" />
            <oc:property name="governance.bpm.user" value="dtgovworkflow" />
            <oc:property name="governance.bpm.password" value="${vault:VAULT::dtgov::dtgovworkflow.password::1}" />
            <oc:property name="sramp.repo.user" value="dtgovworkflow" />
            <oc:property name="sramp.repo.password" value="${vault:VAULT::dtgov::dtgovworkflow.password::1}" />
            <oc:property name="governance.user" value="dtgovworkflow" />
            <oc:property name="governance.password" value="${vault:VAULT::dtgov::dtgovworkflow.password::1}" />
          </oc:properties>
        </oc:configuration>
      </configurations>
    </subsystem>

All of the same properties as described above are applicable to EAP - they are simply configured in a slightly different location.

Back-End Configuration Properties

# S-RAMP Connection details
sramp.repo.url
sramp.repo.auth.provider
sramp.repo.user
sramp.repo.password
sramp.repo.validating
sramp.repo.auth.saml.issuer
sramp.repo.auth.saml.service

# Location of the DTGov WAR
governance.url
# Frequency with which to poll S-RAMP for query matches
governance.query.interval
# Location in JNDI of the email service
governance.jndi.email.reference
# "From" information to use when sending email (domain and address)
governance.email.domain
governance.email.from

# JNDI location of the User Transaction
governance.jndi.userTx.reference

# RHQ connection info
rhq.rest.user
rhq.rest.password
rhq.base.url

# BPM connection info
governance.bpm.user
governance.bpm.password
governance.bpm.url

# BASIC auth user used to invoke DTGov provided services
governance.user
governance.password

# Deployment targets configured for the DTGov deployment service
governance.targets

# Location of the DTGov UI
dtgov.ui.url

# S-RAMP
s-ramp-wagon
dtgov.s-ramp-wagon.snapshots
dtgov.s-ramp-wagon.releases

# DTGov Workflow maven info
dtgov.workflows.group
dtgov.workflows.name
dtgov.workflows.version
dtgov.workflows.package

In particular, the governance.targets and governance.queries configuration properties bear additional explanation. Please see the Governance Workflows chapter for more information on how to use these properties to configure the DTGov Deployment Service and the Governance Workflow Queries, respectively.

User Interface (UI) Configuration

The DTGov user interface can also be configured for a specific deployment and business environment. The configuration of the UI can be modified by making changes to an external configuration file found in the application server’s configuration directory. In JBoss EAP the configuration file can be found here:

jboss-eap/standalone/configuration/dtgov-ui.properties

The location of this file can be overridden by setting the following system property to be the full path to a properties file anywhere on the server’s file system:

dtgov-ui.config.file.name

This configuration file is used to control a number of settings, listed and described in the following section.

User Interface (UI) Configuration (EAP)

As mentioned above, when running in JBoss EAP the configuration properties are stored in the standalone.xml file. See the section Back-End Configuration (EAP) above. The UI properties are stored in a section named dtgov-ui:

    <subsystem xmlns="urn:jboss:domain:overlord-configuration:1.0">
      <configurations>
        <oc:configuration xmlns:oc="urn:jboss:domain:overlord-configuration:1.0" name="dtgov-ui">
          <oc:properties>
            <!-- Below is not the full list of properties needed - it is imply illustrative of the format -->
            <oc:property name="dtgov-ui.workflows.group" value="org.overlord.dtgov" />
            <oc:property name="dtgov-ui.workflows.name" value="dtgov-workflows" />
            <oc:property name="dtgov-ui.workflows.version" value="1.3.0-SNAPSHOT" />
          </oc:properties>
        </oc:configuration>
      </configurations>
    </subsystem>

UI Configuration Properties

# 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

# Dtgov API related properties
dtgov-ui.dtgov-api.endpoint
dtgov-ui.dtgov-client.class
dtgov-ui.dtgov-api.authentication.provider
# Only used when using saml bearer token auth
dtgov-ui.dtgov-api.authentication.saml.issuer
dtgov-ui.dtgov-api.authentication.saml.service
dtgov-ui.dtgov-api.authentication.saml.sign-assertions
dtgov-ui.dtgov-api.authentication.saml.keystore
dtgov-ui.dtgov-api.authentication.saml.keystore-password
dtgov-ui.dtgov-api.authentication.saml.key-alias
dtgov-ui.dtgov-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.

Configuring UI Deployment Stages

The DTGov user interface has a page that allows users to see a list of all deployments being tracked. That page allows the user to filter the list of deployments based on the environments in which the deployment is…deployed. In other words, the UI page allows the user to show only the deployments that are currently deployed in, for example, the DEV environment. Since different organizations have different numbers and names for these environments, the actual filter options are configurable. An example will prove useful:

dtgov-ui.deployment-lifecycle.classifiers.stage.dev=Development:http://www.jboss.org/overlord/deployment-status.owl#InDev
dtgov-ui.deployment-lifecycle.classifiers.stage.qa=QA:http://www.jboss.org/overlord/deployment-status.owl#InQa
dtgov-ui.deployment-lifecycle.classifiers.stage.stage=Staging:http://www.jboss.org/overlord/deployment-status.owl#InStage
dtgov-ui.deployment-lifecycle.classifiers.stage.prod=Production:http://www.jboss.org/overlord/deployment-status.owl#InProd

If the above configuration is used (in the dtgov-ui.properties file) then the UI will show four possible environments that the user can use to filter deployments (dev, qa, stage, prod). The format for the value of each entry is:

Label : Classifier

The Label will be shown in the UI (in the filter drop-down) and the Classifier will be used when performing the S-RAMP query to retrieve the filtered list of deployments.

Configuring UI Deployment Types

The DTGov user interface’s deployment listing page also allows users to filter by the type of deployment (Java Web Application, SwitchYard Application, etc). Since different organizations will likely work with varying technologies, the Deployment Type filter is configurable. For example:

dtgov-ui.deployment-lifecycle.types.switchyard=SwitchYard Application:ext/SwitchYardApplication
dtgov-ui.deployment-lifecycle.types.jar=Java Archive:ext/JavaArchive
dtgov-ui.deployment-lifecycle.types.war=Java Web Application:ext/JavaWebApplication

In the above example, the user would be able to filter by SwitchYard Application, Java Archive, and Java Web Application. The format for each entry is:

Label : S-RAMP Artifact Type

The Label will be shown in the UI (in the filter drop-down) and the S-RAMP Artifact Type will be used when performing the S-RAMP query to retrieve the filtered list of deployments.

Note: the list of Deployment Types is also used in the Add Deployment dialog when adding a new deployment. In this case, the S-RAMP Artifact Type is used when adding the deployment to the repository.

This configuration works in conjuction with the Deployment Service described in the Deployment Management chapter of this guide. The classifiers specified when configuring Deployment Targets should be represented here.

Configuring Authentication

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:

Component	Provider Interface	Config Property	Config 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:

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

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

That’s it!

Contents

Getting Started
User Management
Introduction
Configuring
S-RAMP Integration
Governance Workflows
Notifications
Human Tasks
Managed Deployments
Project Management
Data Model

Readme

Provide feedback

Saved searches

Use saved searches to filter your results more quickly