Skip to main content

# 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 run-wf.

## 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's where users can interact with a running workflow, for example to confirm a manual step or to fix an error. See Monitoring Workflows.

### Creating a new workflow​

1. Choose Automation > Workflows.
2. Click New.
3. Fill in the required fields Name with the name of the workflow and Namespace which is used to keep related workflows and steps together.
4. 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.
5. Click Create.

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.

### Adding a new step​

1. Choose Automations > Workflows.
2. Double click on the workflow you wish to add a step to.
3. Change to the Steps tab.
4. 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.
5. Press the + (add a new workflow step) toolbar button to open the Add Workflow Step dialog.
6. Choose a built-in step, a step library step or an existing workflow from the dialog.
7. The Name field is defaulted to the step name, however you should change this to reflect the purpose of the step in the workflow.
8. Click the OK button to add the step to the workflow.
9. The step configure window is now shown to assign any parameters to the step.

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:

- 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.
- 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 changes the amount of memory assigned to a virtual machine — the amount could be a workflow input.
- Step output
  Used when we have some calculation or built-in step before that works out the answer for this step to use in its processing. For example, using the built-in step to send a file then a subsequent step to execute that file.

### Configuring a step parameter​

1. Choose Automations > Workflows.
2. Double click on the workflow you wish to alter.
3. Change to the Steps tab.
4. Double click on the step.
5. 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 its outputs.
6. 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 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:

1. With a workflow open, click the Executions tab.
2. 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 – workflow is paused until a manual step is completed.
- WAITING_FOR_RESUME_DECISION – workflow is paused until a resume decision has been made.
- FINISHED_SUCCESSFUL
- FINISHED_MANUAL_STOPPED – workflow was finished because it was manually stopped.
- FINISHED_ERROR – workflow failed with an error.
- FINISHED_SKIP – 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" : [ {
        "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
      } ]
    }

All Executions lists every execution of the workflow, and is preceded 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 step 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​

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:

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

This downloads one JSON log file for each workflow execution.

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

Example

    {
      "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​

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

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

1. In the main workflow's Properties section, choose the Inputs subsection and click Edit to add/edit the input workflow parameter(s).
2. In the window that appears, 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.
3. In the main workflow's Properties section, choose the Steps subsection and click Add a new workflow step. In the window that appears, choose the Namespace in workflow steps categories, then select the workflow (WF) and tick the checkbox Execute in a loop. Click OK to save.
4. 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.
   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.

note

There are two execution modes for sub-workflows: sequential (each iteration starts after the previous finishes) and parallel (all iterations start at once).

5. In the main workflow's Properties section, click Apply.

The result of the loop step has an output called `results`, containing a JSON array with the execution details of each loop iteration of the sub-workflow, similar to:

    [
      {
        "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": {}
      }
    ]