IBM Security
© Copyright International Business Machines
Corporation 2003, 2012. All rights reserved.
US Government Users
Restricted Rights – Use, duplication or disclosure restricted by
GSA ADP Schedule Contract with IBM Corp.
Purpose of this Document
Overview
API
Description
API Example
The Identity Governance provisioning platform is designed with extensibility as a primary goal. Many of the architectural components have been built using frameworks that can make use of custom extensions. The workflow module is an example of an extensible component. In order for customers to build extensions to be called from within a running workflow environment, an Application Programming Interface (API) for the workflow component has been designed to query and even make modifications to this environment. This document describes that API.
The Workflow API has been developed to provide the developers of custom extensions to Identity Governance a portable and backwards-compatible interface to the workflow environment. This interface is most beneficial when building custom code that can be called from a workflow process as a custom Java application or a JavaScript function (see the JavaScript API for more details). This custom code can then perform special business logic, query external data stores, or even integrate with other workflow engines.
The API consists of a set of java classes that abstract the more commonly used concepts of the workflow environment, such as processes, activities, and relevant data. The classes that make up this API are the same classes the platform uses for its out-of-the-box feature set. A note about security: these classes communicate directly with the workflow engine without authenticating the caller. Clients of this API will be assumed to have an appropriate level of trust. The API is not intended to be used by external un-trusted clients, but to be used within the flow of the provisioning platform’s business logic. The easiest way to deploy client code within the platform’s environment is to have the platform call the code from its published workflow extensions, such as a Java Application activity or a JavaScript activity.
The Workflow API consists of a set of classes that represent the more commonly used concepts of the workflow environment. All of these classes can be found in the com.ibm.itim.workflow.model package and its sub-packages.
The UML class diagram in figure 1 below illustrates the primary objects available in the API and their relationships. The primary object is the WorkflowProcess. A WorkflowProcess is parameterized by a set of RelevantDataItems and is implemented by a set of Activities. If an Activity is manual and requires the participation of a Resource, and Assignment is created to represent the task and fulfill the relationship. The most typical type of Resource is the HumanResource. There are several more objects available in the API that are not shown here. Please see the accompanying API Reference Document for more details on the individual objects.
Figrue
1: Primary Workflow Class Diagram
There is a consistent framework implemented in this API for querying and operating on workflow objects. This framework is centered on an entity class. An entity class is a composite class that holds a reference to a value class that holds the defining attribute information for the entity, and provides access to other related entities. The attribute information is cached for the life of the entity, however, every time a relationship is evaluated, the entity, or entities, that participate in that relationship will be loaded from the data store. For example, the name of a workflow process is cached within the WorkflowProcess entity class, but when the client requests the activities of the process, the activities will be retrieved from the data store and represented as Activity entities.
The following method uses the Workflow API to print the audit trail of a specified process. It organizes the audit trail by activity.
public static void printAuditTrail(long processId) {
try {
// Retrieve the process information
WorkflowProcessEntity process = new ProcessManager()
.getProcess(processId);
// Retrieve activities
Collection activities = process.getActivities();
Iterator iter = activities.iterator();
// Iterate over all activities and obtain audit trail
while (iter.hasNext()) {
ActivityEntity activity = (ActivityEntity) iter.next();
System.out.println(activity.getValueObject().getId());
List auditTrail = activity.getHistory();
Iterator auditIter = auditTrail.iterator();
// Iterate over all audit records and print
while (auditIter.hasNext()) {
EventAudit record = (EventAudit) auditIter.next();
System.out.println(record.getTimeStamp() + ": "
+ record.getEventType());
}
System.out.println();
}
} catch (WorkflowException ex) {
System.err.println("Workflow Exception: " + ex.toString());
}
}