An ERPNext approval workflow is built from three pieces: states (Draft, Pending, Approved), transitions (who can move a document from one state to the next), and optional conditions that decide when a transition applies. You configure all of it from the Workflow list, with no code for most cases.
Short answer
To set up an ERPNext workflow, open the Workflow list, create a new Workflow, and pick the target DocType. Define Workflow States with their doc status (0 Draft, 1 Submitted, 2 Cancelled), add transition rules mapping a state plus an action plus an allowed role to a next state, add conditions where needed, turn on email alerts, mark it Active, and save.
I am Manoj, and I lead ERPNext and Frappe implementation work at MithTech, a team of Frappe specialists in Bengaluru, for organisations with several entities and many roles. Approval workflows are one of the first things clients ask me to configure, usually right after a purchase order slips through without a manager's sign-off. The mechanics are simple once you see how states and transitions fit together; the work is keeping the chain auditable at every level.
Many teams over-engineer their first workflow with six states and a dozen roles, then abandon it. Start with three states and add more only when a real gap appears.
What is a workflow in ERPNext?
A workflow in ERPNext is a rule set that controls how a document moves through defined stages before it is finalised. Each stage is a state, each allowed move is a transition, and each transition is restricted to specific roles. Creating one replaces the standard save-and-submit path for that DocType with your own approval logic.
That last point trips people up. Once a workflow is active on, say, Purchase Order, the normal Submit button disappears unless one of your transitions produces it. The document now does what your workflow allows and nothing more.
Workflows attach to a single DocType each. You can have a workflow on Leave Application, another on Purchase Order, another on Sales Invoice, all running independently. If you run several legal entities, pair this with a clean multi-company setup so each company's approval chain stays isolated.
Skimmable summary: a workflow is states plus role-gated transitions that override the default save/submit path for one DocType.
How do you set up an ERPNext workflow step by step?
Setup happens entirely in the Workflow form. Search "Workflow" in the awesome bar, create a new record, select your DocType, then build states first and transitions second. Save once and the required custom field is created for you. Here is the full sequence.
Create the Workflow and pick a DocType
Open the Workflow list and click New. Give the workflow a clear name (for example, "Purchase Order Approval") and select the Document Type it governs. One workflow controls one DocType.
Define your Workflow States
Add each stage in the States table: a State name (Draft, Pending Approval, Approved, Rejected) and its Doc Status. Use 0 for editable drafts, 1 for submitted/locked documents, and 2 for cancelled ones. Optionally set an Update Field and Update Value so reaching a state also writes a value onto the document.
Add transition rules
In the Transitions table, each row defines a move: the State the document is in, the Action button label an approver clicks (Approve, Reject, Submit for Approval), the Next State it lands in, and the Allowed role that may perform it. This is where the approval chain actually lives.
Set the Workflow State Field
Enter a name in Workflow State Field. On save, ERPNext adds this custom field to your DocType to track the current state. You do not create the field manually; the workflow does it for you.
Turn on email alerts and activate
Tick Send Email Alert so the next approver is notified when a document enters their queue. Tick Is Active to switch the workflow on. Save. The workflow is now live for every new and existing document of that type.
Skimmable summary: create the workflow, define states with doc status, add role-gated transitions, name the state field, enable alerts, mark active, save.
How do doc status values map to workflow states?
Doc status is ERPNext's built-in three-value lock on a document, and every workflow state must declare one. 0 means Draft (fully editable), 1 means Submitted (locked, ledger entries posted), and 2 means Cancelled. Choosing the right value for each state is what makes the workflow behave correctly.
| Doc status | Meaning | Typical workflow states |
|---|---|---|
| 0 | Draft, editable | Draft, Pending Approval, Rejected |
| 1 | Submitted, locked | Approved, Confirmed |
| 2 | Cancelled | Cancelled |
Keep every pre-approval state at doc status 0 so approvers can still edit or send documents back. Only the final approved state should move to 1, because that is the point where ERPNext posts the accounting or stock impact. A common mistake is setting "Pending Approval" to doc status 1, which locks the document before anyone has actually approved it.
Skimmable summary: pre-approval states stay at doc status 0; only the final approved state becomes 1 (submitted) so ledgers post at the right moment.
How do workflow conditions and self-approval work?
Conditions let a transition apply only when a rule is true, so you can route approvals by value, department, or any field. Enter a Python-style expression in the transition's Condition field, such as doc.grand_total > 100000. If the expression is false, that transition is hidden for that document, which is how you build tiered approvals.
For example, on a Purchase Order you might set two transitions from Pending Approval: one to Approved for a Purchase Manager when doc.grand_total <= 100000, and another that routes to a second approval when the total is higher. Conditions can also read related data using framework helpers like frappe.db.get_value, plus the session user and date functions.
Keep condition expressions short and reference fields that always exist on the document. Long or fragile conditions are hard to debug later, and a syntax error can stop the transition from showing at all.
Skimmable summary: conditions gate transitions with expressions like doc.grand_total > 100000; disable Allow Self Approval so makers cannot approve their own documents.
Should you use the visual Workflow Builder?
Yes, if you are on a current version. Frappe Framework v15 (released in 2023) introduced a visual Workflow Builder that lets you lay out states and draw transitions on a canvas instead of filling in table rows. It writes to the same underlying Workflow document, so nothing about the logic changes, only how you author it.
The builder helps with complex chains where a table view gets hard to read: you see the whole approval graph at a glance and can spot a dead-end state or a missing transition quickly. For a simple three-state workflow, the classic table form is fine and often faster. If you are planning a version move to get it, our ERPNext v16 workspace guide covers what else has changed in the newer interface.
Table form
Fast for simple workflows. Every field is visible in one scroll. Best when you have three or four states and know exactly what you want.
Workflow Builder (v15+)
Visual canvas for states and transitions. Best for multi-level, conditional approval chains where seeing the whole graph prevents mistakes.
Skimmable summary: the v15 visual Workflow Builder authors the same workflow on a canvas; use it for complex chains, stick with the table form for simple ones.
Frequently asked questions
+Why is the Submit button missing after I created a workflow?
Because a workflow overrides the default save-and-submit behaviour for that DocType. The document now follows only your transitions. If you need a Submit action, add a transition whose Next State has doc status 1. Until such a transition exists for the user's role, no Submit button appears.
+Can one document type have more than one workflow?
Only one workflow can be Active on a DocType at a time. Enabling a second and marking it active deactivates the first. If you need different behaviour for different companies or branches, use conditions inside a single workflow to branch by field value rather than trying to run two workflows.
+How do approvers get notified?
Tick Send Email Alert on the workflow. When a document reaches a state, the users holding the allowed role for the next transition receive an email. For richer messages, you can also build a separate Notification record, but the built-in alert covers most approval queues.
+Can I edit a workflow after documents already exist?
Yes. Changing states or transitions applies going forward. Be careful renaming or deleting a state that live documents currently sit in, because those records reference the old state name. Add new states and transitions freely; remove old ones only after confirming no document is parked there.
+Do workflow conditions require coding?
No. Conditions are short Python-style expressions on document fields, like doc.total > 50000 or doc.department == "Sales". You do not write a script or install anything. Only unusual logic that reads across multiple documents benefits from a developer's help.
+Does ERPNext charge extra for workflows?
No. Workflows are part of ERPNext, which is open source under GPLv3 with no licence fee. There is no per-workflow or per-user licence fee for the feature itself. Any cost is in hosting and implementation, not in unlocking the capability.
To see how we run a rollout, read about ERPNext implementation, or read the multi-company setup guide to keep each entity's approvals cleanly separated.
Comments & ratings
No comments yet. Start a new discussion.
Manoj · Published on 20 July 2026
Worked with us? Leave a Google review