---
title: "Building a workflow on the canvas"
description: "Draw a workflow's steps on a canvas, try it with sample data, follow each run step by step, and ask Halon to change it beside you."
canonical: https://firefight.app/docs/ai/workflow-canvas
---

# 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](https://firefight.app/docs/ai/workflows.md).

## 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](https://firefight.app/docs/ai/workflows#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](https://firefight.app/docs/ai/workflows#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.