The Workflow API

Documentation home

The API

Accessing the API

Descriptor objects

Using the API in the context of a form

Auditing information

Security and visibility

Error processing

Exception handling

Failed node enactment re-execution

Error recovery processes

 

See also: Workflow Management API Javadoc

 

Description

 

This section describes the runtime mechanism available for accessing the WfMS. This mechanism manifests itself as a Java Application Programming Interface (API) which is embodied as the Java interface WorkflowManagement which appears in the package com.ebasetech.api.workflow.

                                

The rest of this section shows how to use the Workflow API in the context of a workflow-aware application. The basic approach to using the API is to obtain access to the singleton WorkflowManager object which implements the API. All of the facilities defined by the API are available on this object.

 

The API

 

This section does not in itself provide detailed descriptions of the Workflow API. This is left for the javadoc generated documents which can be viewed here. What follows, therefore, shows the basic way of accessing and using the API but the large bulk of the detail remains in the javadoc documents.

 

Accessing the API

The WfMS provides an implementation of the WorkflowManagement API as the singleton class com.ebasetech.ufs.workflow.server.external.WorkflowManager. Users of the API can obtain access to the instance of this class by invoking the Instance() method that the class provides. Hence, all uses of the WfMS API will be preceded by some code like:

 

WorkflowManagement api = WorkflowManager.Instance();

 

// use the api object

 

Note that client applications should use the WorkflowManager object from the point of view of the WorkflowManagement interface. That is, the singleton object should be used as shown in the code snippet above. This will provide a user of the WfMS API with the maximum possible protection against future changes in the details of the API.

 

A Javascript script can access the WorkflowManagement API directly as follows, without the need for the preceding Java code:

 

var api = system.workflow.api;

 

// use the api object

 

Descriptor objects

In general, the API gives programmers access to the fundamental components of the workflow system internals including:

 

 

This is done by defining a number of descriptor classes, instances of which provide a remote reference into an internal object of the WfMS and which are passed in and out of the methods in the WfMS API. The descriptor classes implement interfaces that are nested within the WorkflowManagement interface and are:

 

1.      DecisionEnactmentDescriptor which describes the enactment of some decision in the enactment of a process

2.      FallibleEnactmentDescriptor which describes the enactment of some node within a process which can feasibly fail. Typically this is the enactment of some process node that contains a script

3.      InteractiveTaskEnactmentDescriptor which describes the enactment of some interactive task in the enactment of a process

4.      SystemTaskEnactmentDescriptor which describes the enactment of a system task within a process, such as a process node that sends an email.

5.      TaskEnactmentDescriptor which is the enactment of some system or interactive task in a process.

6.      JobDescriptor which describes the enactment of a process as a separate Job

7.      EscalatorEnactmentDescriptor which is the enactment of a particular escalator within a particular Job.

8.      PauseEnactmentDescriptor which describes the enactment of some pause node in the enactment of a process, such as waiting for a database update from an external system

 

Hence, if a programmer wished to cancel a particular job there could be some code like:

 

WorkflowManagement api = WorkflowManager.Instance();

 

List jobs = api.openedJobs(…);

WorkflowManagement.JobDescriptor job =

    (WorkflowManagement.JobDescriptor)jobs.get(0);

api.cancelJob(job, …);

 

In many cases it is likely that the accessing application will not have the ability to retain a complex Java object such as one of the descriptors. In these cases the API provides the ability to generate a unique string-valued handle for a descriptor that may be used in just the same way.

Hence, the previous code to cancel a job could be written as:

 

WorkflowManagement api = WorkflowManager.Instance();

 

List jobs = api.openedJobs(…);

WorkflowManagement.JobDescriptor job =

    (WorkflowManagement.JobDescriptor)jobs.get(0);

String jobHandle = job.getIdentifier()

api.cancelJob(jobHandle, …);

 

Using the API in the context of a form

 

Information on using the WfMS API in the context of an Ebase form can be found here.

 

Auditing information

 

In some situations a client application may wish to get additional information about the actions that have been carried out in the internals of the WfMS. This is facilitated by the latter recording audit information as a series of database records, each of which describes some important information.

 

The WfMS API provides access to the audit records by means of the getFilteredAuditRecords method that is available on the WorkflowManagement API. This method allows the user to define a filter for the set of audit objects that are needed. The method returns a list of Audit objects, each of which may be queried to determine useful information about a particular audit record.

 

Security and visibility

 

The methods available in the WfMS API have the capability of completely disrupting the sound behaviour of the workflow system. Consequently, some system of security is needed to ensure that only the correct users get access to the facilities of the API. The main bulk of the implementation of the desired security system is left to the user to implement by the implementation of a suitable local implementation of the SecurityHandler interface. This handler uses the “caller” security token (which is simplistically the name of the person invoking the api but could well be a non-spoofable local implementation instead.

 

This security token determines two things about the API:

 

  1. Whether the current user has access to the API method concerned. If this is not the case the API throws a WorkflowSecurityException  and the operation is aborted.
  2. Whether the current user has visibility of any returned objects. This means that even though an API call by a user fundamentally extracts a list of objects from the WfMS it might well be that only a subset of those is visible to the user. Hence, it is quite possible for an empty list to be returned, for example from the API methods that provide lists of the interactive tasks in the system.

 

Complete details of the way to implement security in a particular situation are contained in the customization section of this documentation.

 

Error processing

 

Use of the WfMS API allows a user to direct the behaviour of the system as a whole. Many aspects of this behaviour are concerned with error processing of one form or another and this section summarizes these.  This section describes at a high level the main aspects of such error processing. Again, complete details of some of the things described here are contained in the provided Javadoc information for the WfMS API.

 

Exception handling

The WfMS API is powerful and hence it is capable of accessing the underlying WfMS in such a way as to generate a wide variety of different exceptional conditions. Hence, each of the API methods is declared as being able to throw one of four different exceptions. The programmer must provide suitable exception handling functionality for each of these. The exceptions are:

 

  1. PersistenceException which is thrown in some situation where the WfMS’s underlying database accessing functionality has failed. The appearance of this exception indicates some deep underlying malaise.
  2. WorkflowManagementExceptionwhich is thrown in a wide variety of situations. The particular underlying cause is shown by the embedded cause exception.
  3. WorkflowSecurityException which indicates that the person invoking the api method does not have clearance to carry out that function. The behaviour and customization of the WfMS security model is described in another part of this documentation.
  4. ConcurrentUpdateException which is thrown in the situation where one member of a multi-processor server cluster is carrying out a similar, but conflicting, operation as another member of that cluster.

 

No systematic guidance can be given for these exceptions, but it should be noted that they all represent something that is important to a client application and should not just be ignored. However, the WfMS is a transactional application so when one exception does get thrown the state of the application and its underlying data sources will be returned to the previous (that is, before the last API operation) known good state.

 

Failed node enactment re-execution

Many of the node enactments that are carried out by the process of process enactment can feasibly fail. For example, the scripts that are defined as a component of the Decision parts of a process can be incorrectly written. When this happens the enactment is placed in the failed state and further enactment of that branch of the relevant Job cannot proceed.

 

In this case a client application may determine what failed enactments there are using the getFailedNodes method available in the API. As normal this returns a list of descriptor objects which may be used to populate a display of the problems in the current set of enactments.

 

In some cases it will be possible to resolve the issue that causes an enactment to fail and it can then be re-executed. This is provoked by use of the reexecute method of the API. Note that this action could well cause the enactment to fail again in which case the system will return to the previous state.

 

In some circumstances it may be necessary to just ignore a failed node and proceed in any case. In such a circumstance a client application can use the forceCompletion method to force the WfMS to just proceed with enactment of the job.

 

Error recovery processes

The final error management tool available to users of the WfMS is to define an error recovery process for a workflow process. An error recovery process is just a normal workflow process, except that the system itself will cause that process to be enacted should some node fail in the enactment of the original process.

 

The WfMS process designer provides facilities to allow the user to define which error recovery process, if any, to use.