Deferrals

Overview

Workflow processing only stops for a few reasons:

  • A branch (or connector expression) resolves to False
  • There are no more nodes to process
  • The engine encounters a deferred node

Deferred nodes are used to wait for a response from another process. For example, an approval node should create the approval but then wait for the decision before continuing processing.

Configuring the Node

Most nodes meant to be deferred are already set to default that way as Handlers. If you want to manually set the node as deferred, you must select the Defers check box on the node after (not during) node creation.

deferral

Example of a deferred node

Deferred nodes show a blue corner on the node. It makes them easy to find on trees.

deferredNode

A blue corner on a node indicates the node is deferred

Defers and the Task Engine

When the Task Engine encounters a deferred node, it completes the function of the node (such as approval or record creation), then stops and waits for a trigger to complete the node. In a run, the node (shown as a Task) remains "In Progress" until a trigger completes it.

Tokens and Triggers

Once a node has stopped workflow processing, it must be resumed via a Trigger. Resuming a deferred node requires the following information:

  • Token: A unique identifier that allows the engine to find the specific instance of the node.
  • Action Type: Can be either Update or Complete. This determines the action the workflow engine takes on the deferred node instance.
    • Update: Used to fire Update connectors attached to the deferred node instance. It can also pass specific messages.
    • Complete: Used to complete the deferred node instance and fire attached Complete connectors.

Note: The Task API can also update or complete deferred nodes.

SampleTrigger2

An example of a trigger on a deferred node

Results and Messages

One of the benefits of a deferred node is passing information from the system that is creating the trigger to restart the deferred node instance. Information can take the form of either Results or Messages. In general, Results are used in the workflow, and Messages are simple statements used to notify an interested party.

Results have a specific XML structure:

    <results>
       <result name="Approval Decision">Denied</result>
       <result name="Approver Name">Anakin Skywalker</result>
       <result name="Date">1999-05-19</result>
    </results>

The outer tag must be results, and all the inner tags are the singular result. The name is used to identify the result in a parameter in a node or connector farther down the tree. For example: <%=@results['Approval Create']['Approval Decision']%> would return "Denied" if the results above were used.

Messages are simpler because the format is plain text. You can also put the message directly in the parameters for it on the node (and take advantage of all the other options available to nodes, like values or results).

SampleMessages

An example of a node configured to Update when the connector fires

The options (Create, Update, and Complete) match when connectors fire.

Connectors and Deferrals

Update and Complete actions on deferred nodes can fire different connectors. Complete connectors are assigned by default and fire when the node is complete. However, there are two other types of connectors to use with deferred nodes.

The first type is the Create connector. This connector fires when the deferred node completes its action (for example, an approval or record creation) and then waits for a response (defers). Many workflows want to fire another action at this time. The Create Connector allows them to do this.

The second type is the Update connector. It fires when an Update action is sent to an instance of a deferred node. This connector is often used to send messages or keep customers informed of changes to a process that was started by a deferred node.

Below is a simple example tree using all three types of connectors: Create, Update, and Complete. You can distinguish them by the makeup of the arrow. Create connectors use a dotted line, Update connectors use a dashed line, and Complete connectors use a solid line.

SampleConnectors

Types of connectors