Following runs and catching errors

In short: Every time a workflow starts, a run is created. In View > Runs you see each run on the canvas: which steps it went through, which exit it took, where it is now and what it is waiting for. A step that fails stops the run, unless you choose another step under If this fails. You can run a failed run again from the failed step.

Where to find this

Go to Account > Workflows, open a workflow and choose View > Runs. You need the role Organisation admin. For a workflow of the whole account you only see the runs in organisations you have access to.

In the Workflows list you also see Runs (7 days) per workflow with the number of failed and open runs. Colleagues without an admin role follow the run of one ticket in the workflow tab on the ticket (see The workflow tab on the ticket).

View a run

The Runs view of a workflow: on the left the list of runs with a coloured dot and status, in the middle the canvas with the steps passed highlighted and the Course of the run timeline, on the right the run details with the Try again from the failed step button (menu Account > Workflows, open a workflow, View > Runs).

1. On the left under Runs, choose a run. Each run has a coloured dot, the status and the start time. With the Refresh button you fetch the list again.
2. The canvas shows the run over the workflow, drawn as the version the run ran on. You see which steps it went through (and how often, with a repeat), which routes it took, where it is now and what it is waiting for.
3. You follow a run that is still going live (Live). With Camera follows the view moves along with the step the run is at. With Play again you play the run back step by step. The Course of the run timeline lets you go through the steps.
4. On the right are the details: the status, the start time, Waits until {moment} for a waiting run, a link to the ticket and the error if the run failed.
5. Click a step on the canvas to see what went in (In) and what came out (Out). If the run passed that step several times, choose which pass under Pass. A step whose turn it is shows Next up. A step the run did not pass shows This run did not come here. Click the top box for What started it: the fields of the event, as JSON. You also see the in and out of a step as JSON.

If a run is about confidential content you may not see (such as a recorded conversation), you only see the steps, routes and status, with the notice What the steps read and wrote, and their errors, is hidden: this run is about confidential content you may not see.

Why did the workflow (not) start?

In View > Runs, open the Latest events block. For the recent events of the trigger’s kind (the last 14 days) you see:

Statuses of a run

Per step you see Busy, Waiting, Done or Failed, and the exit the step took.

Waiting for a colleague

A step that puts work with a colleague puts it in To do and on the ticket (if the run belongs to a ticket):

The details then show Waiting for someone in To do or Waiting for someone in To do · expires {moment}.

• The default deadline for a question or proposal is 7 days; with Deadline (minutes) you set at most 30 days.
• An open item on a ticket that is closed expires by itself. The run then continues via expired.
• A task optionally has a deadline (Due in (minutes), at most 365 days); the run does not wait for it.

See Building blocks: people and To do.

Exits versus errors

There are two ways in which something does not work:

• An exit that says “did not work”. Many blocks have an exit such as failed (failed), none (none), not found or rejected (rejected). That is an ordinary route: under If failed you choose yourself what happens then. If you leave that exit empty, the run ends neatly as Done.
• A step that fails. A step cannot do its work, for example because a label no longer exists, a colleague no longer has access to the organisation, the run does not belong to a conversation, or the step’s AI agent has been switched off. Without a route under If this fails, the run then stops with the status Failed.

A step that does not work because of a temporary disruption is automatically retried by aishaa a number of times. Only if it keeps failing does the step fail.

If this fails (onError)

Every step has the field If this fails (technically onError). By default it says Stop the run. If you choose another step, the run goes there if this step fails.

• The failed step gets the exit error and the output { "error": "…" }. A later step reads the reason with {{<stepname>.error}}.
• Use this where a later step can still help, usually a Task or Ask a person for a colleague. Do not set it everywhere.
• A step cannot refer to itself under If this fails.

Example: a step that fetches data, with a task as a safety net.

{
  "trigger": { "event": "message.understood" },
  "steps": [
    { "id": "zoek", "block": "record.find", "label": "Find the customer's order",
      "inputs": { "kind": "order" },
      "exits": { "found": "details" },
      "onError": "hulp" },
    { "id": "details", "block": "record.read", "label": "Read the order",
      "inputs": { "read": "PLUGIN/LEESACTIE", "record": "{{zoek.recordId}}" },
      "onError": "hulp" },
    { "id": "hulp", "block": "task.create", "label": "Ask a colleague to take a look",
      "inputs": { "title": "Workflow could not read the order", "text": "Ticket {{trigger.ticket.number}}: {{zoek.error}} {{details.error}}" } }
  ]
}

A reference to a field that does not exist is filled in as empty in a text. That is why you can mention both error fields in the task.

Run a failed run again

Once you have solved the cause (a connected system works again, a colleague has access again), you do not need to wait for the next event:

1. Open the failed run in View > Runs.
2. Click Try again from the failed step.
3. You see The run goes again from the failed step. The run continues on its own version, with everything it already knew.

The failed step stays in the history. When you try again, an action in a connected system goes to that system as a new request. So first check whether the action really was not carried out the first time. The button is only there for a failed run that can go again, and not if the workflow has been deleted.

Never twice at once (concurrencyKey)

In the When panel, under Never twice at once for, you choose a field of the trigger, usually the ticket (trigger.ticketId). As long as a run is open for the same value (Running, Waiting or Paused), a new event for that value starts nothing.

• The new event is not kept for later: it simply does not start a run.
• Use this for workflows that wait a long time, such as a reminder after a few days, so that only one runs at a time per ticket.
• In JSON: "concurrencyKey": "trigger.ticketId". The key must be a field of the trigger.

Pausing and deleting during a run

• Pause: running runs wait at their next step with the status Paused. Resume continues them where they were.
• Delete: the workflow starts nothing any more. Open runs stay where they are.
• Publishing a new version does not change running runs: they finish on their own version.

Limits

A workflow never reacts to an event it caused itself.

Let a step do it itself from now on

A step that sends or carries out something as a proposal (Message to the customer, Forward by e-mail, Plugin action) counts how often in a row colleagues pass the proposal on unchanged. After 10 times in a row, someone who may change the workflow sees Do this itself from now on on the ticket (with Sent on as proposed {number} times in a row). After Yes, from now on, aishaa publishes the live version again, with only that step on execute at once. That is not possible while the draft has other unpublished changes. An edit, a rejection or an expired proposal resets the counter to zero, and so does a new version in which the step does something different. You set it back in the workflow itself.

Good to know

• You cannot stop a run by hand. Pause the workflow if runs must not continue.
• The Runs view refreshes by itself when something changes; if the connection misses a signal, the page reads the run again now and then.
• Failed runs do not get a separate notification. Look in the Workflows list for {number} failed under Runs (7 days).

Related

• The workflow tab on the ticket
• Create, test and publish a workflow
• References, routing, repeating and choosing
• Building blocks: people
• Triggers and events
• To do