Automation examples

Automations are a powerful way to perform complex, repeatable tasks automatically and without interaction to streamline processes, ensure consistency across multiple systems and allow the business to self-serve. We provide an API to allow access to this functionality from a remote system.

Executing a workflow

To execute a workflow, we need to provide the name and namespace of that workflow, which is a workflow's unique identifier, as well as a customer to define the systems that can be involved in a workflow.

Additionally, workflows can require inputs so that they run on the correct systems and with the correct parameters. These inputs can either be supplied directly or a variant can be provided (by ID).

For example, to execute the test.hello-world workflow, we can use this mutation:

mutation ExecuteWorkflow {
    executeWorkflow(
        input: {
            name: "hello-world"
            namespace: "test"
            customer: 1
            inputs: { key: "system-to-execute-on", value: "60" }
        }
    ) {
        result {
            success
            message
        }
        executions {
            id
            lifeCycleStatus
            executionStatus
        }
    }
}

This will return the following status information:

{
  "data": {
    "executeWorkflow": {
      "result": {
        "success": true,
        "message": null
      },
      "executions": [
        {
          "id": "14414",
          "lifeCycleStatus": "RUNNING",
          "executionStatus": "EXECUTING_STEP"
        }
      ]
    }
  }
}

The execution ID is important to record as this will allow us to use the next query to frequently check the current status of the workflow to determine when it succeeds, or report any errors.

Get the status of a workflow execution

As workflows could take anywhere from seconds to hours or days to execute (if they have manual steps waiting on an operator), the above mutation doesn't wait until the workflow completes, but simply returns with an ID that we can use to query the status in the future.

For example querying for execution ID 1554 using this query:

query WorkflowExecution {
    workflowExecution(id: "1554") {
        id
        lifeCycleStatus
        executionStatus
    }
}

This will return the following status information:

{
    "data": {
        "workflowExecution": {
            "id": "14414",
            "lifeCycleStatus": "WAITING",
            "executionStatus": "WAITING_ON_ERROR"
        }
    }
}

Get workflow step details

You can retrieve detailed information about each step in a workflow execution by using the root field. This returns the step execution tree. Each note has a children field that contains sub-steps. Available fields for a step are:

Field	Type	Description
id	ID!	Step identifier
name	String!	Step name
running	Boolean!	Whether the step is currently executing
confirmed	Boolean!	Manual confirmation state
resultState	Enum	EXECUTED, WORKFLOW_STOPPED, WORKFLOW_CONTINUED, MANUALLY_STOPPED, INTERNAL_FAILURE
resumeDecision	Enum	WAITING, SKIP, RETRY, STOP
startTime	DateTime	Step start time
endTime	DateTime	Step end time
executionCount	Int!	Number of times this step has run
inputs	[Property!]!	Step input parameters (key/value pairs)
outputs	[Property!]!	Step output values including messages (key/value pairs)
children	[WorkflowExecutionNode!]	Child steps (recursive)

For example, querying for execution ID 1234567 with step details:

query WorkflowExecutionWithSteps {
    workflowExecution(id: "1234567") {
        id
        lifeCycleStatus
        executionStatus
        root {
            id
            name
            running
            resultState
            startTime
            endTime
            inputs { key value }
            outputs { key value }
            children {
                id
                name
                running
                resultState
                startTime
                endTime
                inputs { key value }
                outputs { key value }
            }
        }
    }
}

Returns step details including timing, status, inputs and outputs:

{
    "data": {
        "workflowExecution": {
            "id": "1234567",
            "lifeCycleStatus": "FINISHED",
            "executionStatus": "FINISHED_SUCCESS",
            "root": {
                "id": "ROOT",
                "name": "Main Process",
                "running": false,
                "resultState": "EXECUTED",
                "startTime": "2026-02-27T14:35:16.000Z",
                "endTime": "2026-02-27T14:35:23.000Z",
                "inputs": [
                    { "key": "systemID", "value": "118" },
                    { "key": "FORCE_STOP", "value": "true" }
                ],
                "outputs": [],
                "children": [
                    {
                        "id": "c0294ab2-d737-42ca-9195-966bebc34127",
                        "name": "stop_cloud_server",
                        "running": false,
                        "resultState": "EXECUTED",
                        "startTime": "2026-02-27T14:35:16.000Z",
                        "endTime": "2026-02-27T14:35:23.000Z",
                        "inputs": [
                            { "key": "systemID", "value": "118" },
                            { "key": "FORCE_STOP", "value": "true" }
                        ],
                        "outputs": [
                            { "key": "success", "value": "true" },
                            { "key": "message", "value": "Successfully executed Stop for server." }
                        ]
                    }
                ]
            }
        }
    }
}

For workflows with nested sub-workflows, extend the children query recursively to retrieve deeper levels of the step tree.