frappe-impl-workflow

name	frappe-impl-workflow
description	Use when implementing document Workflows, approval chains, or state-based transitions in Frappe. Prevents stuck documents from missing transitions, broken approval chains, and permission errors on workflow actions. Covers Workflow DocType, Workflow State, Workflow Action, transition rules, allowed roles, conditions, workflow_state field, apply_workflow. Keywords: workflow, approval, transition, Workflow State, Workflow Action, state machine, approval chain, workflow_state, approval chain, document approval, multi-step approval, workflow stuck, status transitions..
license	MIT
compatibility	Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16.
metadata	{"author":"OpenAEC-Foundation","version":"2.0"}

Frappe Workflow Implementation

Step-by-step guide for implementing document workflows in Frappe. Covers design, setup, testing, and common approval chain patterns.

Quick Reference: Implementation Checklist

1. □ Design states and transitions on paper/diagram first
2. □ Create Workflow State records (master list)
3. □ Create Workflow Action Master records (Approve, Reject, etc.)
4. □ Create the Workflow DocType record
5. □ Add states with correct doc_status values
6. □ Add transitions with roles, actions, and conditions
7. □ Set allow_edit roles per state
8. □ Configure email notifications (optional)
9. □ Test every transition path with test users
10. □ Verify self-approval blocking works as expected

Step 1: Design Your Workflow

Before touching the UI, map out your workflow on paper.

Identify States

ALWAYS start by listing every distinct document stage:

Example — Purchase Order Approval:
  Draft → Pending Review → Pending Approval → Approved → Submitted → Cancelled

Map DocStatus to States

For submittable DocTypes, ALWAYS assign doc_status correctly:

Stage	doc_status	Meaning
All "in-progress" states	0	Document is Draft, editable
Final approved/active state	1	Document is Submitted, locked
Cancelled state	2	Document is Cancelled

NEVER assign doc_status = 1 to intermediate approval states. A submitted document cannot return to draft. Once submitted, the only forward path is another submitted state or cancellation.

Map Transitions

For each state, define: What actions are possible? Who can perform them? Any conditions?

Draft         →[Submit for Review / Creator]→     Pending Review
Pending Review →[Approve / Reviewer]→              Pending Approval
Pending Review →[Reject / Reviewer]→               Draft
Pending Approval →[Approve / Manager]→             Approved
Pending Approval →[Reject / Manager]→              Draft
Approved      →[Submit / Manager]→                 Submitted (doc_status=1)
Submitted     →[Cancel / Manager]→                 Cancelled (doc_status=2)

Step 2: Create Prerequisite Records

2a. Create Workflow States

Navigate to Workflow State list or create via API:

# Create states with appropriate styles
states = [
    {"workflow_state_name": "Draft", "style": ""},
    {"workflow_state_name": "Pending Review", "style": "Primary"},
    {"workflow_state_name": "Pending Approval", "style": "Warning"},
    {"workflow_state_name": "Approved", "style": "Success"},
    {"workflow_state_name": "Submitted", "style": "Info"},
    {"workflow_state_name": "Rejected", "style": "Danger"},
    {"workflow_state_name": "Cancelled", "style": "Inverse"},
]
for s in states:
    if not frappe.db.exists("Workflow State", s["workflow_state_name"]):
        frappe.get_doc({"doctype": "Workflow State", **s}).insert()

Available styles: Primary, Success, Warning, Danger, Info, Inverse (or empty for default).

2b. Create Workflow Action Masters

actions = ["Submit for Review", "Approve", "Reject", "Send Back", "Cancel"]
for action in actions:
    if not frappe.db.exists("Workflow Action Master", action):
        frappe.get_doc({
            "doctype": "Workflow Action Master",
            "workflow_action_name": action
        }).insert()

Step 3: Create the Workflow

Via UI

Navigate to Setup > Workflow > New Workflow:

1. Set Workflow Name (e.g., "Purchase Order Approval")
2. Set Document Type (e.g., "Purchase Order")
3. Check Is Active
4. Add states in the States table
5. Add transitions in the Transitions table

Via Python

workflow = frappe.get_doc({
    "doctype": "Workflow",
    "workflow_name": "Purchase Order Approval",
    "document_type": "Purchase Order",
    "is_active": 1,
    "send_email_alert": 1,
    "states": [
        {"state": "Draft", "doc_status": "0", "allow_edit": "Purchase User"},
        {"state": "Pending Approval", "doc_status": "0", "allow_edit": "Purchase Manager"},
        {"state": "Approved", "doc_status": "1", "allow_edit": "Purchase Manager"},
        {"state": "Rejected", "doc_status": "0", "allow_edit": "Purchase User"},
        {"state": "Cancelled", "doc_status": "2"},
    ],
    "transitions": [
        {
            "state": "Draft",
            "action": "Submit for Review",
            "next_state": "Pending Approval",
            "allowed": "Purchase User",
            "allow_self_approval": 1,
        },
        {
            : ,
            : ,
            : ,
            : ,
            : ,
        },
        {
            : ,
            : ,
            : ,
            : ,
        },
        {
            : ,
            : ,
            : ,
            : ,
        },
        {
            : ,
            : ,
            : ,
            : ,
        },
    ],
})
workflow.insert()

Step 4: Configure Advanced Features

Conditional Transitions

Add Python conditions to show transitions only when criteria are met:

# Only allow approval for orders above 50000 by Senior Manager
{
    "state": "Pending Approval",
    "action": "Approve",
    "next_state": "Approved",
    "allowed": "Senior Manager",
    "condition": "doc.grand_total > 50000",
}

# Standard approval for orders up to 50000
{
    "state": "Pending Approval",
    "action": "Approve",
    "next_state": "Approved",
    "allowed": "Purchase Manager",
    "condition": "doc.grand_total <= 50000",
}

ALWAYS use doc.fieldname syntax in conditions (the document is exposed as a dict).

Available in conditions: frappe.db.get_value(), frappe.db.get_list(), frappe.session.user, frappe.utils.now_datetime(), frappe.utils.add_to_date(), frappe.utils.get_datetime().

Self-Approval Blocking

Set allow_self_approval = 0 on approval transitions. This means:

• The document owner (creator) CANNOT perform this action
• Administrator is ALWAYS exempt from this restriction
• Other users with the required role CAN perform the action

Email Notifications

1. Set send_email_alert = 1 on the Workflow
2. On each state row, set send_email = 1 (default)
3. Optionally link an Email Template via next_action_email_template
4. Add a custom message on the state row for inline notification text

Update Fields on State Change

Use update_field and update_value on state rows to automatically set document fields:

# Set approval_status when entering "Approved" state
{"state": "Approved", "doc_status": "1",
 "update_field": "approval_status", "update_value": "Approved"}

# Use expression to set approval date dynamically
{"state": "Approved", "doc_status": "1",
 "update_field": "custom_approved_on", "update_value": "frappe.utils.now()",
 "evaluate_as_expression": 1}

Step 5: Test Your Workflow

Manual Testing Checklist

1. Create a test document — verify it starts in the first state (Draft)
2. Check available actions — only roles with transitions from Draft should see buttons
3. Perform each transition — verify state changes correctly
4. Test rejection paths — verify documents return to correct state
5. Test self-approval — log in as document owner, verify blocked transitions
6. Test conditions — create documents that meet/fail conditions, verify button visibility
7. Test email notifications — verify emails sent on state changes
8. Test with non-submittable DocType — verify all doc_status = 0

Programmatic Testing

# Get available transitions for a document
from frappe.model.workflow import get_transitions, apply_workflow

doc = frappe.get_doc("Purchase Order", "PO-00001")
transitions = get_transitions(doc)
# Returns list of dicts with action, next_state, allowed, etc.

# Apply a workflow action
updated_doc = apply_workflow(doc, "Approve")
# Returns the updated document after state change

Common Workflow Patterns

Pattern 1: Sequential Approval Chain

Draft → Level 1 Review → Level 2 Review → Approved → Submitted

Each level has its own role. Document moves linearly through approvals.

Pattern 2: Conditional Routing by Amount

Draft → Pending Approval
  ├─[amount <= 10000 / Team Lead]─→ Approved
  ├─[amount <= 50000 / Manager]──→ Approved
  └─[amount > 50000 / Director]──→ Approved

Use condition on each transition to route based on document values.

Pattern 3: Review with Rejection Loop

Draft ←──[Reject]── Pending Review ──[Approve]──→ Approved
  └──[Submit for Review]──→ Pending Review

Rejected documents return to Draft for revision. Creator resubmits. This is the most common approval pattern.

Pattern 4: Leave Approval

Applied (doc_status=0, allow_edit=Employee)
  └─[Approve / Leave Approver]─→ Approved (doc_status=1)
  └─[Reject / Leave Approver]─→ Rejected (doc_status=0)
Approved
  └─[Cancel / HR Manager]─→ Cancelled (doc_status=2)

Pattern 5: Document Review (Non-Submittable)

For non-submittable DocTypes, ALL states MUST have doc_status = 0:

Draft → Under Review → Reviewed → Published
(all doc_status = 0)

Migrating from Manual DocStatus to Workflow

If your DocType currently uses manual Submit/Cancel buttons and you want to add a workflow:

1. Map existing documents — The workflow engine auto-maps existing documents to states based on their docstatus when the workflow is created
2. Define a state for each docstatus — ALWAYS have at least one state per docstatus value your documents currently use
3. Test with existing data — Verify that existing submitted documents show the correct workflow state
4. Update list views — If using override_status, the workflow state replaces the Status column

NEVER activate a workflow without a state for docstatus=0. New documents would have no valid initial state.

Decision Tree

Starting a new workflow implementation?
│
├── What type of DocType?
│   ├── Submittable → can use doc_status 0, 1, 2
│   └── Non-submittable → ALL states must be doc_status = 0
│
├── How many approval levels?
│   ├── Single → Two-state: Draft → Approved
│   ├── Sequential → Chain: Draft → L1 → L2 → Approved
│   └── Conditional → Route by field values using conditions
│
├── Need self-approval blocking?
│   └── Set allow_self_approval = 0 on approval transitions
│
├── Need rejection/revision loop?
│   └── Add Reject transition back to Draft or previous state
│
├── Need email notifications?
│   ├── Enable send_email_alert on Workflow
│   └── Link Email Template on each state
│
└── Need automated field updates?
    └── Use update_field + update_value on target state

Troubleshooting

Problem	Cause	Solution
No action buttons visible	User lacks required role	Add role to user OR add transition for user's role
"Self approval is not allowed"	User is doc owner + allow_self_approval=0	Have different user approve, or set flag to 1
"Workflow State not set"	Document created before workflow activation	Run update_default_workflow_status or manually set state
Document stuck in state	No outgoing transition defined for current state + user role	Add missing transition
"Cannot cancel before submitting"	Transition goes from doc_status=0 to doc_status=2	Add intermediate submitted state
Actions show for wrong users	Role assignment too broad	Use more specific roles or add conditions

See Also

• Workflow Patterns — Detailed step-by-step workflow examples
• Decision Tree — Extended decision tree for workflow design
• Examples — Code examples for common scenarios
• Anti-Patterns — Mistakes to avoid
• frappe-core-workflow — Workflow engine internals and API reference