Building Workflows

In Avantra, workflows are defined as a collection of Steps that join these steps together to automate multiple tasks. A workflow can also contain other workflows to build even larger workflows and reuse workflows you’ve built before.

Workflows can also be scheduled or be triggered by notifications or externally through our API. See Running Workflows.

Workflow Concepts

A workflow is made up of the following components:

Definition

These settings control the visibility and permissions needed for executing this workflow and make it easier to group related workflows together.
Inputs

A workflow can be started with parameters that allow the user to customize the logic performed, for example use different credentials or choose the system to run the workflow on.
Types

Different types of workflows can replace an Avantra built-in task or perform their preconfigured actions before or after a task. The default selection is Start/Stop/Restart different systems, such as SAP System, Database, SAP Instance, etc.
Steps

These are the tasks that the workflow performs. Either our built-in steps, JavaScript Step Library steps or other workflows can be connected together here.
Outputs

If this workflow calculates a result and can be used inside other workflows, these outputs can be defined here.
Variants

If the workflow has input parameters, these values can be saved for future use to make executing workflows easier. See Variants.
Schedules

A workflow can be executed at defined times automatically by creating one or more schedules. See Schedules.
Executions

When a workflow is started the execution results are displayed here. Additionally it is where users can interact with a running workflow, for example to confirm a manual step or to fix an error. See Monitoring Workflows.

Procedure: Creating a new workflow

Choose Automation Workflows.
Click the New button.
Fill in the required fields Name with the name of the workflow and Namespace which is used to keep related workflows and steps together.
Optionally, select a value from the Customer drop-down menu. Selecting a customer affects the visibility of a workflow and the permissions required to execute it.
Click the Create button.

The workflow details will now open.

Configuring Steps

Firstly, we will go through the process of adding a step to a workflow. We then show the procedure for creating workflow inputs

Procedure: Adding a new step

Choose Automation Workflows.
Double click on the workflow you wish to add a step to.
Change to the Steps tab.
Without an existing steps selected, new steps are added at the end. Optionally, selecting existing step allows you to determine the initial position of the new step.
Press the + (add a new workflow step) toolbar button to open the Add Workflow Step dialog.
Choose a built-in step, a step library step or an existing workflow from the dialog.
The Name field is defaulted to the step name, however you should change this to reflect the purpose of the step in the workflow.
Click the OK button to add the step to the workflow.
The step configure window is now shown to assign any parameters to the step.

We will explain parameters next. Workflows steps are chained together so that the steps can use work performed or calculations of previous steps. This way steps can be reused in different combinations to do different tasks.

A step’s input parameters can either be:

Set to a Constant value

Useful when using a reusable step in a specific workflow that will only ever need a particular value for the input parameter. For example in restarting an SAP system, this is always the timeout to use.
Set to a Workflow input

Used when we would like the workflow to be generic and allow the user or parent workflow to select the option for this input parameter as it’s the main purpose of the workflow. For example a workflow that amount of memory assigned to a virtual machine - the amount could be a workflow input.
Set to a Step output

Used when we have some calculation or built-in step before that works out the answer for this step to use in it’s processing. For example using the built-in step to send a file then a subsequent step to execute that file.

Procedure: Configuring a step parameter

Choose Automation Workflows.
Double click on the workflow you wish alter.
Change to the Steps tab.
Double click on the step
For each input parameter, select either Constant value, Workflow input or Step output.
- for Constant value, enter the value in the text box shown
- for Workflow input, choose a created input from the dropdown
- for Step output, choose a previous step from the dropdown, then choose one of it’s outputs
Click the Apply button to save these changes and close the window.

Defining inputs and outputs

Import and export

To share workflows between systems the export and import buttons can be used.

Export

Select all workflows that should be included into the export and click on Export. Specify a filename and select whether sub-workflows, Step Library steps and/or variants should be included and click on Export. After that the export file is created and is downloaded.

File format

The export will create a zip will with the following folder structure.

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

Each exported step consists of two files. One contains the meta data (.json) and the other one contains the JavaScript code (.js).

It is possible to change names and namespaces and repack it to a zip file to change them before an import.

Export execution results

For workflows, a JSON file containing every execution of a workflow and the steps of the last workflow execution.

To download a workflow execution file:

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

This will download the workflow’s JSON execution results file.

The downloaded file will be in a .zip folder named execution_<WorkflowID>.

Example

The structure of the JSON file starts with listing the details of the latest execution of the workflow:

  "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."
  } ],

Statuses can be:

CREATED
RUNNING
WAITING_FOR_MANUAL - this means that the workflow is paused until a manual step has been completed.
WAITING_FOR_RESUME_DECISION - this means that the workflow is paused until a resume decision has been made.
FINISHED_SUCCESSFUL
FINISHED_MANUAL_STOPPED - this means the workflow was finished because it was manually stopped.
FINISHED_ERROR - this means the workflow failed with an error.
FINISHED_SKIP - this means the workflow finished due to a failing step being skipped.

The next section of the JSON file lists the steps of the most recent execution of the workflow.

  "steps" : [ { //only for latest execution
    "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."
    } ],

Steps consist of the inputs and outputs that are required to complete the step action.

To complete the JSON file, the sections allExecutions and children are listed.

    "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
        "confirmedBy" : null
  } ]
}

All Executions lists every execution of the workflow, and is precented by the start time, end time and execution status of the first execution of the workflow. The all executions section is listed from oldest to newest.

There are instances within an execution where a decision has to be made. Possible decisions are:

WAITING - this is for waiting statuses that require a decision to be made.
SKIP - this is when there a stepped is skipped, and the workflow continues with the next step.
RETRY - this is when a step is retried, usually done if the stap originally fails.
STOP - this is when a step fails with an error.

The children attribute lists steps that are completed in sub-workflows and loops.

Export execution logs

You are able to download JSON log files of each execution of a workflow as a log file. The JSON log file contains information about a single execution, such as 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. Click Export execution log.

This will download the workflow’s JSON log file for that execution. The filename will be <WorkflowID>_log.json.

If there are multiple executions and you want to download logs for every execution:

With a workflow open, click the Executions tab.
Click Export all execution logs.

This will download a number of JSON log files, with the amount downloaded equal to the number of executions there have been of a workflow.

The JSON file lists every action that is done within a workflow.

Example

The structure of the JSON file starts with listing the details of the latest execution of the workflow:

{
  "id" : 33301,
  "name" : "Workflow",
  "namespace" : "Namespace",
  "start" : "2024-11-06T15:04:58.000+00:00",
  "end" : "2024-11-06T15:05:03.000+00:00",
  "log" : [ {
    "number" : 1,
    "logLevel" : 2,
    "node" : null,
    "msg" : "Triggered by user  USER (2024-11-06 16:04:58) with no variant. (Customer: Customer)",
    "timestamp" : "2024-11-06T15:04:58.000+00:00"
  },
  .
  .
  .
  {
    "number" : n,
    "logLevel" : 2,
    "node" : null,
    "msg" : "Workflow ended successfully at 2024-11-06 16:05:03\n\nWorkflow Outputs:\n-------------\nresult -> 'Waited for 2 seconds.'",
    "timestamp" : "2024-11-06T15:05:03.000+00:00"
  } ]
}

Import

To start the import wizard click on Import. If a workflow consists of sub-workflows and steps and if they are included in the file they can be selected in the import wizard. If steps or sub-workflows are not imported steps or workflows with the corresponding names must be present in the system.

Loops in workflows

The sub-workflows can be added to a workflow as a loop step.

To add a sub-workflow as a loop, follow the next steps:

In the main workflow’s Properties section, choose the Inputs subsection and click Edit (framed in red) to add/edit the input workflow parameter(s).
In the window that appeared, click Add a new row. Specify the new parameter’s name and type, and select the default value from the dropdown menu. Click Apply to save the changes.
In the main workflow’s Properties section, choose the Steps subsection and click Add a new workflow step. In the window that appeared, choose the Namespace in workflow steps categories, then select the workflow (WF) and tick the checkbox Execute in a loop (framed in red). Click OK to save the changes.

In the next window, specify the loop item set, execution mode, and the action to be executed upon failure. Click Apply to save the changes.

The 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.

There are two execution modes for sub-workflows: sequential and parallel. In sequential mode, the next iteration will start if the previous one is finished. In parallel mode, all iterations are started in parallel at once.

In the main workflow’s Properties section, click Apply.

The result of the loop step will have an output called results containing a JSON file with the execution details of each loop iteration of the sub-workflow, similar to the example below:

[
  {
    "result": "EXECUTED",
    "inputs": {
      "sys": "server1 (5601, Server)"
    },
    "outputs": {}
  },
  {
    "result": "EXECUTED",
    "inputs": {
      "sys": "server2 (5602, Server)"
    },
    "outputs": {}
  },
  {
    "result": "EXECUTED",
    "inputs": {
      "sys": "server11 (5611, Server)"
    },
    "outputs": {}
  },
  {
    "result": "EXECUTED",
    "inputs": {
      "sys": "server12 (5612, Server)"
    },
    "outputs": {}
  },
  {
    "result": "EXECUTED",
    "inputs": {
      "sys": "server13 (5613, Server)"
    },
    "outputs": {}
  }
]