Workflow definition language

Workbench Workflow Definition Language (WWDL) uses JSON and follows the schema outlined in this guide. The workflow is parsed at runtime by the WorkflowRunner class, prior to execution.

Workflow structure

Workflows are constructed as a sequence of stages. Each stage must run in sequence, however steps within a stage can run either independently of each other, in a loop or in batches (fan-out/fan-in).

Stages with a "when" condition will only run if the condition evaluates to True. The condition must follow Jinja syntax.

[
    {
        "name": "<stage-name>",
        "when": "{{<stage-condition>}}",
        "steps": [ <array-of-step-definitions> ],
    },
    {...}
]

Attribute	Required	Type	Description
name	Yes	String	Plain-language description of the workflow stage purpose.
when		Boolean	Jinja template that must evaluate to True for the stage to execute.
steps	Yes	Array	A list of steps in the stage that will be conditionally executed.

Steps

At present there are two types of step definitions: class-based and template-based. Both definition types possess the following common attributes:

{
    "name": "<step-name>",
    "when": "{{<stage-condition>}}",
    "depends_on": [ <array-of-step-names> ],
    "output": "<output-variable-name",
    "retries": <retry-limit>,
    "on_failure": "<step-failure-action>"
}

Attribute	Required	Type	Description
name	Yes	String	Plain-language description of the workflow stage purpose.
when		Boolean	Jinja template that must evaluate to True for the step to execute.
depends_on		Array	A list of steps in the stage that must complete before this one. Steps cannot be dependent on steps in another stage, as stages always run in sequence.
output		String	A key / variable name to use when storing results of the step in the workflow context dictionary. Steps with multiple outputs will be stored as a tuple at this variable name.
retries		Integer	Maximum number of unsuccessful attempts before terminating the step. Defaults to 0.
on_failure		String	If set to 'fail' then the workflow run will be forced to terminate if retries is exceeded. Else the step will silently fail and proceed to the next step. Defaults to 'fail'.

Class-based steps

Class-based steps (as the name implies) instantiate a class object and then (optionally) call a method of that class. Class-based steps have the following additional attributes:

{
    "class": "<workbench-class>",
    "instance_params": { "<workbench-class-keyword-arguments>" },
    "method": "get_item",
    "call_params": { <class-method-keyword arguments> }
}

Attribute	Required	Type	Description
class	Yes	String	The name of the Workbench class to instantiate. Must use dot notation to direct to the necessary Workbench sub-package, for example "bindings.DocumentVersion".
instance_params		Dictionary	A dictionary of key-value pairs denoting the keyword arguments to be passed to the class constructor. When referencing context variables, the variable key / name must be preceded by a "$".
method		String	The name of the class method to be called. Note: if no method is invoked and no "output" variable name is set then step execution will return nothing.
call_params		Dictionary	A dictionary of key-value pairs denoting the keyword arguments to be passed when calling the method. When referencing context variables, the variable key / name must be preceded by a "$".

Example: Generating a signed URL

This example uses the Workbench Azure Blob Storage client (which must be instantiated with organization, workspace and session arguments) to generate a signed URL to a blob.

{
    "name": "Get signed URL",
    "class": "clients.AzureBlobStorageClient",
    "dependsOn": [
        "Concatenate blob_name"
    ],
    "method": "get_signed_url",
    "instance_params": {
        "organization": "$organization",
        "workspace": "$workspace",
        "session_id": "$session_id"
    },
    "call_params": {
        "blob_name": "$blob_name"
    },
    "output": "signed_url"
}

Template-based steps

Template-based steps execute a Jinja template. This template can range in complexity anywhere from string concatenation through to method invocation. Template-based steps have the following additional attributes:

{
    "template": "{{<step-template>}}",
}

Attribute	Required	Type	Description
template	Yes	String	The Jinja template to evaluate.

Example: Initializing a session

This step will run only if a doc_version context variable (referencing an instance of the DocumentVersion class) is not already set. It will run after an earlier step titled 'Connect to session'.

{
    "name": "Get session documents",
    "when": "{{doc_version is not defined}}",
    "template": "{{session.initialize()}}",
    "dependsOn": [
        "Connect to session"
    ]
}