Workflow Guide

Chapter 5   Workflow Designer

This chapter describes how to use the Workflow Designer to create workflow processes. It has these sections:

• About Workflow Designer

• Defining a process

• Working with the editing features

• Defining activities

• Defining links

    For background information, see Basic Workflow Development.

About Workflow Designer

Creating a workflow process that executes successfully in the Director Workflow subsystem is a three-step process:

1. Use the rich graphing environment of Workflow Designer to visualize and lay out the logic of your process

2. Use the property inspector in Workflow Designer to configure workflow properties that link the process to the resources of your Director environment

3. Save the completed process definition (Workflow Designer translates it into an XML-based program that the workflow engine can execute)

NOTE   Workflow Designer is completely integrated into Workbench.

Summary of Workflow Designer features

Process logic is created exclusively in Workflow Designer. The features available to you are the following.

Defining a process

The document you create with Workflow Designer can be called a workflow, a process, or a process definition. Process definition more precisely refers to the XML document created by Workflow Designer.

To create a process definition:

1. With your EAR project open in Workbench, select File>New from the menu.

2. Click the Workflow tab.

   

3. Select Workflow Process and click OK.

   Workflow Designer opens in the editing area with a new process definition.

   

To save a process definition:

1. Select File>Save from the Workbench menu.

2. If Workflow Designer detects any mistakes in the process, a popup message informs you and asks if you would like to save anyway. This validation occurs on all save events. Click Yes.

   If this is your first save, the Save As dialog appears.

3. Choose a directory location and specify a file name.

   Usually you want to store your process definitions in ResourceSet\data\workflow-processes.

4. Click Save.

To open a process definition:

1. Select File>Open from the Workbench menu.

2. From the Open dialog, choose a directory location and process definition file.

   Usually you can find your processes in ResourceSet\data\workflow-processes.

3. Click Open.

Each process has properties that you can set in Workflow Designer.

To set process properties:

1. Open the property inspector:

   • Click the Designer toolbar icon:

     

     OR

   • With the cursor in the Designer window right click and select Properties.

   The Property Inspector displays the process properties.

   

2. Click the UI tab to view the UI properties.

3. Fill in the Process and UI properties as follows:

   Property	Description
   Name	The formal name of the process. If you need to name your processes according to some naming convention, this is the place to set it.
   Description	A description of the process intended for the Workflow Designer user.
   WorkName	An informal or user-friendly process name that would appear in end user components.
   Roles	A semicolon-delimited list of existing security roles that are authorized to create workitems with this process.     For information about security roles and authorization, see Authorizing access to applications in the User Management Guide.
   Nodes	(Read-only) The number of activities in the process.
   Edges (Paths)	(Read-only) The number of paths in the process. (Edge is the graphing term for a workflow path.)
   Labels	(Read-only) The total number of labels in the process including floating and attached labels.
   Background Color	Click the data area to bring up the standard color selection dialog.

Working with the editing features

The screen below shows the important command features of Workflow Designer:

Graphing environment

Basic navigation

1. Click the Pan button on the toolbar to change the cursor to pan mode.

   

2. Drag the hand cursor on the graph area to scroll the graph in the editing area.

You can also use the horizontal and vertical scroll bars to achieve this effect.

Basic selection

1. Click the Selection button in the toolbar to change the cursor to selection mode.

   

2. Click any object to select it and right-click to display its properties in the Property Inspector.

   Click empty space and drag the selection rectangle around a group of objects to select them all.

Creating a node

Nodes are objects in the graphing environment. They are represented by icons on the graph. A node always represents an instance of an activity.

To create a node (activity):

1. Click the arrow in the activity dropdown list.

2. Select a type:

   

       For information, see Defining activities.

3. Click anywhere on the graph.

   TIP   Click multiple times to create multiple nodes.

Creating an edge

An edge is a linear connection from one node to another. Edges are represented by arrows. An edge is a single path of a workflow link. A link is the set of paths that exit a single activity. Each path represents a potential routing of workitems exiting the activity.

To create an edge (path):

1. Click the arrow in the link path dropdown list.

2. Select a type.

3. Click on a node and drag from the starting node to the target node.

   If you are creating a simple link path, you can only draw a single path from a single activity. The edge appears solid.

   If you are creating a path for any of the other link path types, you can draw multiple paths from a single activity, but all the paths must be of the same type. These edges appear dashed.

   TIP   Select a single path of a multipath link and notice that the rest of the paths that form this link are displayed in blue.

Creating a segment

A segment is the line between two points of an edge.

To create a segment:

• Click any point on a path and drag.

  The point you drag becomes the bend in the path. Segments are purely cosmetic.

Graphical properties

Each node, path, and label has a set of properties associated with it. Select and right-click an element, and the properties of the element are displayed in the Property Inspector.

The table below describes the graphical properties found on some or all of the elements:

Using layout features

The layout is the arrangement of the activities, paths, and labels in your graph. Workflow Designer has a sophisticated layout feature that can completely rearrange your graph to maximize readability and minimize space.

You can specify whether you want the new arrangement to have a horizontal or vertical orientation and whether you want link paths drawn as diagonal lines or composed of perpendicular segments.

There are two kinds of layout: full layout and incremental layout.

Full layout gives Workflow Designer great freedom to move activities, paths, and labels around the graph.

For example: the figure below displays a hand-arranged layout:

The figure below shows the result of applying a full layout to the hand-arranged layout:

Incremental layout attempts to make a graph more attractive and organized but also tries to keep the basic design of your hand-arranged layout.

This figure shows the result of applying an incremental layout to the hand-arranged layout:

TIP   Try a layout on your graph and select Workbench Edit>Undo to back out of a layout you don't want.

To set layout preferences:

1. Choose Workflow >Layout Settings from the Workbench toolbar menu.

   

2. Select an orientation.

3. Select a link (path) style.

4. Click OK.

To apply a full layout:

• Choose Workflow >Full Layout from the Workbench menu.

  OR

• Press Ctrl+Shift+L.

To apply an incremental layout:

• Choose Workflow>Incremental Layout from the Workbench menu.

  OR

• Press Ctrl+Shift+M.

Using zoom features

Workflow Designer gives you four ways to zoom:

Using the grid

Workflow Designer includes a drawing grid that works much like the grid in any graphics program:

• When the grid is visible, the corners of activity and label objects stick to the intersections of horizontal and vertical grid lines. This makes it much easier to line up objects and use consisting spacing.

• When the grid is invisible, objects can be positioned without constraint in one-pixel increments.

• Turning the grid on does not reposition existing items to align with the grid.

To turn the grid on or off:

• Choose Workflow>Toggle Grid from the Workbench menu.

  OR

• Click the Grid button from the Workbench toolbar:

  

  OR

• Press Ctrl+Shift+G.

To change the spacing of grid lines (grid size):

1. Choose Workflow>Grid Size from the Workbench menu.

   The Grid Size dialog displays.

   

2. Enter a value in pixels from 7.5 to 1000.

   The default is 10.

3. Click OK.

Using the Overview window

The Overview window is a popup window that gives you a thumbnail view of the entire workflow graph to help you find your way around in a large graph. The Overview window:

• Appears when you click the Overview button on the toolbar:

  

• Stays on top as you work in the graph area

• Is dismissed by clicking the X button in the upper-right corner

• Can be resized by dragging the edges

• Indicates the overview area visible in the graph area with a blue outline box

You can use the outline box of the Overview window to do several useful things:

Using labels

Labels are separate objects in the graphing environment and therefore have their own property sheets. Labels have two forms:

• Floating labels    Floating labels are simply text you place on your workflow graph and have no association with another workflow graph object. Titles, version numbers, notes, and legends are all good uses for floating labels.

• Attached labels    Most labels are associated with an activity or link path and are called attached labels.

By default, activities and link paths start without a label.

To create a floating label:

1. From the Workbench toolbar, select the Label button:

   

2. Click the location on the graph where you want the label to appear.

   The label appears as a box with the text Untitled inside.

   Each click creates a new label.

3. From the toolbar, select the arrow button.

4. Double-click inside a new label and edit the text.

5. Click outside the label to save your changes.

To create an attached label:

1. In Workbench, right-click an activity icon or link path.

2. From the popup menu, select Create Label.

   A label appears directly below the activity or link path.

3. Double-click inside the label and edit the text.

4. Click outside the label to save your changes.

An activity or link path can have many labels. You can reposition the attached link as you like by dragging it to a new location. Note the line that appears as you drag; this line indicates the activity or link path the label is attached to.

To format any label:

1. In Workbench, right-click the label and select Properties.

   The Property Inspector displays showing the current formatting properties. (If the Property Inspector is already open, simply click the label.)

2. Make the changes you want.

   Changes are saved as you make them.

Defining activities

This section explains the activities you add, as described in Creating a node.

Start activity

Appears automatically when you create a process.

Represents the Workflow subsystem functions necessary to create a new workitem and optionally to assign an initial document to the workitem. The start activity is created when a new workflow process is created and cannot be deleted from the process. There is only one start activity per process. You do not provide a user interface to this activity. To display properties, select the node and right-click.

    For information about the UI properties, see Graphical properties.

User activity

Represents a task or step in your business process that requires human interaction. In Workflow Designer, you specify properties that inform the engine and queue about this task. You use the APIs to interact with the activity. The activity itself is not aware of what code will interact with it. Workitems at an activity wait at the activity until forwarded by your code. To display properties, select the node and right-click.

    For information about coding workitems, see Basic Workflow Development.

    For information about the UI properties, see Graphical properties.

Automatic activity

Represents an unattended task or step in your process. In Workflow Designer, you specify properties that configure the engine and queue for this task. The queue is aware of the Java class that represents the automatic activity. The queue manages automatic activities according to the timeout and retry settings you provide. Programmers must implement a terminate function to specify behavior for automatic activities that exceed timeout and retry counts. To display properties, select the node and right-click.

    For more information, see Customizing Activities and Links.

    For information about the UI properties, see Graphical properties.

Synchronize merge activity

Represents the Workflow subsystem functions necessary to take multiple branches of a workflow and combine them into one. You only need to synchronize and merge workflow paths that send workitems along more than one path:

• AND link

• OR link

There must be one synchronize merge activity for each workflow split, which is any link other than a simple link. Splits and synchronize merges must be defined using the same logic as parentheses. You must merge the last split before you can attempt to merge the split that came before it. You do not provide a user interface to this activity. To display properties select the node and right click.

    For information about the UI properties, see Graphical properties.

Web Service activity

Represents the functionality needed to consume a document style Web Service. Essentially, a Web Service Activity is a specialized extension of an Automatic Activity. In the activity property sheet, you specify a Web Service input document and properly formatted XML that the Web Service needs to return the requested information. Use of this activity assumes familiarity with document style Web Service technology.

    To learn more about WSDL, see www.w3.org/TR/wsdl and www.w3.org/2002/ws/desc.

Click on the Web Service panel to edit these properties:

    For information about the Activity properties, see Automatic activity.

    For information about the UI properties, see Graphical properties.

Rule activity

NOTE   This link type is available only if you have included the Rule subsystem in your Director project. For more information, see Adding Rule subsystem extensions to the Workflow Designer.

Represents the Rule Subsystem functionality needed to execute a rule. The Rule subsystem includes some installed conditions and actions related to workitem properties. For more information see the following descriptions in the Rules Guide:

• Set Workitem Priority action

• Set Workitem Value action

• Check Workitem Value condition

  Property	Description
  Name	A unique reference to this activity. Workflow Designer provides a default name to start with, which you can change. NOTE   You can access this value from the workflow client API using EbiWorkitemDelegate.getActivityName().
  Type	(Read-only) The activity type.
  Description	A description of the activity intended for the Workflow Designer user.
  RuleID	The RuleID as specified in the Rule Editor.

    For information about the UI properties, see Graphical properties.

Finish activity

Represents the Workflow subsystem functions necessary to bring a workflow process to a normal end. There must be one (and only one) finish activity in a process. You do not provide a user interface to this activity. To display properties, select the node and right-click.

    For information about the UI properties, see Graphical properties.

Defining links

This section describes the links you add, as described in Creating an edge.

Simple link

Represents a definite path from one activity to another. You specify the addressee. To display link properties, select the edge element and right-click.

    For information about the UI properties, see Graphical properties.

Specifying an addressee

Each link can accept a single value for its Addressee property. Typically this value is a role, and the role defines a list of users with permission to perform work at the activity. You can also specify that the addressee value should be dynamically derived at runtime from a workitem property.

To specify an addressee:

1. Click the data area beside an Addressee property in the Property Inspector.

   

2. If you want to specify an absolute addressee, select Literal.

   For a user, select User and specify the user name in the Value field.

   For a role, select Role and specify the role name in the Value field.

3. If you want to specify a dynamic addressee, select Expression.

   To obtain the addressee from a workitem property, specify the property name in the Value field.

   To obtain the addressee from a workitem document property, specify the workitem document name and the document property separated by a forward slash:

     workitemDocumentName/documentPropertyName
   

   The dynamic expression must resolve to a single user or role. Even when using a dynamic addressee, the User or Role selection must be accurate. In other words, the path must know whether to expect a user addressee or a role addressee.

   NOTE   The User and Role selections have no affect in this case.

AND link

Represents a definite routing decision to forward the workitem on every path defined in the link. In Workflow Designer, each path is represented by an arrow. The collection of paths exiting an activity is said to be the link. You specify the addressee. To display link properties, select the edge element and right-click.

AND links do not create copies of the workitem—nor do other non-simple links. Rather, they represent the opportunity for multiple tasks to occur simultaneously on one workitem. To avoid contention, you can adopt a strategy of not locking workitems but locking documents within workitems. Organize your workitem data into multiple documents, with information specific to any parallel activities segregated in one document.

You must specify a synchronize merge activity for each AND link. For more information, see Synchronize merge activity.

    For information about the UI properties, see Graphical properties.

OR link

Represents a variable routing decision to forward the workitem on every path that evaluates to true. You specify a simple or compound expression using workitem or document properties. Keep in mind that properties are workflow metadata. To display link properties, select the edge element and right-click.

Care must be taken to guarantee that one path will always be true. An OR path with no expression specified is evaluated as true. If no path evaluates to true, the workitem travels on the default path. An OR link must have one and only one default path specified.

An OR link path that fails to evaluate properly is set to false.

You must specify a synchronize merge activity for each OR link. For more information, see Synchronize merge activity.

    For information about the UI properties, see Graphical properties.

Specifying a path expression

The expression builder allows you to test workitem properties and workitem document properties in simple or compound expressions that ultimately evaluate to true or false.

To specify an expression:

1. Click in the data area beside an expression property in the Property Inspector.

   

2. Specify a workitem property or document property.

   To specify a workitem property, enter it in the Property Name field and leave the Document Name field blank.

   To specify a document property, enter it in the Property Name field and enter the associated document name in the Document Name field.

3. Specify the value to test in the Property Value field.

4. In the first dropdown list, if this is not the first test condition, choose whether you want the current test condition ANDed or ORed to the condition that precedes it.

5. In the second dropdown list, choose the test, such as eq (equals) or gt (greater than).

6. In the third dropdown list, choose the data type of the Property Value field.

   The Designer attempts to validate your entry.

   • For Boolean, you must enter true or false.

   • For Timestamp, use this format:

       MM/DD/YYY < optional: HH:MM:SS>
     

7. (Optional) Enable the Not check box to negate the current expression.

8. Click Add.

9. Repeat the Steps 1 through 8 as necessary, and click OK when you are done.

XOR link

Represents a variable routing decision to forward the workitem on the first path that evaluates to true. You specify a simple or compound expression using workitem or document properties. To display link properties, select the edge element and right-click.

The Workflow subsystem controls the order of evaluation.

Care must be taken to guarantee that one path will always be true. An XOR path with no expression specified is evaluated as true. If no path evaluates to true, the workitem travels on the default path. An OR link must have one and only one default path specified.

An XOR link path that fails to evaluate properly is set to false.

    For information about the UI properties, see Graphical properties.

XOR condition link

NOTE   This link type is available only if you have included the Rule subsystem in your Director project. For more information, see Adding Rule subsystem extensions to the Workflow Designer.

Represents a variable routing decision to forward the workitem on the first path that evaluates to true. Essentially, it is an enhanced XOR link. The Workflow subsystem controls the order of evaluation. To display link properties, select the edge element and right-click.

The Rule subsystem includes an installed condition that allows you to check a workitem value. For more information, see the description for the Check Workitem Value condition in the Rules Guide.

Care must be taken to guarantee that one path will always be true. An XOR path with no condition specified is evaluated as true. If no path evaluates to true, the workitem travels on the default path. An OR link must have one and only one default path specified.

An XOR condition link path that fails to evaluate properly is set to false.

    For information about the UI properties, see Graphical properties.

Rule link

NOTE   This link type is available only if you have included the Rule subsystem in your Director project. For more information, see Adding Rule subsystem extensions to the Workflow Designer.

Represents a variable routing decision evaluated by the Rule subsystem using an existing rule. Rule links choose only one path. The rule returns the path. The Rule subsystem includes an installed action that allows you to specify the path. For more information, see the description for the Set Next Activity action in the Rules Guide.

To display link properties, select the edge element and right-click.

NOTE   The addressee is specified in Workflow Designer, not in the rule.

    For information about the UI properties, see Graphical properties.

Adding Rule subsystem extensions to the Workflow Designer

If you have the Rule subsystem in your application, you can take advantage of the integration between the Rule subsystem and the Workflow subsystem. You can add a Rule Activity and two types of link: XOR condition link and Rule link.

To add rule extensions to the Workflow Designer:

1. Make sure Workbench is not running.

2. Copy the following file from this location in your Director install directory:

     \templates\TemplateResources\workflow-re\WorkflowRE.jar
   

   to this location in your Workbench install directory:

     \lib\graphbeans\workflow\
   

3. Restart Workbench.

   The activity and link types appear in the activity and link menu selections in the Workflow Designer.

Workflow Guide

Copyright © 2002, SilverStream Software, LLC, a wholly owned subsidiary of Novell, Inc. All rights reserved.