> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Statuses

> Track ticket progress with flexible status system including system statuses and custom sub-statuses that can be assigned to specific forms

Statuses track ticket progress through your workflow. Use five system statuses as categories, then create custom sub-statuses underneath them for granular process management. Assign custom statuses to specific forms (Structured intake forms with custom fields) to match different workflows.

## Mental model

Status is a two-level system: five fixed system statuses and optional custom sub-statuses underneath them.

**System statuses (fixed, always available):**

| Status | Meaning | Active/Resolved |
| - | - | - |
| **Open** | New, unstarted ticket | Active |
| **In Progress** | Actively being worked on | Active |
| **Waiting** | Blocked on external input or dependency | Active |
| **Done** | Resolved, may need verification | Resolved |
| **Closed** | Fully completed and archived | Resolved |

Every ticket has exactly one status at any time. The default status for new tickets is Open.

**Custom sub-statuses** nest under a system status and provide granular tracking. A sub-status like "Needs Review" under "In Progress" inherits the system status semantics (still active, still in progress) while adding process detail.

Sub-statuses are workspace-scoped but form-gated: they must be explicitly assigned to specific forms before tickets using those forms can use them. Different forms can have different sub-statuses available, enabling form-specific workflows within the same workspace.

***

## Custom sub-status design patterns

Design sub-statuses around the distinct workflows in your workspace:

**Approval-heavy workflows (e.g., access requests):**

* Open → Pending Approval (under Waiting) → Approved (under In Progress) → Provisioned (under Done) → Closed

**Development workflows (e.g., bug reports):**

* Open → Investigating (under In Progress) → Fix in Progress (under In Progress) → Needs Review (under In Progress) → Done → Closed

**External dependency workflows (e.g., vendor requests):**

* Open → In Progress → Waiting on Vendor (under Waiting) → Vendor Responded (under In Progress) → Done → Closed

When designing sub-statuses, keep them scoped to the forms that need them. A "Needs Review" sub-status is relevant for bug reports but not for password reset requests. This prevents status dropdowns from becoming cluttered with irrelevant options.

***

## Status in automation

**Workflow triggers:** The "Status Changed" trigger fires when a ticket's status changes. You can filter on specific status transitions (e.g., only fire when status changes to Done).

**Workflow actions:** The "Set Status" action changes a ticket's status as part of a workflow. Use it for auto-progression (e.g., set to "In Progress" when assigned, set to "Done" when an approval is completed).

**Agent rules:** The agent can set ticket status based on conversation context. Common patterns:

* "When you resolve a user's issue, set the ticket status to Done."
* "If the user says they need to check with their manager, set status to Waiting."

**Status-driven patterns:**

* Trigger a CSAT survey when status changes to Done.
* Notify the requester when status changes from Waiting to In Progress.
* Auto-close tickets that have been in Done status for a configured period.

***

## Constraints and gotchas

* The five system statuses (Open, In Progress, Waiting, Done, Closed) cannot be renamed, deleted, or reordered. They are permanent.
* Custom sub-status labels must be unique within a workspace. Two sub-statuses cannot share the same label, even if they sit under different system status groups. Ravenna rejects any attempt to create or rename a sub-status to a label that's already in use.
* Custom sub-statuses must be assigned to forms before they can be used. Creating a sub-status alone does not make it available on any ticket.
* Deleting a sub-status that is still in use requires a target status. `ticketStatus.delete` and `requestTypeTicketStatus.delete` accept an optional `targetStatusId`; it is required whenever tickets still use the status being deleted (or removed from a form), and the request fails with `TARGET_STATUS_REQUIRED` otherwise. `targetStatusId` cannot be the status being deleted. For `ticketStatus.delete`, the target must be another status in the same workspace. For `requestTypeTicketStatus.delete`, the target must be a status the form still offers, and if the removed status was the form's default, the default is repointed to the target, or cleared when no target is given.
* Ticket migration during delete runs through the standard bulk-update pipeline inside a single transaction with the delete: timestamps, timeline entries, and status-based workflows fire as with a manual bulk change; when a target is given, deleted, unpublished, and merged tickets move in the same transaction; and a failure rolls back both the move and the delete. Migrations are capped at 500 tickets per delete (`TOO_MANY_TICKETS_IN_STATUS`).
* A sub-status inherits the semantics of its parent system status. A sub-status under "Done" is considered resolved regardless of its name.
* Tickets can transition between any statuses freely. There are no enforced status transition rules (e.g., you can go from Open directly to Closed). Enforce transitions through workflow logic if needed.
* Kanban board columns map to statuses. Each status (system or custom) becomes a column.
* Bulk status updates apply the same status to all selected tickets. If tickets span different forms with different available sub-statuses, only commonly available statuses will be selectable.
* Status changes are recorded in ticket history with timestamps. This data is available in analytics for tracking resolution times and workflow efficiency.


## Related topics

- [List statuses](https://docs.ravenna.ai/api/status/list-statuses.md)
- [List asset statuses](https://docs.ravenna.ai/api/assets/list-asset-statuses.md)
- [Reorder asset statuses](https://docs.ravenna.ai/api/assets/reorder-asset-statuses.md)
- [Workspace settings](https://docs.ravenna.ai/documentation/platform/workspaces/settings.md)
- [Configure](https://docs.ravenna.ai/documentation/automate/agents/configure.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.