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