# Building a workflow

The builder is a canvas. Tasks are cards; prerequisites are the lines between
them. You lay the process out visually, then publish it.

## 1. Create the workflow

**Workflows -> New workflow.** Three things:

- **Name** -- what people call the process.
- **Key** -- a URL-safe slug, unique in your organization. Lower case, letters,
  numbers and dashes: `prod-deploy`.
- **Description** -- optional, one line, shown on the workflow card.

**Create and open builder** takes you to the canvas.

## 2. Add tasks

**Add task** in the bar at the top drops a new card on the canvas. Drag cards
around freely -- position is saved, and the layout is how people read the process
later, so it is worth arranging deliberately: earlier work higher up, parallel
work side by side.

## 3. Connect them

Every card has a small handle on its top and bottom edge. Drag from the **bottom**
of one task to the **top** of another to say *this one waits for that one*.

The line you have drawn is a [prerequisite](prerequisites.md). Two tasks dragged
from the same predecessor both become available at once -- that is how you express
work that happens in parallel.

The bar at the top counts what you have: "6 tasks - 6 prerequisites".

## 4. Fill in each task

Click a card and the editor opens on the right:

- **Title** -- what you are asking for.
- **Instructions** -- how to do it, and how to tell pass from fail. Formatting is
  available. Optional, but this is the field that makes a workflow usable by
  someone who did not write it.
- **Assigned to** -- people and [groups](groups.md), or leave it empty for anyone.
  See [how assignment works](assignment.md). **Manage groups** next to it opens the
  group editor.
- **When ready** -- where this task sends its work when it becomes available. Only
  relevant if your organization has set up connections; leave it alone otherwise.
- **Fields** -- what the task asks you to record. See [Fields](fields.md).
- **Delete this task** -- at the bottom of the panel.

## 5. Save

Changes are not live until you save them. A bar appears while you have unsaved
work, with **Save changes** and **Discard**.

Saving is not publishing. It stores the current state of the canvas so you can
come back to it.

## 6. Preview

**Preview** shows the workflow as a checklist, without generating a real one and
without touching your data. Use it to check the order reads correctly and the
instructions make sense before anyone runs it for real.

## 7. Publish

**Publish** raises the workflow's version -- v3 becomes v4 -- and makes that version
what new [checklists](checklists.md) are generated from.

Two things worth knowing:

- You have to save before you can publish. The button stays disabled while there
  are unsaved changes.
- Publishing does not touch checklists already in flight. They stay pinned to the
  version they were generated from and finish it. See
  [Checklists](checklists.md).

If the workflow has a problem that makes it unrunnable -- a loop where two tasks
wait on each other -- publishing is refused until you fix it.

## Then

Go to [My work](my-work.md) and generate the first checklist from it.

## Next

- [Prerequisites](prerequisites.md)
- [Fields](fields.md)
- [Checklists](checklists.md)