Workflow Guide

Chapter 2 Basic Workflow Development

This chapter describes basic workflow development concepts and introduces the workflow client API. It has these topics:

About the development process

Analyze your business needs

In the design phase, you first need to determine what you want to automate in your business process. The design should be as detailed as possible, and involve business experts as well as application developers. Some of the issues you will likely address are:

What is the order of execution for business activities and what conditions determine the flow of work among them?
What documents need to be included in the process?
Who is responsible for each activity?
What activities can be executed without user intervention?

Create a workflow process

Using the Workflow Designer, you as application developer lay out the process graphically, creating activities and links and assigning users and properties where applicable. You then save the process as an XML file that can be executed by the workflow engine.

For more information, see Workflow Designer.

Define workflow users

Director workflow recognizes two kinds of authorized users:

Any valid user in your realm that is specifically identified by a workflow activity
Any valid role in your realm that is specifically identified by a workflow activity

For the most part, designing user access for workflow is the process of designing roles. Roles normally parallel activities. When designing your process, you identify the activities you require, design a user interface for the activity, and define a role with a list of authorized users.

For more information, see the chapter on role-based autorization in the User Management Guide.

Develop a workflow client

As application developer you use the workflow client API to create workitems and interact with the workflow process and the workflow engine. Workitems are containers for the data that will be worked on and can include documents and properties.

Workflow subsystem components

Before you start developing a workflow client you need to be familiar with the different parts of the Workflow subsystem:

Workflow component	Function or description
Workflow engine	Subsystem software that executes a workflow process and controls the queue process.
Workflow queue	Persists workitem data and mediates between workflow clients and the workflow engine. The queue is also responsible for monitoring automatic activities.
Process definition	An XML descriptor that represents activities and links that the workflow developer creates using the Workflow Designer.
Activities	Defines what work is executed at each step in the process. Activities are defined in the Workflow Designer, and there are two basic types: User activities: activites that require user intervention. They have associated workitems (see definition below) Automatic activities: unattended activities that execute without intervention by the client. The logic is provided by the application developer, as described in Customizing Activities and Links.
Workitems	Containers that are associated with user activities. Workitems can contain editable properties and documents, or pointers to documents.
Links	Defines the logical path between activities and the user addressee. Links are defined in the Workflow Designer.
Workflow client	The user interface with the Workflow subsystem provided by the application developer using the Workflow API. The client defines workitems and interacts with the workflow engine and queue.

For more information about how these components interact in an application, see How the client works.

About the workflow client

The workflow client implements classes in the wf.api and wf.client.api packages to interact with the Workflow subsystem. These are the interfaces you can use to develop the client:

Interface	Description
EbiWorkitemDelegate	Used by clients to interact with workitems. It provides methods for accessing workitem properties and associated documents, and for locking and unlocking workitems for users or user sessions.
EbiContext	Provides access to portal session information. This object is passed by several methods in the client API.
EbiQueueDelegate	Provides operations for accessing, forwarding, and reassigning queued workitems.
EbiWorkEngineDelegate	Provides methods for starting a process instance.

How the client works

The following diagram shows how the Workflow client API interacts with the Workflow subsystem:

wfAPIS

The application provides a mechanism for starting the workflow engine and the queue process.
The workflow client uses an EbiWorkflowEngineDelegate to start a new process instance.
The client uses EbiQueueDelgate to get a list of current workitems for the user.
The queue delegate gets an EbiWorkitemDelgate for processing each workitem in the queue and forwarding to the next activity until the process is completed.

Developing the client

This section describes some basic client development topics.

Workitem life cycle

For the most part, workflow client development involves handling workitems and associated documents. Here is a summary:

Somewhere in your Web application, a user initiates a new workflow process. This might be, for example, a Create New Document button in a Director component.
The client code calls a method on EbiWorkflowEngineDelegate to create a new process instance. The Workflow subsystem creates the process instance and automatically creates a new workitem. A process instance holds only one workitem.
If you have specified a starting document in the Workflow Designer, the subsystem adds it to the workitem. Typically, this document is some kind of template that your business logic populates with data specific to the individual work request. Although the document can be stored as string data in the workitem and persisted by the queue layer, typically the document is an URL to a document in the Content Management subsystem.
At the first activity in the process, you use an EbiWorkitemDelegate to do any of the following:
- Add more documents
- Add and set workitem properties, which are metadata about the workitem
- Add and set document properties, which are metadata about documents in the workitem
Repeat the Step 4 at any subsequent activity in the process. You can also delete documents and properties anytime.

Design options

You can use either Director portal components or JSP pages to develop the client. Director includes a set of JSP tags that you can use for JSP implementations.

The installed workflow core components provide the generic logic and user interface for starting a process and getting a list of workitems for a user.

For more information For an example of using the core components, see Sample Workflow Application.

Working with properties

Workitem properties can be defined for the workitem itself or for a document associated with a workitem. A workitem property might be an editable value on an HTML form. A document property in this context is part of the workitem but does not affect the physical document. In both cases, a workitem property must be defined as an.EbiProperty object that can be accessed from an EbiWorkitemDelegate.

Here is a partial list of com.sssw.wf.api.EbiProperty methods:

EbiProperty methods	Description
getPropertyName()	Returns the name of this property.
get/setPropertyType()	Accessor method for the property data type.
get/setPropertyValue()	Accessor methods for the property value.
isDocumentProperty()	Returns true if the property is defined for the associated workitem document.
isImmutable()	Returns false if the property can be edited.

Here is a partial list of com.sssw.wf.client.EbiWorkitemDelegate methods:

Property access methods	Description
createProperty()	Creates an EbiProperty
getAllProperties()	Returns a list of all workitem and all document properties.
getWorkitemProperties()	Returns a list of all workitem (non-document) properties
get/setProperty()	Gets/sets an EbiProperty for a workitem (non-document).
setDocumentProperty()	Sets an EbiProperty for a document
hasProperty()	Tests whether the workitem has the specified property.

Working with documents

A workflow document is an artifact that is accessed and modified by a workflow user or an automatic activity. The workitem acts as a container for documents.

A document can have either of two formats:

XML document This document is typically business-specific, such as a purchase order or insurance claim form. You can access an XML document by specifying the document itself (a DOM) or a pointer to the document. The pointer can be a String or an URL.
Non-XML document The basic form of this document is application specific, such as a document from a content management system.or a spreadsheet application. When accessing a non-XML document you must specify a pointer. When you add a non-XML document to a workitem using addDocument(), the pointer is stored in an XML proxy document. It is up to the application to know how to retrieve the document from the pointer.

Here is a list of document-related methods that you can access from an EbiWorkitemDelegate:

Document access methods	Description
add/removeDocument()	Adds or removes a document from the workitem.
lock/unlockDocument()	Locks or unlocks the document for editing. If you have multiple documents associated with a workitem, you would probably want to lock the document rather than the workitem itself.
updateDocument()	Updates changes to a document.

Binding activities to client types

The Workflow subsystem provides a mechanism for specifying different client types for workitems associated with workflow activities. For example, you might want the user interface for a particular workitem to be a spreadsheet application, a Java client, or some other application.

Activity policy descriptor

You specify clients in a descriptor called activity-policy.xml. This descriptor is used by the core WorkflowQueue component to determine what set of clients to use for a selected workitem. The schema is defined in activitypolicy.xsd, located in the installed library/WorkflowService/schema directory.

Example Here is the activity policy defined for three components used in the sample content management workflow application:

  <?xml version="1.0"?>
  <activitypolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="activitypolicy.xsd">
  	 <activity name="AssignContent">
  	 	 <client type="portal" uri="/main/comp/WorkflowAssign">Portal</client>
  	 </activity>
  	 <activity name="CreateContent">
  	 	 <client type="portal" uri="/main/comp/WorkflowCreate">Portal</client>
  	 </activity>
  	 <activity name="AuthorizeContent">
  	 	 <client type="portal" uri="/main/comp/WorkflowAuthorize">Portal</client>
  	 </activity>
  </activitypolicy>
  


 
Element
 
Description


 
name

 
Indicates the name of the activity as specified in the Workflow Designer.



 
client 

 
Indicates the client type and the URL for the application component or JSP page. The default client type is portal, which means the component will use Director portal services to render the client.
 
NOTE	  You can also specify default as the client type and provide an implementation. In addition, you can add a client tag under <activtypolicy> as a global default using the string default.

Element	Description
name	Indicates the name of the activity as specified in the Workflow Designer.
client	Indicates the client type and the URL for the application component or JSP page. The default client type is portal, which means the component will use Director portal services to render the client. NOTE You can also specify default as the client type and provide an implementation. In addition, you can add a client tag under <activtypolicy> as a global default using the string default.

Adding client types

If you want to provide a different client type, you can modify the activity policy file and add the new client type and associated URLs. The XSL of the WorkflowQueue core component (WorkflowQueueDefault.xsl) looks for portal as the client type and uses the associated URL as the link for the activity. To reference a different client type, modify the XSL for the queue component and the activity-policy client type accordingly.

NOTE The QueueComponent only supports direct URL references as an URI pointer, but it can be modified, or you can provide a custom queue client.

Accessing policy information

EbiWorkitemDelegate provides access to activity policy information. Here is a list of some of the methods:

Client info method	Description
getClientTypes()	Returns an array of all client types for this activity.
getClientURI()	Returns the URI of the specified client type.
getPolicyDefaultURI()	Returns the default policy client URI for this activity.
hasClientType()	Determines whether the activity includes the specified client type.
hasClientDefault()	Determines whether the activity has a default client type.

Reassigning workitems

The EbiWorkitemDelegate.reassign() method allows you to assign the current activity to another addressee's workitem queue. This is useful when you want to temporarily transfer work to another user. It has this declaration:

  public void reAssign(com.sssw.wf.client.EbiAddressee addressee,
                       EbiContext context)
                throws com.sssw.wf.exception.EboWorkitemException

The addressee can be any user defined in your server authentication realm, or a role described in your project resource set. For more information, see the API Reference.

Workflow Guide