Building Workflows

A workflow is a sequence of steps that automate one or more tasks. Workflows can include other workflows as steps, making them composable and reusable across different scenarios. They can be triggered manually, on a schedule, from a notification, or via the API. See Running Workflows for information on how to trigger workflows.

Workflow components

A workflow consists of the following:

Component	Description
Definition	Controls visibility, permissions, and grouping.
Inputs	Parameters passed to the workflow at execution time, for example credentials or a target system.
Types	Defines whether the workflow replaces a built-in Avantra task or runs before/after one. Defaults to Start/Stop/Restart.
Steps	The tasks the workflow performs — built-in steps, Step Library steps, or sub-workflows.
Outputs	Results that can be passed to a parent workflow.
Variants	Saved sets of input values for reuse at execution time. See Variants.
Schedules	Scheduled execution times. See Schedules.
Executions	Execution history and the interface for interacting with running workflows. See Monitoring Workflows.

Creating a workflow

1. Navigate to Automation > Workflows.
2. Click New.
3. Enter a Name and select a Namespace.
4. Optionally, select a Customer to control visibility and execution permissions.
5. Click Create.

Configuring steps

Steps are chained so each step can consume inputs from the workflow or outputs from previous steps.

Adding a step

1. Navigate to Automation > Workflows.
2. Double click on the workflow you wish to add a step to.
3. Go to the Steps tab.

note

Without an existing step selected, new steps are added at the end. Optionally, selecting an existing step allows you to determine the initial position of the new step.

4. Click + (add a new workflow step) to open the Add Workflow Step dialog.
5. Select a built-in step, Step Library step, or sub-workflow.
6. Update the Name field to reflect the step's purpose in this workflow.
7. Click OK to add the step and then configure the step parameters.

Step parameter sources

Each step input can be set from one of three sources:

• Constant value: A fixed value, useful when the same value is always needed (for example, a timeout).
• Workflow input: A value supplied by the user or parent workflow at execution time.
• Step output: A value produced by an earlier step in the workflow.

Configuring a step parameter

1. Navigate to Automation > Workflows.
2. Double click on the workflow you wish to alter.
3. Go to the Steps tab.
4. Double click on the step.
5. For each input, choose Constant value, Workflow input, or Step output and set the value.
6. Click Apply.

Importing and exporting workflows

Workflows can be exported and imported.

Importing a workflow

1. Click Import to open the import wizard.
2. Select which sub-workflows and steps to include.

Any sub-workflows or steps not included in the import must already exist in the target system.

Exporting a workflow

1. Select the workflows to export.
2. Click Export.
3. Enter a filename and choose whether to include sub-workflows, Step Library steps, and/or variants.
4. Click Export to download the file.

The export is a .zip file with the following structure:

steps/
  <namespace>/
    <step_name>.js
    <step_name>.json
variants/
  <namespace>/
    <workflow_name>/
      <variant_name>.json
workflows/
  <namespace>/
    <workflow_name>.json

Each step exports as two files, a .json file and a .js file. Name and namespaces can be changed by editing the files and repacking the .zip before importing.

Exporting execution results

You can download a .zip file containing a JSON record of every execution of the workflow, plus the step details from the most recent execution.

To download a workflow execution file:

1. With a workflow open, click the Executions tab.
2. Click Export execution results.

The download file is named __execution_<WorkflowID>__.zip. The JSON includes workflow-level fields (name, namespace, start / end times, status, inputs, outputs) followed by a steps array with the inputs and outputs for each step in the most recent execution, and an allExecutions array listing every execution from oldest to newest.

Example

{
  "workflowName" : "Workflow",
  "workflowNamespace" : "Namespace",
  "startTime" : "2024-11-06 16:16:31",
  "endTime" : "2024-11-06 16:17:05",
  "status" : "FINISHED_SUCCESSFUL",
  "customer" : "Root",
  "startedBy" : "User",
  "stoppedBy" : "",
  "variant" : "",
  "inputs" : [ {
    "name" : "number",
    "rawValue" : "1",
    "renderedValue" : "1"
  } ],
  "outputs" : [ {
    "name" : "result",
    "rawValue" : "Waited for 1 seconds.",
    "renderedValue" : "Waited for 1 seconds."
  } ],
  "steps" : [ { 
    "name" : "Wait",
    "inputs" : [ {
      "name" : "seconds",
      "rawValue" : "1",
      "renderedValue" : "1"
    } ],
    "outputs" : [ {
      "name" : "success",
      "rawValue" : "true",
      "renderedValue" : "true"
    }, {
      "name" : "message",
      "rawValue" : "Waited for 1 seconds.",
      "renderedValue" : "Waited for 1 seconds."
    } ],
    "startTime" : "2024-11-06 16:16:31",
    "endTime" : "2024-11-06 16:16:36",
    "status" : "FINISHED_SUCCESSFUL",
    "allExecutions" : [ {
      "startTime" : "2024-11-06 16:04:58",
      "endTime" : "2024-11-06 16:05:03",
      "inputs" : [ {
        "name " : "seconds",
        "rawValue" : "2",
        "renderedValue" : "2"
      } ],
      "outputs" : [ {
        "name" : "success",
        "rawValue" : "true",
        "renderedValue" : "true"
      }, {
        "name" : "message",
        "rawValue" : "Waited for 2 seconds.",
        "renderedValue" : "Waited for 2 seconds."
      } ],
      "status" : "FINISHED_SUCCESSFUL",
      "decision" : null
    } ],
    "children" : [ ],
    "confirmedBy" : null
  } ]
}

Execution statuses:

Status	Description
CREATED	Execution has been created but not yet started.
RUNNING	Execution is in progress.
WAITING_FOR_MANUAL	Paused at a manual step.
WAITING_FOR_RESUME_DECISION	Paused after a step failure, awaiting a decision.
FINISHED_SUCCESSFUL	Completed successfully.
FINISHED_MANUAL_STOPPED	Stopped manually before completion.
FINISHED_ERROR	Failed with an error.
FINISHED_SKIP	Completed by skipping a failed step.

Execution decisions (recorded in the decision field per step):

Decision	Description
WAITING	A decision is pending.
SKIP	The step was skipped; execution continued.
RETRY	The step was retried.
STOP	The step failed and execution was stopped.

Export execution logs

You can download a JSON log file for one or all executions, containing a timestamped record of every action performed.

To download a workflow execution file:

1. With a workflow open, click the Executions tab.
2. Select the workflow execution you wish to download a log file for.
3. To export a single execution, click Export execution log. The file is named <WorkflowID>_log.json.
4. To export all executions, click Export all execution logs. One file is downloaded per execution.

Defining inputs and outputs

note

This section is a placeholder — content to be written. (DOC-376)

Conditional branching (IF/ELSE)

Workflows support conditional branching using an IF/ELSE block. When the workflow reaches an IF/ELSE block, it evaluates a condition and executes either the if branch (condition is true) or the else branch (condition is false).

Adding an IF/ELSE block

1. Open a workflow and go to the Steps tab.
2. Click New > If block.
3. In the Configure if dialog, set the following:
   • Name: A name for this if block.
   • Reference id: An optional identifier for referencing the block elsewhere.
   • Condition: Required. A JavaScript expression that evaluates to true or false. If true, the if branch executes, otherwise the else branch executes. Step outputs and inputs are referenced using the step's reference id, for example step1.output.result == 'done'. Workflow inputs are referenced as workflow.input.<INPUT_NAME>.
   • If/Else outputs: Optional. Map named outputs to step outputs from each branch, with separate columns for Step output (if) and Step output (else). This makes results from either branch available to subsequent steps.
4. Click Apply.

Three rows are added to the steps list: If, Else, and Endif.

Adding steps to a branch

Steps are added to each branch by selecting a row within the branch and adding a new step in the normal way:

• To add a step to the if branch, select a row from the statement and add a step. It will be inserted between the If and Else rows.

note

IF/ELSE blocks can be placed inside a loop block to apply conditional logic within each iteration of a loop.

Loops

• Inline loop node: Loop over one or more steps within the same workflow without creating a separate workflow.
• Sub-workflow loop: Execute a separate workflow for each item in a system selector.

Inline loop node

An inline loop node allows steps within a single workflow to be repeated for each item in a set, without requiring a separate sub-workflow.

To add an inline loop:

1. In the Properties of a main workflow, select Inputs and click Edit.
2. Click Add a new row. Specify the new parameter's name and type, and select the default value from the dropdown menu.
3. Click Apply to save the changes.
4. Go to the Steps tab.
5. Click New > Loop block.
6. In the Configure loop dialog, set the following:
   • Name:A name for this loop node.
   • Reference id: An optional identifier for referencing the loop elsewhere.
   • Loop items set: Required. The set of items the loop will iterate over. Choose the source type:
     • Constant value (String): A fixed string value.
     • Constant value (System selector): A static system selector. The workflow runs for each system in the selector.
     • Workflow input: A value passed in at execution time.
     • Step output: A value produced by a previous step.
   • Execution mode: Sequential (each iteration completes before the next starts) or Parallel (all iterations run simultaneously).
   • Loop outputs: Map named outputs to step outputs to expose results from each iteration.
   • On Failure: What to do if an iteration fails: Continue, Stop, Stop - Ask to resume, or Retry.
7. Click Apply.
8. Add steps inside the loop block as you would in a normal workflow.

Loop results appear in the execution log and are included in execution export files.

Sub-workflow loop

Sub-workflows can be added as a loop step.

To add a sub-workflow as a loop:

1. In the Properties of a main workflow, select Inputs and click Edit.
2. Click Add a new row. Specify the new parameter's name and type, and select the default value from the dropdown menu.
3. Click Apply to save the changes.
4. In the Steps of a main workflow, click Add a new workflow step.
5. Select a Namespace in the workflow steps categories.
6. Select the workflow (WF) and tick the checkbox Execute in a loop.
7. Click OK to save.
8. Set the Loop item set, execution mode, and the action to be executed upon failure.
   Loop items set is the system selector for the loop set input, containing the systems for loops to be run on. The sub-workflow will be executed for each system in that system selector.
9. Click Apply.
10. In the main workflow's Properties section, click Apply.

note

There are two execution modes for sub-workflows:

• sequential (each iteration starts after the previous finishes)
• parallel (all iterations start at once).

The loop step produces a results output, which is a JSON array with one entry per iteration, each containing the result status, inputs, and outputs for that system:

[
  {
    "result": "EXECUTED",
    "inputs": {
      "sys": "server1 (5601, Server)"
    },
    "outputs": {}
  },
  {
    "result": "EXECUTED",
    "inputs": {
      "sys": "server2 (5602, Server)"
    },
    "outputs": {}
  }
]