Status Transitions

status_transitions is a list of dictionaries on your workflow class. Each entry defines one allowed move between two statuses.

Transition Properties

Key	Required	Description
name	Yes	Unique identifier — used in method names (<name>_condition, <name>_done)
display_name	Yes	Label shown on the action button in the UI
from	Yes	Status the record must be in for this transition to appear
to	Yes	Status the record moves to when the transition executes
description	No	Short description shown in the UI
confirmation_message	No	Confirmation dialog text shown before the transition runs
roles	No	List of role names that can trigger this transition — all roles if omitted
form	No	Form class to collect user input during the transition
is_manual	No	Set to False to hide from UI — system/automated transitions only

Basic Example

status_transitions = [
    {
        "name": "submit",
        "display_name": "Submit for Approval",
        "description": "Submit this record for manager review",
        "confirmation_message": "Submit for approval?",
        "from": "draft",
        "to": "pending",
    },
    {
        "name": "approve",
        "display_name": "Approve",
        "description": "Approve and activate the record",
        "from": "pending",
        "to": "active",
        "roles": ["Manager", "Admin"],   # only these roles see this button
    },
    {
        "name": "reject",
        "display_name": "Reject",
        "from": "pending",
        "to": "rejected",
        "roles": ["Manager", "Admin"],
        "confirmation_message": "Are you sure you want to reject?",
    },
    {
        "name": "reopen",
        "display_name": "Return to Draft",
        "from": "rejected",
        "to": "draft",
    },
]

Defining Statuses

In Meta, define every status with a colour and label. The on_create_status is required — it's assigned when a new record is created.

class Meta:
    model = Order
    on_create_status = "draft"
    statuses = {
        "draft":    {"color": "#717680", "label": "Draft"},
        "pending":  {"color": "#F59E0B", "label": "Pending Approval"},
        "active":   {"color": "#12B76A", "label": "Active"},
        "rejected": {"color": "#F04438", "label": "Rejected"},
    }

Common Patterns

Approval flow with rejection path:

draft → pending → active
              ↘ rejected → draft

Progressive lifecycle with rollback:

draft → review → testing → approved
                 ↘ review   (rollback)

Simple toggle:

active ⇄ inactive

Role-Restricted Transitions

Transitions without roles are visible to all roles with access to the view. Add roles to restrict:

{
    "name": "approve",
    "from": "pending",
    "to": "active",
    "roles": ["Manager", "Admin"],   # only Manager and Admin see this button
}

Roles must match the role names configured in your App Panel exactly.