Defining Workflow Templates

This section discusses concepts and tasks pertaining to defining and maintaining workflow templates, template definitions, workflow variables and nodes. It includes:

Overview of Template Definition Tasks

Defining a complete workflow template definition includes creating a template, creating a template definition, designing the flow, defining variables, specifying node properties, and, optionally, defining exception handlers. While defining workflows is an iterative process, which requires revision and refinement at each level, the following steps outline the recommended order in which you should perform these tasks when defining a new template definition:

Working with Templates

Figure 5-1 Workflow Templates and Workflow Template Definitions

Creating a Workflow Template

To create a workflow template:

Updating Template Properties

To update template properties:

Deleting a Template

When you delete a workflow template, the following occurs:

To delete a workflow template:

Working with Template Definitions

In the folder tree, a workflow template definition name consists of its effective and expiry dates and times. The effective and expiry dates and times represent the range of time within which the workflow template definition is available for instantiation, or run-time execution. Note that you may have multiple template definitions with the same effective and expiry dates.

To make a template definition available for instantiation, you must activate it first. At design time, you can activate as many template definitions as you want, with the only restriction being that you cannot activate template definitions with the same effective (starting) date.

The advantage of the effective and expiry feature is that it allows you to make workflow template definitions valid for exact periods of time, without having to manually inactivate and activate different template definitions over the course of the calendar year. For example, perhaps you have a cyclical business, which requires you to run a particular workflow template definition from January to March, followed by a second workflow template definition having different tasks or variables from April to June, followed by a third defined for July to September. Rather than having to manually inactivate one template definition and activate another for each quarterly period, you simply specify different effective and expiry dates, mark them all as active, and the server automatically selects the correct version when the workflow is instantiated.

On the other hand, although you can have multiple active template definitions, only one template definition can actually be instantiated at run time, which means that you should take care to design your effective and expiry dates in a rolling fashion, and avoid overlapping dates. If you have active template definitions with overlapping dates, for example, one from January to March, and another from February to April, the process engine will simply pick up the first one that it finds in the database, which is usually the first one to have been created at design time.

Creating a Workflow Template Definition

When you create a template definition, you specify its effective and expiry dates.

To create a workflow template definition:

In the workflow design area, a default workflow template definition is presented along with a toolbar containing drawing shapes used for defining the workflow template. The default workflow template definition contains three shapes: Start, Task, and Done.

Figure 5-4 Workflow Design Area

Opening an Existing Template Definition

Although you can view read-only properties for a template definition by right-clicking any of its folders in the folder tree and selecting Properties from the pop-up menu, you cannot modify a template definition unless it is opened. Once you open a definition, it is locked and can only be opened in read-only mode by another user.

To open an existing workflow template definition:

Note: You should not try to modify a template definition that has running instances, as this can cause unpredictable exceptions in those instances. If you want to make changes to such a template definition, you should do the following:

Saving and Closing a Template Definition

In the Studio folder tree, an asterisk (*) appears to the left of each workflow template definition that needs to be saved.

To save a template definition, do one of the following:

When you close a template definition, it is unlocked and available for use by another user.

To close a workflow template definition, do one of the following:

Updating, Labeling, and Activating a Template Definition

When you create a new template definition, it defaults to inactive status. Often template definitions that are currently in development are inactive to prevent premature invocation. However, before a workflow can be instantiated, or placed into the run-time environment, you must activate one of its template definitions.

To update the properties of a workflow template definition:

Copying a Workflow Template Definition

The Studio allows you to copy an existing workflow template definition within the same template. When this is done, all of the assigned workflow template definition properties are copied as well. This saves you time when you must create more than one workflow template definition with similar properties. The properties of the new workflow template definition can be modified as needed.

To copy an existing workflow template definition:

Printing a Template Definition

You can print workflow template definition diagrams from the Studio. There are two methods for invoking the print facility.

The Text tab contains information relevant to each workflow node, including action and node notes, as well as details on actions within tasks, events, decisions and done nodes, including sub-actions within actions.

The Graphics tab contains a diagram of the workflow template definition.

Figure 5-8 Print Workflow Graphics

In the Print dialog box, select the appropriate settings to print the workflow.

Deleting a Template Definition

When you delete a workflow template definition, the following occurs:

To delete a workflow template definition:

Working with Nodes

The following table lists workflow shapes, their node name, and purpose.

Adding, Arranging, and Connecting Nodes

To manipulate shapes in the design area, you can do the following:

Deleting a Node or Connection

To delete a node:

To delete a connection:

Workflow Design Guidelines and Tips

As you are adding, connecting and arranging shapes, you may wish to keep in mind the following design guidelines:

Working with Node Properties

Once you have placed node shapes into the workflow design area, you can begin specifying their properties. One of the first tasks you will want to do, for example, is to rename nodes to give them an easily recognizable view of the function they are to perform in the workflow. The following sections provide explanations and procedures for working with properties that are common to all types of nodes. For properties that are specific to each type of node, refer to the sections that discuss each node type.

To access node properties, do one of the following:

Renaming Nodes

To rename a node:

Specifying or Updating Successor Nodes

All node properties dialog boxes contain a Next tab which displays a list of all nodes in the current workflow. The next node in the flow is indicated by a check next to the node name. You can use this tab to specify the successor node (or nodes) to the current node or change the successor nodes defined in the design area. Selecting or deselecting check boxes on this tab automatically redraws the connection lines drawn in the design area.

Figure 5-9 Next Tab of Node Properties Dialog Boxes

All node properties dialog boxes contain a Notes text box that you can use to enter a comment about the node or actions contained in it. This is helpful for other users who access the same workflow and need to understand the workflow logic or design.

Figure 5-10 Notes Tab of Node Properties Dialog Box

Adding, Updating, Reordering, and Deleting Workflow Actions

All nodes, with the exception of Joins (AND and OR), allow you to add, update, reorder and delete actions within their properties dialog boxes.

Figure 5-11 Actions Tab of Node Properties Dialog Boxes

Copying Nodes

You can copy a shape representing a node within a workflow template definition and paste it into the current workflow template definition or into another open workflow template definition. Since any actions and properties that have been defined within the node are also copied, you can use the copying function to create reusable design patterns which may only require minor modifications.

Note: If you are copying nodes between template definitions, be sure that any variables referenced by the node and its actions have been created in the target template definition, and that other referenced objects, such as roles, users and business calendars, are defined for the organization with which the template is associated.

Any properties and actions that have been defined within the node are also copied.

To copy a node and its properties within and between template definitions:

Viewing Task and Event Usage

To see where a Task or Event node is used:

Working with Variables

Each workflow template definition can have a set of variables associated with it. Variables can hold values that are returned by business operations, that are extracted from XML documents, or that are set explicitly by workflow actions. Variables can also be used by the workflow for several other purposes, such as to evaluate a condition in a decision node, or to store the result of a response from the Worklist client application.

Not all workflow template definitions require variables. However, for those workflow template definitions containing processes that require variables, you can define these before you begin defining other workflow components such as node properties and actions, or add variables during the design process.

Workflow variables have a workflow-global scope. That is, a single variable is shared by all objects within a workflow template definition instance. Variables are, therefore, defined at the workflow template definition level in the folder tree and are referred to as workflow variables.

Variables can be of the following types:

Note: If a plug-in is defined for variable types, additional variable types may be available.

Additionally, for input parameters, you can specify whether or not they are mandatory. If the input parameter is mandatory, the workflow does not start until the value for the variable is received from the calling, or parent, workflow. If the value is not received, the workflow does not start, and an exception is thrown.

Creating a Variable

To create a variable:

Updating a Variable

To update an existing variable:

Viewing Variable Usage

To see where a variable is used within the workflow:

Deleting a Variable

To delete a variable:

Defining Node Properties

This section describes how to define node properties, according to each specific type of node:

Defining Start Properties

Every workflow has at least one start shape that indicates the beginning of the workflow. The first node after the start will be the first activated node of the workflow, which can be a Task, Decision, or Event node.

Note: If no Start node is specified, no node activation can occur in the workflow.

Start nodes can have four types of triggers:

Note: When you create a template definition, the default Start node is set to a manual start.

You can also specify more than one Start node, for various purposes, for example:

To define a Start node:

Defining a Timed Start Node

You can start a workflow at an exact time and date by specifying a start date expression. To start a workflow, you also need to specify the organization in which the workflow should be started.

You can also specify an interval at which the workflow will be restarted, such as every two days. In this case, an instance of the workflow will start every two days until the template expiry date. After the template expiry date, no additional workflows will be started.

Figure 5-17 Start Properties Dialog Box: Timed Option

Defining Event And Event-Triggered Start Properties

A workflow can be started, or nodes within a workflow triggered, by an event. An event is an asynchronous notification from another workflow or from an external source, such as another application. Start nodes can be defined as event-triggered, and Event nodes can only be triggered by an external event.

In an XML event type, the actual trigger is either the document type declaration (DOCTYPE) specified in the prolog of the XML message, or it is the root element of the XML message. You specify the DOCTYPE or root element with which you want to trigger the event or start the workflow in a Start or Event node's properties dialog box. The event is not triggered unless the DOCTYPE or root element specified in the node's properties dialog box matches that in the incoming XML message.

In addition to using the DOCTYPE or root element, you can further qualify an event with an event key and an event condition. These are described below.

Understanding Event Keys

An event key allows you to specify the contents or JMS header or property values of incoming XML messages that will trigger a Start or Event node. That is, rather than allowing all incoming XML documents with a particular DOCTYPE or root element to trigger the node, you can filter the instances of incoming XML messages according to specific values contained in the XML body or JMS header fields, so that only a particular message, or messages, containing those values can trigger the node in the running workflow.

An event key consists of two parts:

Using XML Content as an Event Key

As a simple example, imagine that you have regularly incoming XML messages that, among other things, report customer account information from an accounts receivable application. These messages contain the following elements, among other data:

Listing 5-1 Example Incoming XML Document

<account>	
	.
	.
	.
	<number>847365</number>
	<customer>John Doe</customer>
	<balance>
		<status>past due</status>
		<date_due>7-11-2001</date_due>
		<amount_due>5670.85</amount_due>
	</balance>
	<credit_limit>7500.00</credit_limit>
</account>

Let us say that you have a workflow that processes overdue accounts, so that only incoming documents with a balance status of "past due" (as opposed to "OK" or "pending", for example) should trigger the workflow. First, you specify that the root element of the incoming document must be <account> for the document to even be considered as a trigger for this workflow. Then, you create an event key to correspond to the value of past due. At run time, the event processor compares the value returned by the balance status element in the incoming XML document with the value specified in the Start node. If there is a match, the workflow is triggered.

Let us now look at how we would construct our key value and event key expressions in light of our example. For our Start node, our key value expression would consist of a constant (surrounded by quotation marks, as required by workflow expression syntax) as follows:

"past due"

The event key expression required to return this value from the XML document, that you specify in the event key configuration, is:

ToString(XPath("/account/balance/status/text()"))

For our Event node, our key value expression would consist of a variable (expressed by the dollar sign in workflow expression syntax) that we have created in the workflow, and whose value has presumably been set earlier by the running workflow instance:

$AccountNumber

Assuming that the account number is stored as a string in the workflow variable, the expression required in the event key configuration to return this value from the XML document is:

ToString(XPath("/account/number/text()"))

The following figure summarizes the event key mechanism for XML content.

Figure 5-18 Event Key Mechanism

You can also use the EventAttribute() function to retrieve specific values from JMS headers or properties. The mechanism functions exactly the same way as for an XML document, but rather than parsing the XML document for the target value, the value can be extracted from a JMS property.

For example, let us say the sending application uses a property field to indicate the country from which a message is originating, that we will call Country, and that you have different workflows that should be started according to the country of origin. Your event key expression would look like the following:

ToString(EventAttribute("Country"))

For a workflow that should only process information pertaining to Canada, the key value expression in your start node could be:

"Canada"

Now let us say that also contained in this message is a property called Province. Within your start node, you extract this information and store it in a variable for containing province names. Once the workflow is instantiated, you want to ensure that only messages coming in for that particular province are used to trigger another event instance in the workflow, say for example, to call a business operation that will calculate a sales tax value. In this case, you could create an event key for the province. The event key expression would be:

ToString(EventAttribute("Province"))

The key value expression would consist of the variable name:

$ProvinceName

Understanding Event Conditions

To even further qualify the trigger of an Event or Start node, you can specify a condition that must be evaluated. In this way, even if the event processor has identified an event key match, the event will still not be triggered unless the condition is met.

Note: Although you can use an event condition without an event key, this is not recommended. The event key mechanism provides significantly better performance than a simple event condition, as it stores the target value in memory and involves much less DOM parsing on the incoming XML document. You should only use an event condition as an additional filter, along with an event key, when you wish to further restrict the XML message instance that should trigger the event.

$Amount_Due > .75 * $Credit_Limit

You can also use XPath() and EventAttribute() functions in event conditions to directly extract content from XML or JMS header or property data and compare it with other data, including constants, variables or even other functions. To continue the country example, you could have an event that should only be fired if the country of origin is one that you specify. Imagining that the country information were embedded in an XML element, such as <country>, your condition would look like this:

ToString(XPath("/root_element/child_element/country/text()")) = "Canada"

If the country value were embedded in a JMS property called Country, your condition would look like this:

ToString(EventAttribute("Country")) = "Canada"

Initializing Variables from Event Data

Figure 5-19 Variables Tab of Start and Event Node Properties Dialog Boxes

Figure 5-20 Workflow Variable Assignment Dialog Box

Although you can use this feature in a Start node to initialize variables to constant values when the workflow starts, it is probably most useful for capturing incoming event data that is to be used to set multiple variable values. For example, if the node is to be triggered by an incoming XML document in a JMS message, you can use multiple expressions to initialize variables with values contained in the document, or specified by JMS header or property fields.

To update a variable value, you highlight the variable name in the list, and click Update to invoke the Workflow Variable Assignment dialog box.

To delete a variable assignment, you select the variable name in the list, and click Delete.

Defining Event-Triggered Start Properties

When you define an event-triggered start, you need to specify the organization in which the workflow should be started. You can specify the organization at design time or use an expression that determines the organization at run time, for example, by extracting the data specified in the incoming event message.

To define an event-triggered Start node:

Defining Event Properties

To define an Event node:

Defining Decision Properties

A workflow can use any number of decision. Each decision node contains a condition that is evaluated when a transition to that decision node occurs. The result is either True or False, with subsequent flow of control passed to different paths, according to the result.

Additionally, it is possible to specify actions to be executed on both a True and a False evaluation of the condition. Actions defined on the True and/or False tab are performed before nodes specified as targets of a true or false branch. They are also listed under True and False folders under Decision folders in the folder tree.

Figure 5-25 Decision Properties Dialog Box

Defining Task Properties

A task node represents the following:

Task nodes are the building blocks of a workflow and should ideally represent a single operation within the flow, although this may need to be implemented by multiple workflow actions.

Figure 5-26 Task Properties Dialog Box

Each task node progresses through four different states: Created, Activated, Executed, and Marked Done. For each state, you can specify a list of actions that are performed when the task reaches that state. The following table shows each task state, and when the actions specified in each state are executed:

All task nodes, unlike other nodes, must be marked done to signal the completion of the node, or the workflow will not proceed. For manually assigned tasks, you can set a permission (see below) that allows a user to mark the task done at run time. More typically, however, you explicitly mark a task done at design time by adding a Mark Task as Done action.

Actions defined in the Task properties dialog box are also displayed in the folder tree under Created, Activated, Executed, and Marked Done folders according to their placement.

About Task Permissions

When you create a Task node, by default, no permissions are initially assigned, but you can enable any of the available task permissions as listed in the following table.

About Task Priority

For manually assigned tasks, you can assign a priority level. The priority has no effect on how the node or its actions are executed at run time, but is simply displayed to Worklist users, who can execute and sort their tasks accordingly.

Priority options are low, medium, and high. The default value is medium.

Defining the Task Node

To define a Task node:

Defining Join Properties

Join nodes are used to merge multiple paths of Task, Event, and Decision nodes into a single path. An AND join causes the workflow to wait until all preceding paths have finished executing before proceeding to the next node. An OR join causes the workflow to proceed to the next node after a single preceding path has finished executing, blocking any preceding unexecuted nodes from executing.

Once you have created a Join, you can change it from AND to OR and vice versa. The shape for the Join is automatically updated in the design area.

Figure 5-27 Join Properties Dialog Box

Defining Done Properties

A Done node represents the point within the workflow where the process completes. Once a done node is reached in the workflow, the running instance of the workflow is marked done, regardless of whether all the done nodes have been reached or not.

You can specify any number of Done nodes in a workflow. If a workflow can exit from various points, you have the option of placing separate done nodes wherever needed.

Although you can add actions to a Done node, this is not recommended.

To define a Done node:

Working with Exception Handlers