Automation run inspector

automation.run-inspector@1

Shows one run of an automation: where it is, what each step did, what it produced and what went wrong. It reads and changes nothing. It needs a key with Read automations.

Look at a run

Replace YOUR_FEATURE_ID with the featureId this operation's catalogue entry gives, and YOUR_RUN_REF with a run's runRef from Find automation runs.

# A new operationId for each new request; the same one to retry it.
curl https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations \
  -H "Authorization: Bearer gl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "featureId": "YOUR_FEATURE_ID",
    "export": "runInspector",
    "contractRef": "automation.run-inspector@1"
  },
  "operationId": "inspect-run-1",
  "input": {
    "runRef": "YOUR_RUN_REF"
  }
}'

// A new operationId for each new request; the same one to retry it.
const response = await fetch(
  "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer gl_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "target": {
        "featureId": "YOUR_FEATURE_ID",
        "export": "runInspector",
        "contractRef": "automation.run-inspector@1"
      },
      "operationId": "inspect-run-1",
      "input": {
        "runRef": "YOUR_RUN_REF"
      }
    }),
  },
);
const receipt = await response.json();
console.log(response.status, receipt);

import requests

# A new operationId for each new request; the same one to retry it.
response = requests.post(
    "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
    headers={"Authorization": "Bearer gl_YOUR_API_KEY"},
    json={
        "target": {
            "featureId": "YOUR_FEATURE_ID",
            "export": "runInspector",
            "contractRef": "automation.run-inspector@1",
        },
        "operationId": "inspect-run-1",
        "input": {
            "runRef": "YOUR_RUN_REF",
        },
    },
    timeout=30,
)
print(response.status_code, response.json())

Parameters

What goes in input:

Name Type Required Description
runRef string Yes The run to show: its runRef from Find automation runs.

Response

A call that worked answers 200 with an applied receipt; its output holds these fields, among others. GET /catalog/automation.run-inspector@1 answers the complete shape as JSON Schema.

Name Type Description
runRef string The run's reference.
revision integer The run's revision. Send it as expectedRevision to Suspend, Resume or Cancel so a change you did not see is never overridden.
featureId string The feature the run belongs to.
source object The automation or built-in setup the run follows.
source.kind one of preset, workflow preset for a built-in setup, workflow for an automation of your own.
source.ref string Its reference.
state one of preparing, queued, running, waiting, needs-input, suspended, succeeded, completed-with-errors, failed, uncertain, cancelled Where the run is: preparing, queued, running, waiting, needs-input, suspended, succeeded, completed-with-errors, failed, uncertain or cancelled.
parentRunRef null or string The run that started this one, or null.
output any JSON value What the run produced so far; its shape depends on the automation.
diagnostics array of object Problems the run met, each with a code, the path it is about and a message.
nodes array of object The run's steps, in order.
nodes[].id string The step's name in the automation.
nodes[].state one of ready, running, waiting, succeeded, failed, uncertain, cancelled ready, running, waiting, succeeded, failed, uncertain or cancelled.
nodes[].generation integer How many times the step has been started afresh (a step that repeats counts up).
nodes[].operationId null or string The operationId of the call the step made, or null.
nodes[].receipt null or object The receipt that call answered, or null.
nodes[].items array of object For a step that handles a list, each item and where it is.
nodes[].waiting object Present while the step waits: for an event (await), a time (wait) or a choice (exit).
nodes[].waiting.deadline string (date-time) When the wait ends on its own. 
{
  "status": "applied",
  "operationId": "inspect-run-1",
  "output": {
    "runRef": "11111111-2222-4333-8444-555555555555",
    "revision": 3,
    "businessProfileId": "YOUR_BUSINESS_ID",
    "featureId": "juniper-cakes.automations",
    "source": {
      "kind": "workflow",
      "ref": "YOUR_AUTOMATION_REF"
    },
    "state": "succeeded",
    "parentRunRef": null,
    "output": {},
    "diagnostics": [],
    "nodes": [
      {
        "id": "send-thanks",
        "state": "succeeded",
        "generation": 1,
        "operationId": "send-thanks-1",
        "receipt": null
      }
    ]
  }
}

Errors

It reads and changes nothing. Besides the answers every request can get (Errors), its receipt can say:

Status HTTP What it means
rejected 400, or 403 when it's a matter of access Not done. diagnostics says why: each has a code, a path into what you sent and a message.

The codes in diagnostics you're most likely to see:

Code Status What it means
AUTOMATION.RUN_NOT_FOUND rejected No such run here for this key.
AUTOMATION.RUN_MOVED conflict The run changed while it was being read. Read it again.
AUTOMATION.GRAPH_NOT_EXECUTABLE rejected The automation this run follows can no longer be read, so the run cannot be shown.