The ]po[ Workflow Introduction Frank Bergmann, 2006-11-15

This guide contains ]po[ workflow overview information for developers with experience with PostgreSQL and the OpenACS toolkit.

Draft Draft

Scope, Audience & Purpose

These slides provide background material talk on ]project-open[ workflows.

We assume that the reader is familiar with basic concepts and the database structure of ]po[ (no TCL knowledge necessary)

For developer documentation please see:– http://www.project-open.org/product/modules/workflow/– http://project-open.blogger.com/ “Dynamic WF with ]po[“

Components of a Workflow

1. The Petri-Net:Many people think this is the main component, but it’s not.

2. The Object:Every WF in ]po[ is associated with exactly one object.

3. Assignment Logic:This is usually a set of PL/SQL procedures that determine who should perform each action in the WF.

4. A number of “Actions”:These are usually calls to “im_object__set_status” PL/SQL procedures that modify the object’s status depending on the WF progress

5. GUI Panels:These panels are TCL forms that allow a user to add information to an object and/or to take special actions implemented in TCL code.

Simple Approval Workflow

Modify

Confirm

Confirmed Rejected

OK

NotOK

Workflow Assignment

Assign to owner of the underlying object

Assign to the “supervisor” of the object’s owner

“Automatic” transitions, no assignment necessary

Actions

enable: status=rejected

fire: status=requested

enable: status=confirmed

GUI Panels

ObjectInfo

Form

AdditionalInfo

Confirm

Delete

The same “panel” is shown for both “Modify” and “Confirm” with minor

differences

Simple Approval Workflow

The example in the previous page shows a simple approval workflow. This WF is used for example in ]po[ V3.4 for approval of vacation requests (“Absences”).

Object Type -> Workflow Mapping

When creating a new object, ]po[ allows you to define a workflow per object type.

]po[ looks up the workflow key in the object type’s category in the “im_categories.aux_string1”

Currently, the following objects are WF-enabled:

– im_project,– im_user_absence,– im_expense_bundle and– im_timesheet_conf_obj

The screenshot at the right show the “SaaS” project type, which is associated with a “saas_project_workflow_wf”.

Showing the WF-Status of a Project

In ]po[ V3.4 there are two additional components associated with every WF-enabled object:

– The “Workflow Graph” shows the current status of the WF and

– The “Workflow Journal” shows the history of all WF decisions.

Timed Transitions

What is a “Timed Transition”?– A Timed transitions automatically “fired” at its

“trigger_time”.– A “Timed Transition” is different from a “hold timeout”:

A timed transition fires, while the “hold timeout” cancels the transition

How can I set the “Trigger Time”?– Trigger_time is set by the result of the “Time” callback.

This callback can be specified in the “Time” field of the WfActionPage

– The time callback is called when the transition is “enabled”.

Request For Change Example

"RFC" Example Case

For the rest of this introduction we will assume the following a "Request for Change" (RFC) example.

– The IT-department of a large corporation wants to consolidate its help-desk operations

– All requests from the organization's users ("Requests for Change", RFC) are captured using a web based application

– Each RFC consists of a number of fields that together specify the customer's need

– The RFC is processed in a strucured way using a Workflow.

It is likely that the workflow will change in the future to accomodate organizational and process changes. Changes should configurable.

RFC - Form & Dynamic Fields

An important number of form fields have been identified during the analysis phase

Fields may or may not appear, depending on the type of RFC

It is possible that the variables variables in the form will change during the course of the project. Changes should be easy to introduce, preferably configurable by the application administrators from the customer's side.

ScreenshotRFC-Form

RFC - Roles

EmployeeAn employee beneficient of the RFC - the guy who needs something changed

DistributorA member of the IT helpdesk to complete the RFC and to judge technical viablility

ApproverThe Employee's boss or somebody with suitable budget responsability to confirm the employee's RFC.

How to Plan your Workflow

"Transitions" & "Places"

Transitions in general represent decisions or actions by a particular user group.

You should normally use different transitions if different user groups are involved (i.e. Employee, IT-Department & Employee's Boss). Otherwise only use a single transition.

It's good practice to reduce the number of transitions to a minimum.

Places are located before and after each transition. They are normally created automatically when creating a new transition.

"Arcs", "Guards", "Attributes" & User Decisions

"Arcs" connect Places with Transitions. "Guards" are boolean conditions on Arcs.

An Arc only "becomes active" (passes on a token) if it's Guard is "true". Two or more Guards behave like an IF-THEN-ELSE.

Web interface actions at the can not influence Guards, however.

Instead, Web actions modifiy the values of WF variables ("Attributes"). The boolean Guard conditions can use these variables to determine their IF-THEN-ELSE behaviour.

"Arcs", "Guards", "Attributes" & User Decisions

Guards are not directly connected to the Web interface. A Guard

A user action (pressing a button) can not influence a Guard directly.

Instead, Web interface actions modify "Attributes" (the workflow's variables). These Attributes in turn can influence the behaviour of Guards.

Designing an IF-THEN-ELSE WF Decision/Branching/...

Two type of standard Guards:– Guard that checks a variable for a particular

value– "ELSE"-Guard, that becomes true if the other

guards haven't become true. - Plus: User-Written Guards:

– The SysAdmin can write his own guards as PlPg/SQL procedures.

Implementing a Two-Way Decision

We usually implement a two-way (IF-ELSE) decision using a boolean Attribute:

– One branch is followed if the attribute is "true". We select a wf_callback__guard_attribute_true" guard and specify the attribute name in the "Optional Argument" field.

– The ELSE condition of the other branch is implemented by choosing the "No other guards were satisfied" condition.

It is important that exactly one Guard becomes true:

– The token would disappear (gets "swallowed")

Implementing a Two-Way Decision

Choose a reasonable Attribute name. For example "Cancel RFC". Take into account that this attribute is global to the entire WF, and that you may reuse the Attribute in other transitions for a similar purpose.

Avoiding Multiple Tokens and "Swallowed" Tokens

Make sure that there is exactly one Guard active on the database & Pl/SQL level:

– You frequently make errors on the GUI level– There errors are _extremely_ difficult to

debug, because WF is difficult to debug– Other parts of the GUI may depend on the

assumption that there is only one Token in the WF. These GUI elements may crash under a duplicated Token condition. However, you won't understand (easily) that this was the condition of the crash.

WF & User Decisions

Transitions frequently involve decisions that lead to a kind of behaviour, controlling the flow in the Workflow

In order to

Frank Bergmannfrank.bergmann@project-open.com

www.project-open.com