Workflow Administration

This chapter describes how to use the Workflow administration tools and features. It has these sections:

Using the workflow administration portlets

The exteNd Director install includes two workflow administration portlets for managing the engine, queue, and runtime processes:

Engine and Queue Administration Console (WorkflowEngineAdmin)
Workflow Administration Client (WorkflowAdminClient)

Workflow administrators can access these portlets from the Director Administration Console (DAC).

For more information, see the chapter about the Director Administration Console in Developing exteNd Director Applications.

Engine and Queue Administration Console

wfAdminComp1

The engine and queue administration console provides the following functionality:

Start, suspend, or shut down the workflow queue
Start, suspend, or shut down the workflow engine
Start, suspend, or shut down both

Start functions Start the selected operation. This option starts an operation from scratch, resumes a suspended operation, or restarts an operation that was shut down.

Suspend functions Suspend the specified operation. Any messages sent to the engine or queue are stored but not executed until you select Start.

Shutdown functions Shut down the specified operation. Any messages sent to the engine or queue during the shutdown phase are lost.

NOTE: You cannot shut down the engine or the queue if it is in the suspended state. In other words, the engine or queue must be running in order for the shutdown function to work.

Workflow Administration Client

wfAdminComp2

This portlet allows you to manipulate the execution of a process instance by allowing you to:

See lists of running, suspended, and finished process instances
See a list of the activities and their states in a selected process instance
Suspend or resume a process instance
Suspend or resume an activity in a process instance
Terminate a process instance

Process functions

Process functions operate on all workitems associated with the process, unless that work is already displayed in a user's queue. In this case, workitems are not affected by suspending or resuming either processes or activities. Essentially, the user owns this work, and no existing functions (apart from locking) can prevent the user from updating and forwarding this work.

Suspending a process Suspending a process tells the Workflow subsystem that no updates should be made to workitems executing that process. Resuming a process returns it to the open state. The effect of suspending and resuming is apparent only when a user forwards work from one activity to another.

For example, assume there are two work queues, workqueue-A and workqueue-B. Also assume that workitem-1 is displayed in workqueue-A, and a forward on workitem-1 would normally result in the work appearing in workqueue-B.

If the workflow process currently being executed by workitem-1 is suspended (by someone selecting the Suspend Process button on the Process Administration Console), a forward on workitem-1 would result in the work disappearing from workqueue-A but not appearing in workqueue-B.

Resuming a process Resuming a process returns it to its original state. Continuing with the same example, assume the workflow process is resumed (by selecting the Resume Process button on the Process Administration Console). A refresh of workqueue-B will reveal workitem-1, ready for updating and forwarding by the user.

Terminating a process Terminating a process tells the Workflow subsystem to remove the process instance and its associated activities from the engine queue process. When a process is terminated, it cannot be recovered.

Activity functions

Suspending and resuming activities is similar to suspending and resuming processes, but enables more precision. An activity can be in one of the following states:

This state	Means the workitem
Open	Is not yet running and has not been suspended
Completed	Has been completed and forwarded to the next activity; cannot be suspended
Running	Is active and cannot be suspended
Suspended	Has been suspended; resuming the activity will reopen the workitem

Suspending an activity Suspending an activity tells the Workflow subsystem not to forward work to this activity in this process. Only open activities may be suspended; attempting to suspend a running or completed activity will have no effect. Other combinations may also be ignored (such as attempting to suspend a process or activity that is already suspended).

IMPORTANT: Java activities cannot be suspended, so you cannot access this type of activity using the workflow administration client portlet or the administration APIs.

Continuing with the example from the preceding section, assume there is an additional work queue (workqueue-C) but that workitem-1 is currently displayed in workqueue-A as before. Further assume that a forward from workqueue-B would result in the work appearing in workqueue-C (giving a simple A-B-C queue sequence).

If the workflow activity for workqueue-C is suspended (by someone selecting the Suspend Activity button), then a forward on workitem-1 (currently in workqueue-A) would result in the work showing up in workqueue-B, as expected. However, a forward from workqueue-B would not result in workitem-1 showing up in workqueue-C, since the associated activity is currently suspended.

Resuming an activity Now assume that the activity for workqueue-C is resumed (by someone selecting the Resume Activity button). A refresh of workqueue-C will then reveal workitem-1, ready for updating and forwarding by the user.

Auditing runtime processes

The Workflow API provides the EbiAuditDelegate.getAuditInfo() method for getting audit information about workflow processes, activities, workitems, and workitem properties. Here is the method declaration:

  public Document getAuditInfo(
  	 String processId, String runNumber, String activityName, Date startDate, Date endDate) 
  throws com.sssw.wf.client.EboAuditLoggerException

The DTD for the return document is available in your exteNd Director project directory at library/WorkflowService/DTD/workflow-auditlist.dtd.

NOTE: All parameter values are optional. To return all information, specify null for the parameter.

Generating runtime exception reports

The Workflow API includes exception-handling classes for the Workflow subsystem portlets, including EboEngineException, EboQueueException, and EboWorkitemException. By default, exception messages are written out to the server console. But you can have the messages sent via e-mail to a specified user. The setting for this option is in config.xml.

Procedure To configure exception messages to be sent to an administrator:

Outside exteNd Director, open the following file:

  My_Project/library/WorkflowService/WorkflowService-conf/config.xml

Uncomment the following lines:

   <!--
  	 <property>
  	 	 <key>WorkflowService/administrator-host</key>
  	 	 <value>SomeHost</value>
  	 </property>
  	 <property>
  	 	 <key>WorkflowService/administrator-address</key>
  	 	 <value>SomeAddress</value>
  	 </property>
  	 -->

NOTE: After you uncomment the properties, you can access them in the XML Editor in exteNd Director.

Set the two properties to a valid user or admin group with a valid e-mail address. For example:

  <property>
  	 	 <key>WorkflowService/administrator-host</key>
  	 	 <value>SMPT mail server hostname</value>
  	 </property>
  	 <property>
  	 	 <key>WorkflowService/administrator-address</key>
  	 	 <value>admin@addresss.com</value>
  	 </property>

Save the file.