Activities and Transitions

The workflow model is activity-based [FG02]. The activities that are to be completed throughout the workflow and the transitions between them are mapped to the nodes and edges of a directed graph. This choice was made to faciliate the application of the Graph-Oriented Programming paradigm for the implementation.

Graph Traversal and Execution Strategy

The execution of a workflow starts with the graph's only Start node. A graph may have one or more End nodes that explicitly terminate the workflow execution.

After a node has finished executing, it can activate one or more of its possible outgoing nodes. Activation adds a node to a set of nodes that are waiting for execution. During each execution step, a node from this set is executed. When the execution of a node has been completed, the node is removed from the set.

The workflow execution is implicitly terminated when no nodes are activated and no more nodes can be activated.

State and Workflow Variables

The workflow model supports state through the concept of workflow variables. Such a variable can either be requested as user input (from an Input node) or be set and manipulated through the VariableSet, VariableAdd, VariableSub, VariableMul, VariableDiv, VariableIncrement, and VariableDecrement nodes.

While a VariableSet node may set the value of a workflow variable to any type that is supported by PHP, the other variable manipulation nodes only operate on numeric values.

Variables are bound to the scope of the thread in which they were defined. This allows parallel threads of execution to use variables of the same name without side effects.

When the execution of a workflow reaches an Input node (see above), the execution is suspended until such time when the user input has been provided and the execution can be resumed.

Control Flow

The control flow semantics of the workflow model draws upon the workflow patterns from [BK03]. The Sequence, Parallel Split, Synchronization, Exclusive Choice, Simple Merge, Multi-Choice, Synchronizing Merge, and Discriminator workflow patterns are all directly supported by the workflow model.

Exclusive Choice and Multi-Choice nodes have branching conditions attached to them that operate on workflow variables to make their control flow decisions.

Action Nodes and Service Objects

So far we have only discussed nodes that control the flow or that can manipulate workflow variables. We are still missing a type of node that actually performs an activity. This is where the Action node comes into play.

When the execution of a workflow reaches an Action node, the business logic of the attached service object is executed. Service Objects live in the domain of the application into which the workflow engine is embedded. They have read and write access to the workflow variables to interact with the rest of the workflow.

Sub-Workflows

The workflow model supports sub-workflows to break down a complex workflow into parts that are easier to conceive, understand, maintain, and which can be reused.

A sub-workflow is started when the respective Sub-Workflow node is reached during workflow execution. The execution of the parent workflow is suspended while the sub-workflow is executing. It is resumed once the execution of the sub-workflow has ended.

Architecture and extensions

The workflow engine been designed and implemented as three loosely coupled components. The Workflow component provides an object-oriented framework to define workflows and an execution engine to execute them. The WorkflowDatabaseTiein and WorkflowEventLogTiein components tie the Database and EventLog components into the main Workflow component for execution persistence and monitoring, respectively.

A workflow can be defined programmatically by creating and connecting objects that represent control flow constructs. The classes for these objects are provided by the Workflow Definition API. This API also provides the functionality to save workflow definitions (ie. object graphs) to and load workflow definitions from a data storage. Two data storage backends have been implemented, one for relational database systems and another for XML files. Through the Workflow Execution API the execution of a workflow definition can be started (and resumed). The figure below shows the conceptual architecture for the workflow engine.

The minimalistic core of the Workflow component is provides basic workflow functionality:

• The Workflow Definition API implements an activity-based workflow model and provides the abstractions required to build workflows.
• The Workflow Execution API implements the functionality to execute workflows.

On top of these core components other components, for instance for persistence (suspending and resuming workflow execution), monitoring (status of running workflows), history (history of executed workflows), and worklist management (human-computer interface), can be implemented. Each of these components encapsulates a design decision and can be customized or replaced.

Summary

The core of the workflow engine is a virtual machine that executes workflows represented through object graphs. These object graphs can be created programmatically through the software component's Workflow Definition API. Alternatively, a workflow definition can be loaded from an XML file. Object graph and XML file are two different representations of a workflow definition that uses the so-called backend language of the workflow engine's core.

Workflow Execution

ezcWorkflowExecutionNonInteractive

An object of the ezcWorkflowExecutionNonInteractive class can execute non-interactive workflows, in other words workflows that contains no input nodes and no sub-workflows.

ezcWorkflowDatabaseExecution

An object of the ezcWorkflowDatabaseExecution class can execute interactive workflows. The persistence data is stored using a relational database.

Workflow Definition

ezcWorkflowDefinitionStorageXml

The ezcWorkflowDefinitionStorageXml class provides the functionality to save workflow definitions to and load workflow definitions from XML files.

ezcWorkflowDatabaseDefinitionStorage

The ezcWorkflowDatabaseDefinition Storageclass provides the functionality to save workflow definitions to and load workflow definitions from a relational database.

Graph Node Classes

Objects of the ezcWorkflowNode classes represent the nodes of a workflow.

ezcWorkflowNode

ezcWorkflowNode is the abstract base class for all graph node classes.

ezcWorkflowNodeStart

An object of the ezcWorkflowNodeStart class represents the one and only start node of a workflow. The execution of the workflow starts here.

Creating an object of the texttt{ezcWorkflow} automatically creates the start node for this new workflow. It can be accessed through the getStartNode() method.

ezcWorkflowNodeEnd

An object of the ezcWorkflowNodeEnd class represents an end node of a workflow. A workflow must have at least one end node. The execution of the workflow ends when an end node is reached.

Creating an object of the ezcWorkflow automatically creates a default end node for this new workflow. It can be accessed through the getEndNode() method.

ezcWorkflowNodeAction

An object of the ezcWorkflowNodeAction class represents an activity node. When the node is reached, the business logic that is implemented by the associated service object is executed.

ezcWorkflowNodeSubWorkflow

An object of the ezcWorkflowNodeSubWorkflow class represents a sub-workflow. When the node is reached, the specified sub-workflow is started. The workflow is suspended until the sub-workflow has finished executing.

ezcWorkflowNodeInput

An object of the ezcWorkflowNodeInput class represents an input node. When the node is reached, the workflow engine will suspend the workflow execution if the specified input data is not available (first activation). While the workflow is suspended, the application that embeds the workflow engine may supply the input data and resume the workflow execution (second activation of the input node). Input data is stored in a workflow variable.

ezcWorkflowNodeVariableSet

An object of the ezcWorkflowNodeVariableSet class sets a specified workflow variable to a given value.

ezcWorkflowNodeVariableUnset

An object of the ezcWorkflowNodeVariableUnset class unsets a specified workflow variable.

ezcWorkflowNodeVariableAdd

An object of the ezcWorkflowNodeVariableAdd class adds a given operand, either a constant or the value of another workflow variable, to a specified workflow variable.

ezcWorkflowNodeVariableSub

An object of the ezcWorkflowNodeVariableSub class subtracts a given operand, either a constant or the value of another workflow variable, from a specified workflow variable.

ezcWorkflowNodeVariableMul

An object of the ezcWorkflowNodeVariableMul class multiplies a specified workflow variable with a given operand, either a constant or the value of another workflow variable.

ezcWorkflowNodeVariableDiv

An object of the ezcWorkflowNodeVariableDiv class divides a specified workflow variable by a given operand, either a constant or the value of another workflow variable.

ezcWorkflowNodeVariableIncrement

An object of the ezcWorkflowNodeVariableIncrement class increments the value of a specified workflow variable.

ezcWorkflowNodeVariableDecrement

An object of the ezcWorkflowNodeVariableDecrement class decrements the value of a specified workflow variable.

ezcWorkflowNodeParallelSplit

The ezcWorkflowNodeParallelSplit class implements the Parallel Split workflow pattern.

The Parallel Split workflow pattern divides one thread of execution unconditionally into multiple parallel threads of execution.

Use Case Example: After the credit card specified by the customer has been successfully charged, the activities of sending a confirmation email and starting the shipping process can be executed in parallel.

ezcWorkflowNodeSynchronization

The ezcWorkflowNodeSynchronization class implements the Synchronization workflow pattern.

The Synchronization workflow pattern synchronizes multiple parallel threads of execution into a single thread of execution. Workflow execution continues once all threads of execution that are to be synchronized have finished executing (exactly once).

Use Case Example: After the confirmation email has been sent and the shipping process has been completed, the order can be archived.

ezcWorkflowNodeExclusiveChoice

The ezcWorkflowNodeExclusiveChoice class implements the Exclusive Choice workflow pattern.

The Exclusive Choice workflow pattern defines multiple possible paths for the workflow of which exactly one is chosen.

Use Case Example: After an order has been received, the payment can be performed by credit card or bank transfer.

ezcWorkflowNodeSimpleMerge

The ezcWorkflowNodeSimpleMerge class implements the Simple Merge workflow pattern.

The Simple Merge workflow pattern is to be used to merge the possible paths that are defined by a preceding Exclusive Choice. It is assumed that of these possible paths exactly one is taken and no synchronization takes place.

Use Case Example: After the payment has been performed by either credit card or bank transfer, the order can be processed further.

ezcWorkflowNodeMultiChoice

The ezcWorkflowNodeMultiChoice class implements the Multi Choice workflow pattern.

The Multi-Choice workflow pattern defines multiple possible paths for the workflow of which one or more are chosen. It is a generalization of the Parallel Split and Exclusive Choice workflow patterns.

ezcWorkflowNodeSynchronizingMerge

The ezcWorkflowNodeSynchronizingMerge class implements the Synchronizing Merge workflow pattern.

The Synchronizing Merge workflow pattern is to be used to synchronize multiple parallel threads of execution that are activated by a preceding Multi-Choice.

ezcWorkflowNodeDiscriminator

The ezcWorkflowNodeDiscriminator class implements the Discriminator workflow pattern.

The Discriminator workflow pattern can be applied when the assumption we made for the Simple Merge workflow pattern does not hold. It can deal with merge situations where multiple incoming branches may run in parallel. It activates its outgoing node after being activated by the first incoming branch and then waits for all remaining branches to complete before it resets itself. After the reset the Discriminator can be triggered again.

Use Case Example: To improve response time, an action is delegated to several distributed servers. The first response proceeds the flow, the other responses are ignored.

Condition Classes

The ezcWorkflowCondition classes can be used to express branch conditions and input validation.

ezcWorkflowConditionVariable

An object of the ezcWorkflowConditionVariable loads a workflow variable and evaluates another ezcWorkflowCondition object for it.

ezcWorkflowConditionNot

An object of the ezcWorkflowConditionNot decorates an ezcWorkflowCondition object and negates its expression.

ezcWorkflowConditionAnd

An object of the ezcWorkflowConditionAnd class represents a boolean AND expression. It can hold an arbitrary number of ezcWorkflowCondition objects.

ezcWorkflowConditionOr

An object of the ezcWorkflowConditionOr class represents a boolean OR expression. It can hold an arbitrary number of ezcWorkflowCondition objects.

ezcWorkflowConditionXor

An object of the ezcWorkflowConditionXor class represents a boolean XOR expression. It can hold an arbitrary number of ezcWorkflowCondition objects.

ezcWorkflowConditionIsTrue

The condition represented by an ezcWorkflowConditionIsTrue object evaluates to true when the associated workflow variable has the value true.

ezcWorkflowConditionIsFalse

The condition represented by an ezcWorkflowConditionIsFalse object evaluates to true when the associated workflow variable has the value false.

ezcWorkflowConditionIsEqual

The condition represented by an ezcWorkflowConditionIsEqual object evaluates to true when the associated workflow variable is equal to the comparison value.

ezcWorkflowConditionIsNotEqual

The condition represented by an ezcWorkflowConditionIsNotEqual object evaluates to true when the associated workflow variable is not equal to the comparison value.

ezcWorkflowConditionIsGreaterThan

The condition represented by an ezcWorkflowConditionIsGreaterThan object evaluates to true when the associated workflow variable is greater than the comparison value.

ezcWorkflowConditionIsEqualOrGreaterThan

The condition represented by an ezcWorkflowConditionIsEqualOrGreaterThan object evaluates to true when the associated workflow variable is equal to or greater than the comparison value.

ezcWorkflowConditionIsLessThan

The condition represented by an ezcWorkflowConditionIsLessThan object evaluates to true when the associated workflow variable is less than the comparison value.

ezcWorkflowConditionIsEqualOrLessThan

The condition represented by an ezcWorkflowConditionIsEqualOrLessThan object evaluates to true when the associated workflow variable is equal to or less than the comparison value.

ezcWorkflowConditionIsAnything

The condition represented by an ezcWorkflowConditionIsAnything object always evaluates to true.

ezcWorkflowConditionIsArray

The condition represented by an ezcWorkflowConditionIsArray object evaluates to true when the associated workflow variable is an array.

ezcWorkflowConditionIsBool

The condition represented by an ezcWorkflowConditionIsBool object evaluates to true when the associated workflow variable is a boolean.

ezcWorkflowConditionIsFloat

The condition represented by an ezcWorkflowConditionIsFloat object evaluates to true when the associated workflow variable is a float.

ezcWorkflowConditionIsInteger

The condition represented by an ezcWorkflowConditionIsInteger object evaluates to true when the associated workflow variable is an integer.

ezcWorkflowConditionIsObject

The condition represented by an ezcWorkflowConditionIsObject object evaluates to true when the associated workflow variable is an object.

ezcWorkflowConditionIsString

The condition represented by an ezcWorkflowConditionIsString object evaluates to true when the associated workflow variable is a string.

Creating a simple workflow programmatically

This example shows how to set up a fairly simple workflow that will execute differently based on the variable 'choice'.

  1. <?php
  2. // Create new workflow of name "Test".
  3. $workflow = new ezcWorkflow( 'Test' );
  4. 
  5. // Create an Input node that expects a boolean workflow variable of name "choice".
  6. $input = new ezcWorkflowNodeInput(
  7.   array( 'choice' => new ezcWorkflowConditionIsBool )
  8. );
  9. 
 10. // Add the previously created Input node
 11. // as an outgoing node to the start node.
 12. $workflow->startNode->addOutNode( $input );
 13. 
 14. // Create a new Exclusive Choice node and add it as an
 15. // outgoing node to the previously created Input node.
 16. // This node will choose which output to run based on the
 17. // choice workflow variable.
 18. $branch = new ezcWorkflowNodeExclusiveChoice;
 19. $branch->addInNode( $input );
 20. 
 21. // Either $true or $false will be run depending on
 22. // the above choice.
 23. // Note that neither $true nor $false are valid action nodes.
 24. // see the next example
 25. $trueNode  = new ezcWorkflowNodeAction( 'PrintTrue' );
 26. $falseNode = new ezcWorkflowNodeAction( 'PrintFalse' );
 27. 
 28. // Branch
 29. // Condition: Variable "choice" has boolean value "true".
 30. // Action:    PrintTrue service object.
 31. $branch->addConditionalOutNode(
 32.     new ezcWorkflowConditionVariable( 'choice', new ezcWorkflowConditionIsTrue ),
 33.     $trueNode );
 34. 
 35. // Branch
 36. // Condition: Variable "choice" has boolean value "false".
 37. // Action:    PrintFalse service object.
 38. $branch->addConditionalOutNode(
 39.   new ezcWorkflowConditionVariable( 'choice', new ezcWorkflowConditionIsFalse ),
 40.   $falseNode
 41. );
 42. 
 43. // Create SimpleMerge node and add the two possible threads of
 44. // execution as incoming nodes of the end node.
 45. $merge = new ezcWorkflowNodeSimpleMerge;
 46. $merge->addInNode( $trueNode );
 47. $merge->addInNode( $falseNode );
 48. $merge->addOutNode( $workflow->endNode );
 49. ?>

Adding custom PHP code to your workflow and manipulating workflow variables

In the previous example the $trueNode and $falseNodes where action objects. However, in order to make them work we must add service objects. The following example replaces the lines where $trueNode and $falseNode are created.

  1. <?php
  2. class MyServiceObject implements ezcWorkflowServiceObject
  3. {
  4.     private $message;
  5. 
  6.     public function __construct( $message )
  7.     {
  8.         $this->message = $message;
  9.     }
 10. 
 11.     public function execute( ezcWorkflowExecution $execution )
 12.     {
 13.         echo $this->message;
 14. 
 15.         // Manipulate the workflow.
 16.         // Does not affect the workflow, for illustration only.
 17.         $execution->setVariable( 'choice', true );
 18. 
 19.         // Return true to signal that the service object has finished
 20.         // executing.
 21.         return true;
 22.     }
 23. 
 24.     public function __toString()
 25.     {
 26.         return "MyServiceObject, message {$this->message}";
 27.     }
 28. }
 29. 
 30. $trueNode = new ezcWorkflowNodeAction( array( 'class' => 'MyServiceObject',
 31.                                               'arguments' => array( 'message: TRUE' ) )
 32.                                        );
 33. $falseNode  = new ezcWorkflowNodeAction( array( 'class' => 'MyServiceObject',
 34.                                                 'arguments' => array( 'message: FALSE' ) )
 35.                                          );
 36. ?>

When this action node is executed it will load the service object with the parameters specified and run the execute() method. Our execute method will print the message passed to the constructor and change the workflow variable 'choice'.

Saving a workflow to an XML file

Typically a workflow is built once and executed many times. It is also common that workflows are interupted during execution and resumed later in another PHP request. To accomodate this it is possible to save and load workflows to XML files (or database through the WorkflowDatabaseTiein).

This example shows you how to store a workflow to an XML file. The example assumes the workflow can be found in the $workflow variable.

  1. <?php
  2. // Set up workflow definition storage (XML).
  3. $definition = new ezcWorkflowDefinitionStorageXml( '/path/to/directory' );
  4. 
  5. // Save workflow definition to database.
  6. $definition->save( $workflow );
  7. ?>

Loading a workflow from an XML file

It is of course also possible to load a workflow that has been saved to disk.

  1. <?php
  2. // Set up workflow definition storage (XML).
  3. $definition = new ezcWorkflowDefinitionStorageXml( '/path/to/directory' );
  4. 
  5. // Load latest version of workflow named "Test".
  6. $workflow = $definition->loadByName( 'Test' );
  7. ?>

Visualizing a workflow using GraphViz

It is possible to write visitors that traverse the workflow graph. One example of this is the GraphViz visitor that generates a viewable graph representation of the workflow. The GraphViz visitor uses the __tostring methods on the nodes to get names for the nodes.

  1. <?php
  2. // Generate GraphViz/dot markup for workflow "Test".
  3. $visitor = new ezcWorkflowVisitorVisualization;
  4. $workflow->accept( $visitor );
  5. print $visitor;
  6. ?>

digraph Test {
node1 [label="Start"]
node3 [label="Input"]
node4 [label="Exclusive Choice"]
node5 [label="PrintTrue"]
node7 [label="Simple Merge"]
node2 [label="End"]
node6 [label="PrintFalse"]

node1 -> node3
node3 -> node4
node4 -> node5 [label="choice is true"]
node4 -> node6 [label="choice is false"]
node5 -> node7
node7 -> node2
node6 -> node7
}