A workflow is a set of statuses and the transitions allowed between them. An issue always sits in one status of the workflow of its issue type, and it can reach the next status only along a transition that exists.
A status and its category
A status has a name, which users read, and a category, which is how the product knows what the status means. There are three categories:
| Category | What it means |
|---|---|
TODO | the work has not started |
IN_PROGRESS | the work is under way |
DONE | the work is finished |
The name of a status belongs to the company: "In progress", "In review" and "With the client" are all IN_PROGRESS. The category exists for the places where the product reasons about statuses it has never seen: boards lay their columns out by category, and in QQL the statusCategory field answers "what is still open" whatever a company called its own statuses.
A DONE status has an explicit completion outcome: "Completed" or "Cancelled". Completed statuses use the completion color; cancelled statuses use a neutral color. Both remain DONE for filters, boards and reports. A status name does not define its outcome: naming it "Cancelled" is not enough.
Select a status in the workflow builder and choose its outcome in Properties. Changing an existing shared status applies to every workflow using it, and the builder explains that impact before publication. The affected workflows receive new revisions; old snapshots are not changed. A version conflict rejects the whole publication.
DONE statuses created before this setting retain their previous "Completed" outcome. If one means cancellation, an administrator explicitly chooses "Cancelled" and publishes the change. Status names, including names in other languages, are not classified automatically.
Statuses live at company level, not inside one workflow: the same "In progress" is reused across workflows, and renaming it renames it everywhere at once.
Transitions
A transition is a named arrow from one status to another. Its name is what a user reads on the button.
The rules checked when a workflow is saved:
- a transition has to change the status: an arrow from a status back to itself is rejected;
- two transitions with the same name between the same pair of statuses are not allowed;
- every status must be reachable from the initial one. A status that no chain of transitions arrives at is a dead end nobody enters, and a workflow holding one will not save.
The initial status is chosen explicitly: every new issue on this workflow is created in it.
A checklist is a reminder and not a gate on transitions: an issue moves to the next status with any number of items left unticked.
Draft and publication
A workflow is edited in the builder, and no live issue is touched until the draft is published. Publication is one action that validates the whole workflow and applies it.
Publishing requires the right to edit workflows and the version you were editing. If somebody else published the workflow while you were working, your publication is rejected as stale and does not overwrite theirs.
Before a live workflow changes, the builder says what will happen: how many existing issues the publication touches and how many new ones in the connected projects; a status that holds issues is not up for removal. A workflow's description is bounded by the company's short-text limit, 60 characters by default.
Revisions
Every publication is kept as a revision: a complete snapshot of the workflow at that moment, with an author and a time. Revisions are read-only and are not edited.
A revision stores the statuses and the transitions themselves as they were published, not references to the current ones. That is why a revision stays readable even after a status has been renamed.
Restoring an earlier revision
You can go back to an earlier version, and it works like this:
- open the revision you want and load it into the builder as a draft;
- the builder shows which version is in force and which number the publication will get;
- publish the draft, and it becomes the next version.
Nothing is overwritten. Restoring version 3 creates version 7; it does not wind the record back to three entries. That is deliberate: a record of workflow changes that can be rolled back stops being evidence of what happened.
Where a workflow is used
Beside each workflow the product shows how many projects run on it, how many issues sit in it, and whether or not it is the company's default workflow. That answers the question otherwise asked in chat: can this workflow be changed safely, and who would it affect.
A workflow can be deleted only while it is not the company's default and no project and no issue uses it; the delete button stays disabled until that holds. A delete must include the version you loaded.
What the trail shows
Creating a workflow, every publication, creating a status and archiving all land in the audit trail as separate records with an author and a time. A publication is found in the same place as everything else, with the same filters.