Doctype States & Status Fields

Frappe has three separate but related mechanisms for tracking document status. Understanding their interplay is critical for correct workflow implementation.

The status Field

A standard Select field on the DocType that represents the human-readable status:

{
    "fieldname": "status",
    "fieldtype": "Select",
    "label": "Application Status",
    "options": "Pending\nApproved\nRejected\nCanceled",
    "default": "Pending",
    "allow_on_submit": 1,
    "in_list_view": 1,
    "in_standard_filter": 1,
    "no_copy": 1
}

Key properties:

• allow_on_submit: 1 — Can change after document submission (critical for workflow-driven status changes)

• in_standard_filter: 1 — Adds a filter dropdown in list views

• no_copy: 1 — Status resets when duplicating the document

The workflow_state Field

A hidden Link field to Workflow State, managed by Frappe's workflow engine:

{
    "fieldname": "workflow_state",
    "fieldtype": "Link",
    "options": "Workflow State",
    "hidden": 1,
    "read_only": 1,
    "allow_on_submit": 1,
    "search_index": 1
}

This field drives automatic transitions and email notifications when a Workflow is configured for the DocType.

The states Array (Indicator Colors)

The states array in the DocType JSON definition maps state titles to colored indicator dots displayed in list views and form headers:

{
    "states": [
        {"color": "Yellow", "title": "Payment Pending"},
        {"color": "Orange", "title": "Payment Requested"},
        {"color": "Blue",   "title": "Payment Received"},
        {"color": "Green",  "title": "Approved"},
        {"color": "Red",    "title": "Rejected"},
        {"color": "Red",    "title": "Canceled"}
    ]
}

How States Map to Colors

Frappe looks at the status field value (or workflow_state if a workflow is active) and matches it against the title in the states array. The matched color renders as a colored dot.

Available colors: Blue, Cyan, Gray, Green, Light Blue, Orange, Pink, Purple, Red, Yellow.

Important: States Titles Need Not Match Status Options

The states array titles can differ from the status field's options. This is useful when:

• The workflow has more granular states than the simple status

• You want different visual indicators for workflow states vs. application status

• Both payment_status and status feed into the visual indicators

Submittable Documents

Adding "is_submittable": 1 to the DocType enables the Draft → Submitted → Cancelled lifecycle:

{
    "is_submittable": 1
}

This automatically adds a docstatus field:

• 0 = Draft

• 1 = Submitted

• 2 = Cancelled

Fields with allow_on_submit: 1 can still be modified after submission.

Practical Pattern: Multiple Status Tracking

A real-world example combining all three mechanisms:

{
    "fields": [
        {
            "fieldname": "status",
            "fieldtype": "Select",
            "options": "Pending\nApproved\nRejected\nCanceled",
            "default": "Pending",
            "allow_on_submit": 1
        },
        {
            "fieldname": "payment_status",
            "fieldtype": "Select",
            "options": "Unpaid\nPaid\nRefunded",
            "default": "Unpaid",
            "allow_on_submit": 1
        },
        {
            "fieldname": "workflow_state",
            "fieldtype": "Link",
            "options": "Workflow State",
            "hidden": 1,
            "read_only": 1,
            "allow_on_submit": 1
        }
    ],
    "states": [
        {"color": "Yellow", "title": "Payment Pending"},
        {"color": "Orange", "title": "Payment Requested"},
        {"color": "Blue",   "title": "Payment Received"},
        {"color": "Green",  "title": "Approved"},
        {"color": "Red",    "title": "Rejected"},
        {"color": "Red",    "title": "Canceled"}
    ],
    "is_submittable": 1
}

This gives:

• status — Application lifecycle (Pending → Approved/Rejected)

• payment_status — Payment tracking (Unpaid → Paid → Refunded)

• workflow_state — Granular workflow engine states for server-side automation

• states — Visual colored indicators derived from the workflow state titles