Build and publish a workflow
Lay out steps, fix issues, and publish an immutable version
A workflow is a reusable process. You edit one draft, and each publish creates a numbered version that never changes. Runs execute the latest published version.
Before you start
Start the app and open localhost:3001. If authentication is on, sign in first. You land on Workflows. With authentication off you are the local user.
Create a workflow
- Choose New workflow.
- Type a name and press Enter. Press Escape to cancel.
The builder opens with no steps.
Add steps
Steps sit on a canvas that reads left to right, with each step to the right of the steps it depends on. Choose Add step, or drag from a step's right edge onto empty canvas to add a step already connected to it.
Select a step to edit it in the drawer beside the canvas. Edits apply as you type, the canvas stays usable, and selecting another step switches the drawer to it. Close the drawer with X, Escape, or a click on empty canvas. The open step is part of the page address, so you can share or reload it. On a narrow window the drawer covers part of the canvas.
| Field | What it does |
|---|---|
| Name | The step's label. A new step's key follows the name until you save or edit the key. |
| Key | The identifier other steps refer to. Uses lowercase letters, numbers and single hyphens. |
| Owner | The person accountable for the step. |
| Executor | Who does the work. Same as owner is the default. |
| Purpose | What the step is for. |
| Inputs | Steps that come first, and which of their deliverables this step receives. |
| Deliverables | Slots of work the step produces: a document or a link. Req marks a required slot. |
| Gate | Approvals needed to finish the step. |
A key change takes effect when you press Enter, leave the field or save, and every step that refers to it updates. Press Escape to cancel it. A key that is invalid or used by another step stays in the field with an error and counts as unsaved until you fix or cancel it. Input description at the top says what a run needs to start.
To add an agent, open Executor, choose New agent, type a name and press Enter. It appears in every executor picker. Agents cannot be renamed or deleted yet, and names must be unique.
Connect steps and map deliverables
A connection makes a step wait for another step and passes it that step's work.
- Drag from a deliverable on the right of a step to the left edge of the next step to pass only that deliverable. Add more connections to pass more.
- Drag from the step's top-right handle to pass all of its deliverables.
- Connections that would create a cycle are refused.
To remove a connection, select it and choose X or press Backspace. Removing the last mapped deliverable from a step also removes the dependency.
Everything on the canvas can also be done in Inputs in the drawer. Check a step to depend on it, which passes all its deliverables, then check deliverables to narrow that down. Clearing every deliverable keeps the dependency and passes all of them again.
A brief includes only the deliverables a step receives. See Use the brief.
Arrange the canvas
Steps place themselves until you move one. Drag a step to arrange it, and every step keeps its place from then on. Positions save with the draft and do not affect runs or published versions. Tidy returns all steps to the automatic layout. Use the canvas controls to zoom or fit the view.
Gates
Without an override, a step uses its default gate:
- No approval when the executor is the owner.
- Approval by the step owner when someone else executes it.
Select Override to list approvals yourself, from the step owner, the run requester or a named person. Clear it to return to the default.
Move or remove steps
The arrows in the drawer change the step's number, which sets the order in run tables and within a canvas column. Remove also clears the step from every dependency and mapped input. Choose Undo in the message that follows to restore it and those connections. If another step has taken its key in the meantime, the step stays removed and a message explains why.
Save
Choose Save or press Cmd+S or Ctrl+S. A draft can be saved with publish issues, such as a missing owner, so you can finish it later. Fields that break a format or length limit, such as a key with spaces, must be fixed first. Save and publish stop there and focus the first one.
Publish
Choose Publish vN. Pending edits are saved first, then the next version is created. Publishing again without changes creates another numbered version. A message confirms Published vN with a link to it.
A published version cannot be changed or removed. To change the process, edit the draft and publish the next version.
Fix publish issues
The issue count in the top bar updates as you edit, and steps with issues are marked on the canvas. Choose the count to list every issue, then choose one to open its step and jump to its field. If a publish is rejected, no version is created and focus moves to the first issue.
| Issue | Fix |
|---|---|
| Add at least one step | Add a step. |
| Key used by another step | Give the step a different key. |
| Depends on missing step | Clear that dependency in Inputs. |
| Input no longer exists | Clear it in Inputs, or restore the deliverable it pointed to. |
| Owner required | Choose an owner. |
| Unknown owner, executor or approver | Choose someone who still exists. The field reads Unknown user or agent. |
| Needs a required deliverable or an approval | Mark a slot as required or add an approval. |
| Slot key used twice | Rename one of the slots. |
| Cycle | Remove one dependency from the listed loop. |
Read a published version
Open the version menu in the top bar and choose a version. The page shows that version as published, with who published it and when. Each step lists its deliverable slots with key, name, whether the slot is required, and description, and the deliverables it receives appear beside its dependencies. It does not change when you edit the draft. Choose Edit draft to return to the builder, or Start run to open the start form with this workflow selected. A run always uses the latest published version, so check the version number in the form if you opened it from an older one.
Recover from problems
- Save or publish failed: your edits stay on screen and stay unsaved. Choose Retry.
- This draft changed elsewhere: someone saved after you loaded the draft. Choose Load latest to take their version and lose your unsaved edits, or Overwrite to replace their changes with yours. Both ask for confirmation.
- Unwanted edits: choose Discard to return to the last saved draft.
- Leaving with unsaved changes: you are asked to confirm before leaving the builder.
- Could not load this page: choose Retry.
- Not found: the workflow or version does not exist. Follow the link back to Workflows.