Chapter 6. Process definitions

Table of Contents

A small overview on the workflow engine and its process definitions
Process definitions
Expressions
Workitems
The main expressions
process-definition
participant
sequence
concurrence
iterator
concurrent-iterator
subprocess
The cursor and the loop expressions
cursor
loop
break, cancel, continue, rewind, back
Expressions for workitem manipulation
set
unset
inc
Conditional expressions
if
case
equals
not
and
or
greater-than
lesser-than
undefined
defined
when
Xeme expressions
quote / q
attribute / a
field / f
variable / v
list
car
cdr
cons
xar
xdr
xons
append
size
nth
Conditional xeme expressions
is-null
is-list
is-atom
is-empty
Time expressions
sleep
cron
Other expressions
save and restore
eval
log
do, undo and redo
interleaved
cancel-process
forget
lose
rotate
The 'dollar notation'
using variables with the dollar notation
using fields with the dollar notation
combining fields and variables in the dollar notation
using constants with the dollar notation
using engine parameters or system properties with the dollar notation
using functions with the dollar notation
Functions
How functions are made available to the engine
A potpourri of Functions
The 'eval' function
The 'range' function
Functions and errors
Implementing your own expressions
Validation of an XML workflow definition

A small overview on the workflow engine and its process definitions

Process definitions

A workflow definition is simply a text file. Actually, this text is structured as XML.

Each release of OpenWFE comes with a process-definitions/ directory where all those files do fit.

This directory is mapped to a small Jetty webserver that listens on port 7079 (it is launched as service 'EngineContext.workflowDefinitionServer' in etc/engine/engine-configuration.xml)

You don't have to restart the engine in order to activate your newly designed workflow definitions, you just have to copy it in workflow-definitions/ or directly edit it there.

Let's assume you've created a workflow definition for flow named 'myflow' with revision '1.0' and saved it under myflow__1.0.xml.

General structure of a process definition

Process definitions are XML documents (though OpenWFE may be extended to understand other formats/sources of process definitions).

The root node is named 'process-definition' and has two mandatory attributes : 'name' and 'revision'.

An XML Schema for the workflow definitions can be found at http://www.openwfe.org/flowdef.xsd If you want to take leverage of it with a power-xml-editor, your workflow definition XML document like this :


<process-definition 

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.openwfe.org/flowdef.xsd"

    name="myflow" 
    revision="1.x"
>

the first children nodes may be description nodes like :


    <description language="default">
     A filtered flow. The participant 'alice' may not have complete access to all
     fields of the workitems transiting to her through this flow.  
    </description>
    
    <description language="fr">
     Un flux filtré. La participante 'alice' n'a pas forcément accès à tous les
     champs des workitems qui transitent vers elle au travers du flux.
    </description>

Such descriptions are used by the UI to present the workflow to the potential launcher. As you can see, a description can be specified in multiple languages, following the two-letter international language code.

the node child immediately after a description (or the first node child if there are no descriptions) is considered as the body of the workflow definition (much like the body of a procedure.

There can be one and only one expression that stands as the body of the definition.

After the body, there may be zero or more 'filter-definition' children, like for example :


    <filter-definition 
       name="reviewer-filter" 
       type="closed" 
       add="false"
    >
        <field regex="review" permissions="rw" />
            <!-- read-write -->

        <field regex="docUrl" permissions="r" />
            <!-- read-only -->

        <field regex="initiatorReview" permissions="" />
            <!-- hidden -->

    </filter-definition>

Such a filter can be attributed to a participant (or a dynamic participant) expression in the body of the flow, like in :


    <participant 
       ref="reviewer-alpha" 
       filter="reviewer-filter" 
    />

This filter defined here is a closed filter so that every field it doesn't mention are considered as hidden. As its 'add' attribute is set to 'false', a user cannot add a field to the workitem. The filter should be followed by the UI or the process acting on the workitem, but anyway, when the workitem gets back the 'filtered' expression, the filter is enforced and any illegal changes are discarded.

sub processes

A workflow definition can contain sub process definitions.


<process-definition 
    name="flow" 
    revision="1.13"
>

    <description>
A recursive flow subdefinition
    </description>

    <subprocess ref="review" />

    <process-definition name="review">
        <sequence>
            <participant ref="role-alpha" />
            <if>
                <not>
                    <equals field-value="reviewed" other-value="true" />
                </not>
                <subprocess ref="review" />
                    <!-- loop until 'reviewed' is set to 'true' -->
            </if>
        </sequence>
    </process-definition>

</process-definition>

This example contains a subprocess named 'review'. The main process only contains a reference to the subprocess. If you carefully examine the example, you'll notice that it is recursive : the subprocess 'review' may call itself. The participant 'role-alpha' will keep receiving the workitem until the field 'reviewed' is set to 'true'.

The language tags appeared here : 'process-definition' and 'subprocess'. The latter one calls a defined subprocess through its 'ref' attribute. Of course, you can specify 'field-ref' or 'variable-ref' instead of 'ref' so that subprocesses to be launched at determined at runtime.

Expressions

An expression is an 'instruction' in OpenWFE process definition language. It can be applied and replied to. Both of these operations require a workitem.

Expressions are applied by their parent expression and get replied to by their children expressions or by a workitem listener (in the case of a participant expression).

For each workflow instance, upon launch, a tree of expressions is built and stored in the engine's expression pool. The root of the tree is the body expression of the workflow (see 'General structure' a few scroll down).

Workitems

Workitems are pieces of data. At the beginning of a workflow instance, there is one and only one workitem. When a workitem is used for the application of a concurrent expression, multiple workitems are usually used for the application of the children of the concurrent expression. A merge is then performed with the merge rules inside the reply method of the concurrent expression.

When you launch a workflow, it is usually done with a launchitem, a basic kind of workitem that gets passed to an engine and contains all the nessary info for launching a flow.

The workitems transiting through live instances of a flow are of class 'InFlowWorkItem'.

OpenWFE may perhaps include in later releases 'CancelItems', items whose task is to notify an engine of the cancelling of a flow instance.