The Workflow API
See also: Workflow Management API Javadoc
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.
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.
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
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, …);
Information on using the WfMS API in the context of an Ebase
form can be found here.
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.
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:
Complete details of the way to implement security in a
particular situation are contained in the customization
section of this documentation.
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.
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:
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.
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.
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.