name: frappe-core-workflow description: > Use when creating or modifying Frappe Workflows, defining states and transitions, adding action conditions, or troubleshooting workflow permission errors. Prevents stuck documents from misconfigured transitions, missing state permissions, and circular workflow paths. Covers Workflow DocType, workflow states, transitions, actions, conditions (Python expressions), workflow permissions, workflow_state field, Workflow Action DocType. Keywords: workflow, states, transitions, actions, conditions, workflow_state, Workflow Action, approval, document workflow, approval process, document stuck, cannot change status, workflow not moving, who can approve.. license: MIT compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16." metadata: author: OpenAEC-Foundation version: "2.0"

Workflow Engine

The Frappe Workflow engine is a state machine that controls document lifecycle through configurable states, transitions, and role-based permissions. It governs when and how documents change status, who can perform actions, and what side effects occur on each transition.

Quick Reference

Workflow DocType            → Defines the state machine for a specific DocType
├── states (child table)    → Workflow Document State rows
│   ├── state               → Link to Workflow State
│   ├── doc_status          → 0 (Draft), 1 (Submitted), 2 (Cancelled)
│   ├── allow_edit          → Role that can edit in this state
│   ├── update_field        → Field to update when entering state
│   ├── update_value        → Value to set (literal or expression)
│   └── next_action_email_template → Email Template link
└── transitions (child table) → Workflow Transition rows
    ├── state               → Source state (Link to Workflow State)
    ├── action              → Link to Workflow Action Master
    ├── next_state          → Target state (Link to Workflow State)
    ├── allowed             → Role that can perform this action
    ├── allow_self_approval → Check (default: 1)
    ├── condition           → Python expression (optional)
    └── transition_tasks    → Link to Workflow Transition Tasks

Key Fields on Workflow DocType

How the Engine Works

1. Activation and Field Creation

When a Workflow is saved with is_active = 1:

• All other workflows for the same DocType are deactivated automatically
• A hidden Custom Field (workflow_state_field, default workflow_state) is created on the target DocType if it does not exist
• The field is type Link to Workflow State, with hidden=1, allow_on_submit=1, no_copy=1
• Existing documents with empty workflow state get their state set based on their current docstatus

2. State Resolution

Every document under a workflow has a workflow_state field. The engine resolves available transitions by:

1. Reading current workflow_state from the document
2. Filtering workflow.transitions where transition.state == current_state
3. Filtering by user roles: transition.allowed in frappe.get_roles()
4. Evaluating transition.condition via frappe.safe_eval() (if set)
5. Returning matching transitions as available actions

3. Applying a Transition

When apply_workflow(doc, action) is called:

1. Load document from DB (fresh read)
2. Get available transitions for current user
3. Find transition matching the requested action
4. Check self-approval: blocked if allow_self_approval=0 AND user is document owner
5. Set workflow_state_field to transition.next_state
6. If update_field is set on the target state, update that field
7. Execute transition tasks (sync first, then async via frappe.enqueue)
8. Handle docstatus change based on source/target state doc_status values
9. Save/Submit/Cancel document accordingly
10. Add workflow comment

Workflow and DocStatus Interaction

CRITICAL: The workflow engine controls docstatus transitions. You NEVER call doc.submit() or doc.cancel() directly on a workflow-controlled document. The workflow does it.

DocStatus Transition Rules

ALWAYS define your states so that docstatus only moves forward: 0→0, 0→1, 1→1, 1→2. NEVER create a transition from a cancelled state or from submitted back to draft.

Non-Submittable DocTypes

If the target DocType is NOT submittable, ALL states MUST have doc_status = 0. The engine validates this and throws an error if any state has doc_status = 1 or 2 on a non-submittable DocType.

Workflow States

Workflow State is a separate DocType used as a master list. Each state has:

State Row Fields (Workflow Document State)

Workflow Transitions

Each transition row defines one possible action:

Condition Expressions

Conditions are Python expressions evaluated in a sandboxed environment. Available globals:

# Available in condition expressions:
frappe.db.get_value(doctype, name, fieldname)
frappe.db.get_list(doctype, filters, fields)
frappe.session.user
frappe.session.roles  # NOT available — use frappe.get_roles() outside conditions
frappe.utils.now_datetime()
frappe.utils.add_to_date(date, **kwargs)
frappe.utils.get_datetime(datetime_str)
frappe.utils.now()
doc.fieldname  # Access any field on the document (as dict)

Example conditions:

doc.grand_total > 50000
doc.department == "HR"
doc.grand_total > 50000 and doc.department != "Finance"

Workflow Actions

Workflow Action Master

Simple DocType with just a workflow_action_name field. Common actions: Approve, Reject, Review, Send Back, Cancel. Create these first before defining transitions.

Workflow Action DocType

Tracks pending actions for users. Created automatically when a document enters a state with outgoing transitions.

Workflow Actions appear in the user's "Workflow Action" list and can be acted on via email links.

Self-Approval Control

def has_approval_access(user, doc, transition):
    return (user == "Administrator"
            or transition.get("allow_self_approval")
            or user != doc.get("owner"))

• Administrator ALWAYS has approval access regardless of settings
• If allow_self_approval = 1 (default): document owner CAN approve
• If allow_self_approval = 0: document owner CANNOT approve their own document

Decision Tree

Need workflow on a DocType?
├── Is DocType submittable?
│   ├── YES → States can use doc_status 0, 1, 2
│   └── NO  → ALL states MUST have doc_status = 0
├── Define states → Create Workflow State records first
├── Define transitions → Need Workflow Action Master records first
├── Who can edit in each state? → Set allow_edit per state
├── Need conditional transitions?
│   └── Use Python expressions with doc.field access
├── Need to block self-approval?
│   └── Set allow_self_approval = 0 on specific transitions
└── Need email notifications?
    └── Set send_email_alert on Workflow + email templates on states

Common Errors

See Also

• API Reference — Complete workflow Python API
• Examples — Workflow configuration examples
• Anti-Patterns — Common mistakes and how to avoid them
• frappe-impl-workflow — Step-by-step implementation guide