Workflow definition object

A Workflow Definition is represented by a JSON Object.

The operation of a workflow definition is specified by tasks, which are represented by JSON objects, fields in the top-level "tasks" object.

Here is an example workflow definition with one task named "Hello World".

{
  "name": "Hello World",
  "description": "A simple minimal example of a workflow definition",
  "startTask": "Hello World",
  "tasks": {
    "Hello World": {
      "type": "Simple",
      "end": true
    }
  }
}

When this workflow definition is started, the system begins execution by identifying the Start Task. It executes that task, and then checks to see if the task is marked as an end task (identified by "end": true). If it is, the workflow terminates and returns an output. If the task is not an end task, the system looks for a "nextTask" field to determine what task to run next; it repeats this process until it reaches a Terminal Task or a runtime error occurs.

In this example, the workflow contains a single task named "Hello World". Because "Hello World" is a Simple Task, the system schedules it until it is completed by a user or remote worker. Assuming the task completes successfully, the workflow will terminate successfully.

Workflow definition fields

Task definitions object

Tasks are represented as fields of the top-level "tasks" object.

The task name, whose length must be less than or equal to 80 Unicode characters, is the field name; task names must be unique within the scope of the whole workflow definition.

The following task names are reserved:

• workflow

Here is an example Simple task:

"Hello World": {
  "description": "Simple task to be executed by a user or SimWorkflow API",
  "type": "Simple",
  "nextTask": "Next Task"
}

Task definition fields

Many fields can appear in more than one task type. The table below summarizes which fields can appear in which tasks. It excludes fields that are specific to one task type.

Task input parameters

Task input parameters is a JSON fragment of key-value pairs containing the mapping values from input or output of another task during the execution. Parameters include data fields and attachments.

Here is an example of task input parameters:

"inputParameters": {
  "${...}": "${jsonata:$merge(*.output)}",
  "attachments": "${jsonata:$merge(*.attachments)}",
  "key": "SWF-${swf:sequenceNumber}"
}

The above example would:

• Merge all the executed task outputs and expand the result to the inputParameters.
• Merge all the executed task attachments and assign them to the field attachments.
• Assign the key field with a string prefix SWF- and the sequence number of the workflow. Example:
  • SWF-1 for the first workflow run;
  • SWF-2 for the second workflow run;
  • SWF-3 for the third workflow run; and so on.

In SimWorkflow, certain parameter name prefixes are reserved for specific purposes. Understanding these prefixes and syntax conventions is crucial for effective workflow design. Here's a breakdown of the reserved prefixes and syntax rules:

Reserved prefixes:

• swf:: Reserved for internal SimWorkflow parameters and variables.

• jsonata:: Used for JSONata expressions, an advanced query and transformation language.

• ${...}: Represents a spread syntax, allowing an iterable (e.g., array or string) to be expanded in specific contexts.

• ${swf:sequenceNumber}: Represents the unique sequence number assigned to the workflow within the workflow definition. This sequence number is specific to the workflow definition and serves as a unique identifier for each instance of the workflow.

JSONPath expression syntax:

• JSONPath expressions for task input and output must be enclosed within ${...} placeholders.

• To escape a JSONPath expression, prefix it with an extra $ character, e.g., $${...}.

• JSONPath expressions enable precise querying and manipulation of JSON data structures. See JSONPath for more information about JSONPath.

JSONata expression syntax:

• JSONata expressions are prefixed with jsonata: within ${...} placeholders, e.g., ${jsonata:...}.

• JSONata is a powerful transformation language used for querying and transforming JSON data. See JSONata for more information about JSONata.

Referencing workflow inputs:

• Workflow inputs are referenced using ${workflow.input}.

Referencing task inputs and outputs:

• Task inputs and outputs are referenced using ${<TASK_NAME>.input} and ${<TASK_NAME>.output} respectively.

Referencing task attachments:

• Task attachments are referenced using ${<TASK_NAME>.attachments}.

Referencing workflow definition variables:

• Workflow definition variables are referenced using ${['swf:variables']} or ${['swf:variables'].${<VARIABLE_NAME>}}.

Examples of acceptable expressions:

• ${workflow.input.title}

• ${TaskName.input.title}

• ${['Task Name'].output.title}

• ${swf:sequenceNumber}

• ${jsonata:$now()}

• ${jsonata:$merge(*.output)}

• ${['swf:variables'].cursor}

• ${['Task Name'].attachments[0].id}

Task definition types