This page gives you technical details about the execution of workflow.
Running a workflow
The page Workflow Models Packaging explained how the Studio JAR containing the workflow definitions is deployed on a Nuxeo instance and how the corresponding workflow models are created.
What is happening when starting a new workflow? How is the running workflow persisted?
Running a workflow means creating a new workflow instance from one of the existing workflow models. The new instance is actually created by copy from the workflow model that is run.
So the new workflow is also a document of type DocumentRoute (and the nodes are its children of type RouteNode) with the path /document-route-instances-root/2016/10/15. The date part of the path corresponds to the day the workflow instance has been created. The lifecycle state for a workflow model is "validated", while the instances are "running" when created and will be "done" or "canceled", depending on how the workflow is ended. The document(s) associated at the workflow start is(are) set on the field docri:participatingDocuments.
The DocumentRoute document and the underlying RouteNodes are used by the workflow engine to:
- Read and store the workflow and node variables
- Read the definition of the graph with the transitions between nodes
- Persist the state of the workflow
Those DocumentRoute and RouteNode objects are useless once the workflow is achieved. They are never visible by the end user and they are removed by default. The clean-up is triggered daily at midnight.
In order to keep the completed workflows enable the following line in nuxeo.conf:
nuxeo.routing.disable.cleanup.workflow.instances = true
How are workflow transitions persisted?
Workflow transitions are stored as properties of the node document. A node has an unique id generated by Studio, set on the rnode:nodeId property. The list of possible transitions from a node is a complex metadata: a list of 'transition' where each 'transition' has (among others) a name, a targetId (the id of the target node) and a condition.
What are workflow tasks?
How tasks are created by the workflow is discussed in the section About tasks, but at this point it's worth mentioning that workflow tasks are also persisted as documents of type TaskDoc.
Since workflows, nodes and task are all documents, the NXQL query language can be used, like on any other document type. Check the page How to query workflow objects to find out more.
Runtime Execution Logic
Workflow nodes and tasks
Workflow nodes can be automatic steps or nodes of type task. An automatic node doesn't wait and doesn't require any external intervention to be completed. For a node of type "task", that means a task (or more) is(are) created when the workflow is executing that node and the node is paused as long as all its originating tasks are not completed.
The lifecycle state of a document representing the node waiting for a task to be completed is 'suspended'.
Plug in custom business logic
Custom business logic is added in the workflow by using automation chains at the node level. There are three entry points on the node where a chain can be added: in input, in output and on transitions. The moment when these chains are executed depends on the state of the workflow.
Execution logic
When a workflow is run, the engine starts with the node having the property 'start' set to true and after runs the nodes following, depending on the transitions in the graph.
A workflow node is run after the following algorithm:
Check if this is a node of type 'merge' or not.
- If true, mark the node as 'waiting' and leave it in the list of pending nodes as long as not all its incoming transitions are evaluated to true.
- If false, move to the next step.
- Execute the "input" automation chain.
- If the node is of type "task", create one or more tasks and mark the node as 'suspended'. The node will stay 'suspended' until its tasks are completed, then move to the next step.
- If not, move to the next step.
- Execute the "output" automation chain.
Evaluate all the conditions for all outgoing transitions from the current node. For all the transitions evaluated to 'true':
- Execute the "transition" automation chain.
- Add its target node to the list of pending nodes (the nodes to be run next in the workflow).
Notes
Fork node: A node of type "fork" is a node having all conditions for its outgoing transitions evaluated to 'true'.
Node of type task "Accept/Reject": The conditions of the outgoing transitions from a node of this type depend on how the task originating from the node was completed. When the user ends the task, the id of the button the user clicked is stored on the node in a predefined property. This property is used in the conditions of the outgoing transitions and when these are evaluated: the workflow knows where to go next, depending if the user accepted or rejected the task.
All the automation chained executed by the workflow engine are executed using a temporary unrestricted session (if the current user is not an administrator, this is a session with the user "system"). The documents bound to the workflow are set as the input for these chains.