Governance services

The System Governance toolkit provides templates and services that you can use in IBM Process Designer to create or customize a governance process.

Introduction

During IBM Business Process Manager installation, the System Governance toolkit (TWSYSG) is imported into the Process Center repository. Each governance process that you create must include a dependency on the System Governance toolkit. The toolkit provides the machinery required to build a governance process. The toolkit has integration services for installing process application snapshots and setting snapshot status.

You cannot edit or change the artifacts in the System Governance toolkit, but you can open the toolkit and view the artifacts within it.

Templates

The System Governance toolkit provides two templates, the Installation Requested template and the Snapshot Status Change template. Each of these templates is a business process definition (BPD) that you can adapt to the needs of your particular organization. Each of these templates is associated with a corresponding governance event. Your governance processes in Process Center must be built from one of these templates to take advantage of the governance services.

Installation Requested template: Use this template as a base to create a customized governance process that will replace the default Installation Requested BPD, which merely calls the installation service from the toolkit. The Installation Requested template has the ProcessAppInstallationRequest variable (of type ProcessAppInstallation).
Snapshot Status Change template: Use this template as a base to create a customized governance process that will replace the default Snapshot Status Change BPD, which has no activities. The Snapshot status change template has the SnapshotStatusRequest variable (of type SnapshotStatus).

Installation services

The System Governance toolkit supplies the following integration services for installation governance, all of which only run locally on Process Center. If you are using these services to install a snapshot, cancel an installation, or set installation status, the installation request must be initiated in the Process Center. See the sections that follow for more details.

Install Snapshot: Installs the snapshot on the specified process server.
Cancel Snapshot Installation: Cancels the installation request that is in progress (that is, waiting for approval). After the installation has started, the cancel request is ignored.
Get All Process Servers: Returns an array of process servers registered with Process Center.
Set Installation Status: Sets the installation status during long-running installations. Define the installation status messages that you want to use in the governance process.
Get Installation Status: Gets the installation status during long-running installations.

If an installation attempt fails, call the Cancel Snapshot Installation service to clear the status in Process Center. The only other way to clear the failure is to reset the governance process for the process application to the system default process. The governance business process definition (BPD) that called the Install Snapshot service should have all the data that is available from the failure already and can send that information in an email or log it. For failures that occurred because of an error in the process application, you might want to leave that status as a failure so no one tries to install that version again.

Install Snapshot

Input: processAppInstallation
Input: processAppInstallationRequest is used in the default Installation Requested BPD.
Output: installResponse, which is used to determine if the installation succeeded and if a failure is recoverable.
Implementation: Calls Java API for installation.

This service can fail to install a snapshot for a number of reasons. The installation request produces a return value that indicates if an error occurred and if the error is recoverable.

Cancel Snapshot Installation

Input: installRequest (processAppInstallation)
Implementation: Calls Java API for installation.

This service can fail under the following circumstances:

The Cancel Snapshot Installation service takes the processAppInstallation object as an input and uses various IDs set on processAppInstallation during processing. Those IDs must not be null or zero length and must be the same IDs that were received by the processAppInstallation object when the snapshot installation request was made.
If cancel is called after installation has started, the cancel request is ignored.
If cancel is called multiple times for the same installation request, all calls after the first call are ignored, because the installation request is already canceled.
If cancel is called against a process application for which governance is not enabled, the cancel request is ignored.
If there is not an active installation request for the snapshot and process server combination, the cancel request cannot succeed.
If the snapshot or process server is not properly identified, it cannot be found in Process Center.

Get All Process Servers

Output: processServers (processServers) provides a list of available process servers.
Implementation: Calls Java API for the list.

Set Installation Status

Use this service to update the installation status while an installation request is waiting for approval. When this service is called, the status updates immediately, without waiting for the current status or the installation to complete.

This service takes the following inputs:

processServerID (String)
snapshotID (String)
status (String) must be between 1 and 64 characters.
description (String) is optional; the length must be between 0 and 250 characters.

Implementation: Calls Java API to set the installation status.

This service can fail under the following circumstances:

If governance is not enabled, you cannot use this service.
If no installation request for that snapshot and process server combination exists, no status can be provided. That is, an installation request must be open and active.
The Set Installation Status service cannot be called after the Install Snapshot service has completed. The Install Snapshot request changes the status, and when the installation is complete, all status values disappear.
If the installation fails before this service is called, no status is provided.
If the snapshot or process server is not properly identified, it cannot be found in Process Center.

Get Installation Status

Input: processServerID (String)
Input: snapshotID (String)
Output: status (String) provides predefined status messages if custom messages are not provided through Set Installation Status.
Implementation: Calls Java API to set the installation status.

Snapshot status services

The System Governance toolkit supplies the following integration services for tracking snapshot status, all of which only run locally on Process Center. You can use the next three services with both process applications and toolkits. You can use snapshot status services with the governance process or independently of the governance process. The snapshot status events are always active, whether they are being used or not.

Get snapshot status: Returns the status of a snapshot.
Get snapshot statuses: Returns a list of strings containing the statuses that are used for snapshots. The list contains default values defined in the product and any custom values that were added through the governance process and are currently being used in the snapshot.
Set snapshot status: Sets the snapshot to the specified status. If the status string that is specified does not already exist, the API creates a new status value using that string.

Get Snapshot Status

Input: snapshotID (String)
Output: status (String)
Implementation: Calls Java API for the status.

Get Snapshot Statuses

Output: statuses (String) (List)
Implementation: Calls Java API for the list of statuses.

Set Snapshot Status

Input: status (String) Extension of string. Length must be between 1 and 50 characters.
Input: snapshotID (String)
Implementation: Calls Java API for setting the status.