Change a ticket's state

Move a ticket between workflow states, close and reopen it, and understand what client users, email replies, and the reopen window can do.

Written for
user
Roles
owner, admin, member, project-manager, elevated-client-user, client-user
Requires
Owner or Admin on any ticket; a member of the ticket's project; any workspace user on an Inbox ticket; a regular client user only to the customer-resolve state on tickets they started
Feature
workflow

A ticket is always in exactly one state. States are defined per workspace and each one is either open or closed; the defaults are Backlog, To do, In progress, Review, and Done, with Done the only closed state. Changing the state is how a ticket is picked up, handed on, and closed.

Before you start

Role What you can do
Owner, Admin Any state on any ticket
Member, Project manager (on the project) Any state on tickets of their projects, and on Inbox tickets
Member not on the project Nothing
Elevated client user (on the project) Any state on tickets they can see on that project
Regular client user Only the customer-resolve state, and only on tickets they started

Steps

  1. Open the ticket.
  2. In the Details rail, choose the new state under State. The change is saved at once and the timeline shows "changed the state to Done".

On a board, dragging a card to another column, or choosing Move to… in the card's menu, does the same thing. See Use boards.

Rules

  • No fixed transitions. SAQ has no state machine: anyone who may change the state may choose any state, including straight from Backlog to Done and back.
  • Closing and reopening. Moving from an open state to a closed one records the closing time on the ticket. Moving back to an open state clears it. The closing time drives the reopen window below and the "as of period close" reports.
  • The customer-resolve state. Workspace settings name one closed state (Done by default) that a regular client user may set on tickets they started themselves; the state list on their ticket page offers only the current state and this one. An Owner or Admin can change or disable it under Settings → Workflow and kinds → Rules. When it is disabled, regular client users cannot change states at all.
  • Email replies reopen closed tickets. When a reply to a closed ticket arrives by email within the reopen window (14 days by default, configurable from 0 to 365 days), the ticket is reopened to the workflow's reopen-target state (Backlog by default) and the reply becomes a comment. After the window, an authorised correspondent's reply becomes a new follow-up ticket on the same project instead. A redacted ticket is never reopened.
  • Archived tickets. The state of an archived ticket cannot be changed; restore it first.
  • Notifications. A state change is emailed to the assignee, the reporter, and the viewers (except the person who made the change) whose preference is "Everything I can see". Regular client users are told about state changes on the tickets they started or view. People with "Mentions and assignments only" are not told about state changes.
  • Boards and lists. A state change counts as activity: the ticket moves to the top of the list and to its new column on the board.

Examples

A consultant finishes a deliverable, sets the state to Done, and the client's users get an email. The client replies to that email a week later; the ticket reopens to Backlog with the reply as a Shared comment.

A regular client user opens the ticket they reported, sees State offering only In progress (current) and Done, and selects Done to confirm the problem is solved.

Through the API: PATCH /api/w/acme/tickets/ACME-184 with {"stateId": "01924c3e-6b2a-7d11-9d0e-3a1f4b5c6d7e"}; state ids come from GET /api/w/acme/workflow. See the API reference.

Common problems

  • "You cannot move this ticket to that state." You are not on the ticket's project, or you are a regular client user choosing a state other than the customer-resolve state.
  • The card snapped back on the board. The state change was refused for the same reason; the error is shown above the board.
  • I closed a ticket and it reopened by itself. Someone replied by email within the reopen window. Read the new comment; if the work is done, close it again.
  • The state I want is not in the list. An Owner or Admin has archived that state under Settings → Workflow and kinds; existing tickets keep it, but it cannot be chosen anymore.
  • Use boards Read the workspace and project boards, filter them, and change state or assignee by dragging cards with the mouse or keyboard or from the card menu.
  • Update a ticket Edit a ticket's title, description, kind, priority, labels, dates, estimate, and assignee from the ticket page, and who may change each field.
  • Configure the workflow: states, kinds, priorities Define the states every board uses, the kinds tickets can have, and the priorities, plus the rules for inbound tickets, customer resolution, and reopening.
  • Email notifications Which events SAQ mails, who receives them by role and preference, how replies thread back to the ticket, and which mailbox sends them.
  • State A state is a ticket's position on the board; each state is open or closed, one open state is the reopen target, and one closed state may be the customer-resolve state.
  • Tickets List, read, create, update, move, archive, delete, and redact tickets through the SAQ REST API, with every filter, body field, response field, and error.