Task Workflow
Route: /org/taskconfig?tab=workflow · Manage permission: Manage Task Status
1. What the workflow is
The workflow is a graph of permitted status changes. Statuses says which states exist; the workflow says which state may follow which.
It is drawn on a canvas: one node per status, plus a single Start node marking where a new task
enters. An arrow from To Do to In Progress means that move is legal. No arrow means it is not.
| Statuses tab | Workflow tab (this page) | |
|---|---|---|
| Defines | The states | The moves between them |
| Shape | A sortable list | A node graph |
| Adding a status | Creates it | Shows it as an unconnected node |
| Permission | Manage Task Status | Manage Task Status — the same one |
Creating a status on the Statuses tab does not connect it to anything. The node appears here alone, and no task can enter or leave it until you draw an arrow.
This is the single most common cause of "I made the status but nobody can use it".
2. How the workflow spreads across the application
The workflow decides whether the move is possible. The Change Status of Task permission decides whether this user may make it. A user without that permission sees the status control but cannot change it, however the graph is drawn.
3. Drawing a workflow — step by step
Step 1 · Open the canvas
The canvas fills the section. Around it:
| # | Element | Where |
|---|---|---|
| 1 | Toolbar — JSON, Clear, Save | Top right |
| 2 | Legend — blue = Input (Target), green = Output (Source) | Top left |
| 3 | AI Assistant panel | Bottom left |
| 4 | Zoom controls and minimap | Bottom |
| 5 | Full screen button | Top right of the section, outside the canvas |
It reads "Optimization suggestions coming soon." — it is a placeholder, not a disabled feature. There is no AI generation on this canvas today.
Step 2 · Connect the Start node
The Start node is a blue circle with a single green output handle. Drag from it to the status a new task should begin in.
Attempting a second one is refused with Start Node Limit — "Start node can only connect to one status." Saving without any is refused with Validation Error — "'Start' node must be connected to a status."
Step 3 · Draw transitions
Each status node carries eight handles — an input and an output on all four sides:
| Handle colour | Type | Meaning |
|---|---|---|
| Blue | Target | Something can arrive here |
| Green | Source | Something can leave here |
Drag from a green handle to a blue one. The arrow is animated and directional. Orbit picks the tidiest pair of handles for you, so the arrow re-routes as you move nodes.
Duplicate arrows between the same two nodes are silently ignored.
Step 4 · Or use the side panel
Clicking a node opens a panel on the right showing the status, its description, and Allowed Next States — every other status with a tick beside it if a transition exists. Clicking a row toggles that transition on or off.
The panel lists every other status with a tick beside it where a transition already exists. Clicking a row toggles that transition on or off, which is the same edit as dragging an arrow but without the aim.
Dragging is faster for two or three statuses. Once you have six, the ticklist is far less error-prone — and it is the only way to see, at a glance, which moves a status does not allow.
Step 5 · Configure a transition
Clicking an arrow opens the transition panel: source status, target status, and two collapsible groups — Actions and Conditions, the latter behind an Allow Conditions toggle.
Source and target are fixed — a transition is redrawn, not re-pointed, from here. Actions run when a task makes the move; Conditions, behind the Allow Conditions toggle, can block it before it happens.
Step 6 · Save
Save validates the Start node, then writes the whole graph — nodes, edges, and a derived adjacency map of permitted targets per status.
Clear removes every arrow at once (All connections cleared) and leaves the nodes in place.
Nothing is saved until you press Save, so a mistaken Clear is recoverable by leaving without saving.
4. Field reference
Toolbar
| Button | Shown when | Does |
|---|---|---|
| Exit | In full screen only | Leaves full screen |
| JSON | Always | Toggles a raw view of the saved graph. Includes a copy button — JSON copied to clipboard |
| Clear | If you can manage | Removes all arrows. Toast: All connections cleared |
| Save | If you can manage | Validates and persists |
Transition actions
Actions run when a task makes this transition.
| Action | Configuration fields | Shown when |
|---|---|---|
| Create Developer Task | Task Title (Follow up on ticket), Task Description, Task Priority | Only if the organization has the task package |
| Send Document to Requestor | Document to Send | Always |
| Send Status Summary | Message template | Always |
| Create Calendar Event | Event Title (Review session), Event Description | Always |
| Email Status Report | Target Email Address ([email protected]), Subject Line, Report Message Body | Always |
Transition conditions
Conditions are evaluated before the transition and can block it. They are only editable with Allow Conditions on.
| Condition | Options |
|---|---|
| SLA Breach Guard | Prevent transition if SLA is Breached · Allow transition ONLY if SLA is Breached |
| Current Status Block | Pick the statuses a transition may not originate from |
| Assignee Requirement | Ticket must have an assigned Agent · Ticket must NOT have an assigned Agent |
| Allowed Ticket Priorities | Multi-select of priorities |
The labels say ticket, agent and SLA because these condition types are shared with Orbit Resolve. On a task workflow, read ticket as task and agent as assignee.
The SLA Breach Guard has nothing to drive it on a task workflow — tasks have due dates, not SLA clocks. Setting it here is not useful.
Validation
| Rule | Message |
|---|---|
| Start must be connected | 'Start' node must be connected to a status. |
| Start may have one connection | 'Start' node can only have one outgoing connection. |
| Start connection attempt beyond one | Start node can only connect to one status. |
Nothing validates that every status is reachable, that a Done status exists, or that the graph has
no dead ends.
5. The admin contract
| Prerequisite | Why |
|---|---|
| Page Access of Task Configuration | Page access |
| Manage Task Status | Manage — shared with the Statuses tab |
| At least one status | With none, there is nothing to connect but the Start node |
| A desktop browser | See below |
On a mobile viewport the section renders a desktop-only fallback instead of the canvas. Every other configuration tab works on a phone; this one does not.
6. Downstream
| Change | Effect |
|---|---|
| Add an arrow | That status change becomes available in the task detail control and as a Kanban drop |
| Remove an arrow | The move disappears from the control. Tasks already in that status stay there |
| Move the Start node's arrow | Only affects newly created tasks |
| Add an action | Runs on every future transition along that arrow |
| Add a condition | Can block the transition for everyone |
| Delete a status on the Statuses tab | Its node and arrows vanish from the graph |
7. Don't confuse this with…
| Thing | Where | Why it is different |
|---|---|---|
| Task workflow (this page) | ?tab=workflow | Per project, status transitions for tasks |
| Statuses | ?tab=statuses | Defines the nodes this canvas draws |
| Resolve statuses & workflows | Resolve settings | A separate graph for tickets, with version history. This canvas has none |
| Module State Management | Organization Settings | Approval-gated state machines for other modules |
| Approval workflows | Organization Settings | Who signs off, not which state follows which |
Orbit Resolve keeps versions of its workflow and reconciles in-flight tickets when one changes. The task workflow does not: a save replaces the graph, and tasks sitting in a status whose arrows you just removed simply stay where they are.
8. Troubleshooting
| Symptom | Cause |
|---|---|
| Cannot save | Start is unconnected, or has more than one arrow |
| A new status cannot be used | It has no arrows yet |
| Second arrow from Start refused | Start allows exactly one |
| A user cannot change status though the arrow exists | They lack Change Status of Task |
| A Kanban drop is rejected | No arrow between those two statuses |
| The canvas is blank on mobile | Desktop-only fallback |
| The canvas has almost no height | It needs a sized parent; use Full screen |
| Arrows vanished after editing statuses | Deleting a status removes its node and arrows |
| SLA condition never fires | Tasks have no SLA clock — that condition is Resolve vocabulary |
Related
- Statuses — the nodes on this canvas
- Kanban board — where a drop is a transition
- Task detail — the status control and Change Status of Task