Building a workflow on the canvas

The canvas is a workflow’s page, where you build and change it. Its steps are drawn as a graph you edit in place, every change is kept as a draft until it is published, and every run of the workflow opens on the same picture. For what a workflow is and what its steps and triggers do, see Workflows.

Opening the canvas

Click a workflow on the Workflows page under Halon in the dashboard. The top line shows its name, which version you are looking at and whether it is live, when it runs, how many of Halon’s suggestions are waiting, and four views. Beside them are Run, which runs the live version now and asks the trigger’s questions first, and for an admin the switch that turns a published workflow on or off.

When runs were skipped because the workflow had already started its most runs per hour, a line under the top says how many in the last week, with each hour, how many were skipped in it and when the last one was. Raise Most runs per hour under Settings to let more start.

View	Shows
Editor	The steps as a graph, with the steps you can add on the left and the settings of what you select on the right
Runs	Every run of the workflow, test runs among them, newest first
Versions	Every version, with who changed what in each
Settings	What it can do, what the workflow’s own identity has been granted or still needs, then its settings, and Delete for one that never ran

On a phone the canvas is a list of steps in the order they run, and tapping a step opens its settings.

Adding and connecting steps

The left column, Add a step, lists everything you can add, grouped as triggers, Halon, incident, tell people, sandbox, HTTP, waiting, people, flow and the tools of each connected integration under its name, with a search at the top. Drag a step onto the canvas to place it, or click it to add it below the step you selected. Drop a step inside a For each box to run it once for every item.

To connect two steps, drag from the dot under one step to another. A step with routes has one dot per route, such as yes and no on a Branch, approved, denied and withdrawn on an Approval, done and not done on a Manual step, or each choice of an Ask a person, named with the words on its button, and each connection is labelled with its route. To take a connection away, select it and press its remove button, or the Delete or Backspace key.

Each step shows whether it only Reads or Changes something. A step that needs something the workflow has not been granted yet says Needs grant, which publishing grants, and a step held by an approval rule during a run says Waiting approval.

A step’s settings

Click a step to open its settings on the right.

• Name, which later steps use to refer to what it gave, such as {{steps.check_web.status}}. Every text field has a picker for the values earlier steps hand on, so you rarely type one by hand.
• The step’s own settings, such as how long a Delay waits, the conditions of a Branch, the list a For each goes through, the question an Ask Halon step asks, what a Watch follows, or the tool a step calls and what it passes. A step that changes something also says how a person puts the change back.
• Check it is still needed first, for a step that changes something. On by default, so in a run a schedule or something happening started, Halon checks the problem is still there before the change and skips the step when it has cleared. See Checking a change is still needed.
• Errors and retries, how many times a step is tried, how long it waits between tries, its time limit, and what happens when every try fails, which is to stop the run, carry on, or take an error route to a step of its own. An Ask a person, Approval or Manual step has no time limit here, since Wait for in its own settings says how long it waits.

Press Apply changes to keep what you changed, or Discard changes to drop it. Remove step asks before it takes the step and its connections away. Click the trigger to change what starts a run, such as the questions a run by hand asks first, the repeat and time zone of a schedule, or the date and time of a one off.

If someone else changed the same step since you opened it, your change is refused and the message says who changed it. Look at the step again and make your change on top of theirs.

Drafts, versions and publishing

Changing a live workflow opens a draft, and the live version keeps running as it was until the draft is published. Discard draft throws the draft away.

An admin publishes a draft with Publish, which names the draft’s version, such as Publish v3, and opens a dialog listing what publishing grants the workflow. The new version replaces the live one, and runs already going finish on the version they started on. A member presses Ask an admin to publish instead, and the admins get a direct message in Slack with Publish and a link to the canvas. Admins see the waiting requests above the canvas, each with Dismiss.

The Versions view lists every version with who made it and what they changed. Open one to look at it on the canvas, read only, and Back to the current version returns. Restore as a draft makes it the draft you work on. While a draft is open, restoring is refused with “Publish or discard the open draft first.”, so nothing in the draft is lost by accident.

Halon’s suggestions

When Halon suggests a change, such as after a run fails or when you ask it to, the change waits on the canvas until you decide.

• A step or connection Halon would add is dashed, and one it would take away is struck through.
• A changed setting shows the old value struck through beside the new one.
• Each suggestion has Accept and Dismiss, and the banner above the canvas says how many are waiting and where they came from, with Accept all and Dismiss all.

Changes by Halon in the canvas toolbar rings every step whose last change was Halon’s and lists Halon’s changes, each with Undo, and Undo all. Undo takes Halon’s change back out and keeps everything people changed around it.

Trying a workflow

Test run tries the draft, or the live version when there is no draft, before it goes live. The dialog asks for:

• answers to the trigger’s questions,
• what started the run, written as JSON or taken from an earlier run,
• which steps that change something should make their change for real. Every other change is shown, not made.

Press Start test run. The test runs as you, with what you may read.

Test this step in a step’s settings tries that step with only the steps before it. Each of those uses what it gave the last time a run reached it, so you can work on one step without running the whole workflow again.

To try the steps after one against an output you choose, pin it. Open a run, select the step and press Pin this output, or press Pin an output in the step’s settings to write one by hand. Test runs use a pinned output in the step’s place until you press Unpin, and published runs always run the step.

Following a run

Open a run from the Runs view, or from the run’s own link. The canvas draws the run read only, with each step’s state and how long it took, and the way the run went lit up. A step inside a For each counts its items.

With no step selected, the panel shows the run: what started it, what it handed back, its error, every step that was skipped because its problem had cleared with what Halon read, and what the run spent on AI and on its sandbox, beside its spending ceiling.

Select a step to see what it was given, what it gave, any result it kept whole under Kept whole, which opens in full, every call it made through the gateway, and its error if it failed. A Browser step shows the screenshot of each screen size it opened. A step that ran in the sandbox, such as Run command, Run script, Check from outside or Browser, says how long it used the sandbox and what that cost.

An Ask a person step waiting for an answer shows its question with its choices, or Answer for a short form, an Approval step shows Approve and Deny, and a Manual step shows its task with Done, which asks for its note when it has one. Someone who may not answer, decide or mark it done sees why when they point at the button. Once settled, the step says who answered or did it, and how.

Action	Does
Try again	Runs a failed step again
Skip	Moves past a failed or waiting step, and the run carries on
Start again from here	Starts a new run from this step, on the same inputs, with the steps before it using what they gave
Stop run	Stops a run that is still going, and every run it started
Pin	Keeps the run’s details however old it gets

Last run in the editor’s toolbar lays the newest run’s states over the steps you are editing.

Asking Halon beside the canvas

Press Ask Halon to open a chat beside the canvas about the workflow you have open. Ask it to explain what the workflow does, add or change steps, or look into a run that failed, for example “add a step that waits for the deploy to finish before checking”. Halon reads the workflow, and whatever it changes shows on the canvas as a suggestion you accept or dismiss.

The chat is one of your chats with Halon. New chat starts another, and the button beside it opens the chat in full, where anything Halon asks you to confirm is answered.