What ERPNext approval workflows do and when teams need them
Finance and operations leaders need spending approved by amount and by role before a purchase order, quotation, invoice or expense claim is submitted. In ERPNext, the mechanism for this is the Workflow feature, which lets you attach a configurable state machine to a DocType. A workflow defines the states a document can be in (for example Draft, Pending Approval, Approved and Rejected), the actions a user can take (such as Approve, Reject or Send for Review), and the transitions that move a document from one state to another. Each transition is tied to a role, so only users holding that role can trigger it. Workflow is distinct from document submission: submission is a fixed lifecycle step in ERPNext that locks a record for accounting, while a workflow governs who may move the record through its approval path before and around that step.
A workflow is worth designing when the approval rule depends on something in the document itself, such as the grand total, the cost center, the supplier or the project, and when the approver for one level differs from the approver for the next. Simple one-step sign-off can often be handled by a permission rule alone. Multi-level chains, value thresholds and separation of duties (for example, the person who raises a purchase order cannot approve it) are where workflows earn their place. Before configuration starts, document the approval matrix with the finance owner, including who approves at each amount band, what happens when an approver is absent, and which document types need the chain. Confirm with your ERPNext version's documentation how conditions on workflow transitions and document field values are expressed, because the exact syntax and available options should be checked against the release you run.
ERPNext Workflow building blocks: states, actions, transitions and roles
An ERPNext approval workflow is a set of states, actions and transitions attached to one DocType, and each transition is gated by a role and sometimes a condition. Designers should settle these parts on paper before touching the Workflow builder, because the same document can be governed by several overlapping rules. The cards below cover the components in the order a designer decides them.
Workflow states as document checkpoints
A workflow state is a named point in a document's approval life, such as Draft, Pending Approval, Approved or Rejected. Each state should answer one question: who must act next, and what can still change. Too many states slow approvers down and make reporting harder, while too few hide where a purchase order is stuck. Agree the state list with the finance and procurement owners and check that every state has at least one outgoing action, or documents will stall without a clear owner.
Actions that move a document between states
An action is the button an approver or submitter clicks, such as Approve, Reject or Send Back for Revision. Each action belongs to a source state and leads to a target state, so a single state can offer several actions. Name actions in the language approvers already use, and decide whether rejection returns the document to the requester or closes it. Ambiguous action names are a common cause of approvals given by mistake.
Role-based transitions
Each transition specifies which role may perform its action, and only users holding that role see the button. Map roles to job functions, such as Purchase Manager or Finance Controller, rather than to named individuals, so the design survives staff changes. Check that no single user holds both the submitter and approver roles for the same step, because segregation of duties depends on it. Confirm how your role assignments interact with the permissions set on the DocType itself.
Document status and submit or cancel
ERPNext documents have a docstatus of Draft, Submitted or Cancelled, and submitted documents are normally locked against field edits. A workflow state is a separate value that runs alongside this status, so designers must decide which state corresponds to submission. Workflow transitions can submit or cancel a document, and that step triggers ledger postings in accounting and stock DocTypes. Test the full path, including cancellation and amendment, before go-live, because approval rules do not undo posted entries.
Conditions on document fields
A transition can carry a condition expressed on the document's own fields, such as a grand total above a threshold or a particular supplier group. This lets one workflow route small purchases to a single approver and large ones to a manager and a controller. Conditions are evaluated at the moment of the action, so a value changed afterward can bypass the intended route. Document the thresholds, the fields they read and who owns changes to them.
Overlapping rules and edge cases
Only one active workflow can govern a DocType at a time, so a request for a new approval step often means editing an existing design rather than adding a parallel one. Edge cases such as partial amounts, multi-currency totals, returns and urgent exceptions need explicit paths, or users will route around the workflow. Before finalizing, walk through a table of sample documents that cover each branch, and confirm the behavior of your ERPNext version with a test site.
Which approval design fits which document and control need
This table compares the main approval designs for ERPNext documents, from single-step and multi-level chains to threshold branches, role-based and user-based approvers, and in-document versus separate requests. Read each row against the document type and control expectation you must meet, then check the trade-off before committing to a design. The main takeaway is that most organizations need a small number of reusable chains tied to roles and amount bands, not a bespoke route for every approver.
| Design option | When it fits | Main trade-off | What to confirm first |
|---|---|---|---|
| Single-step approval | Low-value purchase orders or expense claims where one accountable manager is enough | Fast to configure, but gives no second review for high-value or unusual transactions | Which roles hold the approval and whether any segregation of duties applies |
| Multi-level approval chain | Purchase orders or invoices that pass through a supervisor, then a finance owner | Stronger review, but each added state adds waiting time and more places where documents stall | How many levels your policy requires and who covers absences |
| Amount-threshold branch | Documents whose required approvers depend on the grand total or a value field | Matches spend policy closely, but thresholds must be kept in sync with policy changes | Currency basis, whether taxes are included and the threshold bands in your delegation of authority |
| Role-based approver | Approval belongs to a function, such as any purchasing manager, so staff changes do not break routing | Easier to maintain, but any user holding the role can act, so role assignments need tight control | Which users hold each role today and who approves role assignments |
| User-based approver | A named person must approve, such as a budget owner for a specific cost center | Precise accountability, but routing breaks when people leave or move and needs regular review | Ownership of each cost center or project and a replacement plan for absences |
| Approval inside the document | The approval is part of the purchase order, quotation or invoice state and must be visible in the record | Keeps evidence on the document itself, but the document can be edited or resubmitted, so state rules need care | Which fields and actions must lock after approval and how amendments are handled |
| Separate request document | A distinct approval record is needed for exceptions, such as a credit limit override or a budget breach | Clear audit trail for exceptions, but adds a second document to track and reconcile with the original | Whether the approval must link back to the source document and who can close it |
| Email notification to approvers | Approvers work away from the desk and need prompts to act on pending items | Speeds response, but email alone is not evidence of approval, and notifications can be missed | Mail server setup, notification recipients per state and whether reminders are needed |
How to set up an approval workflow in ERPNext step by step
This sequence takes a documented approval policy and turns it into a working ERPNext Workflow, with roles, amount conditions and approver notifications tested before anyone relies on it for live purchase orders, quotations, invoices or expense claims.
Confirm document types and approval policy
Finance, operations and the policy owner agree which DocTypes need approval (for example Purchase Order, Quotation, Sales Invoice or Expense Claim), the approval levels, the amount thresholds at each level and who may approve at each level. Write these down in a single approval matrix. The step is done when every threshold and approver group in the matrix has a named owner and no open questions remain about exceptions or delegation.
Create roles and assign approver users
An administrator creates one role per approval level in the Role list, then assigns those roles to the named users in the User records. Keep approval roles separate from creator roles so a person cannot both raise and approve the same document. Confirm the exact role and user screen labels in your ERPNext version before you start. The check: open the User list filtered by each new role and confirm it shows only the people in your matrix.
Define workflow states and transitions
In the Workflow DocType, create a workflow for the target document, set the document's starting state (such as Draft) and add the states the document passes through, such as Pending Manager Approval and Approved. For each transition, specify the action (for example Approve or Reject), the allowed role and the next state. Mark the final approved state with the correct document status so submitted documents are recorded properly. Check the diagram or transition table against your matrix line by line.
Add amount conditions to transitions
Add a condition to each transition that routes the document by value, for example sending documents above the manager threshold to a second approval state. Conditions are written as expressions on the document fields, so test the field names against the actual DocType before saving. Confirm how your version handles documents in a different currency, and whether totals are read before or after taxes. The step is complete when a test document below each threshold follows only its intended path.
Configure email notifications for approvers
Create a Notification record linked to the workflow state change so approvers receive an email when a document reaches a state that needs their action. Set the recipient to the relevant role or to a field on the document, and use a clear subject that includes the document name. Confirm that outgoing email is configured and tested under Email Account settings, since notifications will not arrive without it. The check: a test document moved into an approval state sends one email to each intended approver and no one else.
Test each path with a non-production user
On a staging or test site, create a test user with the requesting role and separate test users for each approver. Run one document through every path: approved at each level, rejected, and routed by amount. Confirm that users outside the matrix cannot see the action buttons, that rejected documents return to the expected state, and that notifications match the path taken. Record the results and the ERPNext version. Only move the workflow to production after every path has passed and the approval matrix owner has signed off.
Designing amount conditions and multi-level chains without blocking urgent spend
Routing a document through approval levels depends on the transition conditions you attach to each action in the Workflow DocType. A condition is a Python expression evaluated against the document, so it can test fields such as grand_total on a Purchase Order or a branch or company field on a Sales Invoice. The main design risk is threshold overlap or gaps. If level one covers amounts up to 5,000 and level two starts at 5,000, a document at exactly that value can match both or neither, depending on how the operators are written. Use one boundary operator per band (for example, less than for the lower band and greater than or equal to for the next), and write a test document for each boundary before you go live. Confirm the exact comparison behavior and field names against the workflow documentation for your ERPNext version, since your chosen thresholds will depend on how your currency and company fields are stored.
Multi-level chains need a plan for approvers who are absent or have left. A workflow transition is only as available as the role or user it targets, so an approver on leave can stall a purchase order that someone is waiting on to buy urgent stock. Decide in advance who covers each level, whether that is a named deputy, a second role with the same authority, or a controlled escalation to a finance lead, and record that decision as a policy rather than an ad hoc email. Turnover needs the same treatment: when a user is disabled, documents already sitting in a state assigned to that role must still move. Test this by disabling a test approver and confirming that an open document can still be actioned. Where the logic cannot be expressed in conditions, such as routing by a value held in another DocType, Server Scripts can be used, but they are disabled by default from version 15 and must be enabled with the server_script_enabled setting. Frappe Cloud public shared benches do not allow them, so confirm your hosting option supports this before you design around them.
Questions buyers ask before building ERPNext approval workflows
What drives the cost of an ERPNext approval workflow project?
The cost follows the amount of configuration and testing the written scope requires, and the four biggest drivers are the number of document types, the number of approval levels, how far the routing branches, and how many integrations the approvals touch. A single approval on purchase orders with two levels is a small, bounded piece of work. Adding quotations, sales invoices and expense claims, each with amount thresholds, department routing and delegation, multiplies the states, transitions, role checks and test cases. Each integration, such as a link to a budget check or a notification service, adds design and verification effort. DeployOpen does not publish prices, so the reader should expect a quote built from the written scope, with each driver listed as its own line.
How long does an ERPNext approval workflow take to deliver?
Timing depends on the same scope drivers as cost, and most engagements are fixed-scope, so the deliverables and timeline are agreed in writing before work starts. Expect the schedule to cover the approval matrix review, workflow build in a test environment, role and permission checks, email notification setup and user acceptance testing. Approval workflows rarely slip because of the Workflow configuration itself. They slip when approver names, thresholds or exception rules are still changing after build begins. Ask for the timeline as a set of milestones tied to the signed scope, and confirm which items depend on your decisions and your review availability.
What do we need to provide before an approval workflow build starts?
Before build starts, the client should provide a written approval matrix, a list of ERPNext roles in use, and named approvers for each level and each threshold. The matrix should state which document types need approval, the amount or condition that triggers each level, what happens on rejection, and who may delegate or override. The role list should show which users hold Accounts Manager, Purchase Manager, Sales Manager or custom roles, because transitions are tied to roles. Named approvers matter because email notifications and transition permissions depend on specific users. Missing items are the most common cause of rework, so confirm them before the quote is finalized.
Can our internal team configure simple ERPNext approval workflows themselves?
Yes, a capable internal administrator can often configure a single, linear approval on one document type, provided they understand workflow states, actions, transition conditions and role permissions. The work becomes harder when several document types share logic, when branching depends on amounts or cost centers, or when notifications must reach approvers reliably. Internal staff should also test every transition with users holding each role, including rejected and cancelled paths, and document the configuration for their successors. If the workflow affects financial controls, consider whether the reviewer or auditor will expect a separate test record. An external review of a simple configuration can be a cheaper alternative to a full build.
How does a quote follow from the written scope?
A quote follows directly from the written scope, which lists each document type, approval level, branch condition, role, integration and notification to be delivered, along with the acceptance criteria for each. DeployOpen builds the estimate from those items, so changes to the scope change the quote in writing before work continues. Ask the quote to show the work grouped by discovery, configuration, testing, documentation and handover, so you can see what is included and what is excluded. Confirm whether support or a retainer is quoted separately, since ongoing support is available as a retainer rather than as part of the initial build.
What breaks most often in ERPNext approval workflows?
The most common failures are unclear thresholds, approvers who lack the role needed for a transition, and documents that bypass the workflow after submission. Thresholds written in a currency or tax basis that differs from the document often route approvals incorrectly. When an approver leaves, a transition can stall because no active user holds the required role. Email notifications also fail silently when the approver's address is missing or the outgoing mail setup is not verified. Test each transition with real user accounts, check the notification delivery, and define an exception path for absent approvers before go-live.
Do approval workflows need to meet specific compliance controls?
Approval workflows can support segregation of duties and evidence requirements, but DeployOpen prepares systems, controls and evidence for compliance assessments without issuing audit reports or certifications. Independent auditors and certification bodies make those determinations. For financial documents, define who may create, approve and post, and confirm that the same user cannot approve their own submission. Keep records of the approval matrix and test results so an auditor can trace each approval to a permitted role. Ask your auditor which evidence format they expect before the build starts.
Are approval workflows included in ERPNext's free self-hosted license?
ERPNext is free and open-source software licensed under GPL-3.0, and self-hosting it carries no license fee, so approval workflows built with ERPNext's standard features do not add a software license cost. The Frappe Framework is licensed under MIT. Costs that remain are infrastructure, the implementation work, and any support or upgrade retainer you choose. If you use Frappe Cloud instead of self-hosting, hosting fees apply, and the pricing page lists those separately. Confirm with your procurement team which of these costs fall under your budget and which under your existing infrastructure agreements.
Security and segregation of duties in approval workflows
An approval workflow is only as strong as the controls around it. The cards below cover who can approve, who can change the rules, how approvers are assigned, and what record remains afterward. Check each one in a test instance before go-live, because a workflow that looks correct on screen can still be approved by the person who created the document.
Role-based transition permissions
Each workflow transition in ERPNext names the role allowed to take that action, such as moving a Purchase Order from Pending Approval to Approved. Assign these roles to individuals with care, since a user who holds the approver role on one transition can act on every document that reaches that state. Check each state with a test user who holds only the intended role, and confirm that a user with a broader role cannot skip a level.
Blocking self-approval
A requester who also holds the approver role can approve their own purchase order or expense claim unless a condition stops it. Add a condition on the transition that compares the document owner with the current session user, or separate the requester and approver roles so no one holds both for the same flow. Test the case explicitly, because the default configuration does not describe this risk.
Controlling who edits workflows
Workflow definitions are configuration, and a user who can edit a Workflow record can redirect approvals without a visible code change. Restrict the System Manager role, limit who can create or modify Workflow records, and export approved definitions into version control or a change log. Ask who in your organization approves changes to approval rules, and record that answer in your access policy.
Audit trail of approval actions
Confirm which actions ERPNext records against each document, including the state changes, the user, and the time of each transition. Decide how long these records are kept and whether auditors can export them without system access. Run a sample approval from request to submission, then pull the document history and check that every step names a real person.
User permissions and field-level access
User permissions limit which records a user can see, such as a branch or cost center, and workflow transitions act only on records the user can already access. Field-level read-only settings can also stop approvers from altering amounts after approval. Test a case where an approver outside the relevant branch tries to act on a document, and confirm the transition is refused.
Approver roles from directory groups
If your company manages staff in Active Directory or OpenLDAP, ERPNext can map LDAP groups to roles at each login. This lets a change in the directory, such as adding someone to a finance approvers group, change their ERPNext approval rights without an administrator editing the user. Confirm that removed group members lose the role at their next login, and that the mapping cannot grant roles beyond what the approval design allows.
Keeping workflows correct across ERPNext upgrades and staff changes
Approval workflows fail quietly after upgrades and staff changes, so treat the workflow definition as code that needs a version history and a review step. Keep each Workflow record exported as a fixture or customization file in your own version-controlled repository, so every change to states, transitions, conditions and allowed roles has an author, a reason and a diff. Use the export to review what changed between releases before it reaches production. Record which ERPNext and Frappe version each workflow was tested against, because ERPNext ships frequent minor releases on both supported major versions, 15 and 16. Confirm with your partner or your own test plan which exports you need and how your team will import them into staging first.
Retest the full approval path after every minor release, not only after major upgrades. Build a short test script for each document type in scope, such as a purchase order above and below the amount threshold, a quotation sent back for revision, and an expense claim rejected at the second level. Run each path with test users holding the exact roles in production, and check that the email notifications reach the right approver and that the document can still be submitted by the intended role. Store the results with the release number so an auditor or internal reviewer can see when each path last passed. Ask your implementer to confirm whether the test cases stay with the customization or with the test environment.
Staff changes break workflows in a different way. A workflow usually routes to a Role rather than a named person, so the risk sits in the User and Role assignments behind it. When an approver leaves, the role may still exist while the only holder is inactive, which stalls documents in a state nobody can act on. Set up a leaver checklist that disables the user, reassigns open approvals and checks that each state still has at least one active holder with a backup. Review role membership on a fixed schedule, and make a named owner responsible for any change to a workflow condition, such as a new amount threshold, so that business rules do not drift without approval.
Limits to confirm in your ERPNext version and environment
Approval workflows depend on details that differ between ERPNext versions and hosting models. Confirm the items below against the exact release and environment you plan to run, because a workflow that works on a development bench may not behave the same way on a shared cloud site or after an upgrade.
Condition syntax supported
Confirm which expression syntax your version accepts in workflow transition conditions, such as comparisons on grand total or on fields of child tables, and whether it can reference the approver's roles or the company. Test a transition with a value just above and just below each threshold, including multi-currency documents, because a condition that compares raw amounts may behave differently from one that compares converted company-currency values.
Email template and notification behavior
Confirm which events trigger an email to an approver, whether the template can include a link to the pending document, and whether notifications fire on every state change or only on entry into a state. Check how the email is sent to users who have no email account set up, and whether outgoing email is configured for the site before you rely on it for approvals.
Workflow support on each target DocType
Confirm that the Workflow feature is available and enabled for each DocType you need, including Purchase Order, Quotation, Sales Invoice, Purchase Invoice and Expense Claim. Some documents have submit, cancel and amend behavior that interacts with workflow states, so test the full path from draft through submission and cancellation for each one, not only the happy path.
Behavior on Frappe Cloud shared benches
Confirm whether the plan you intend to use allows the server-side logic your approval rules need. Public shared benches on Frappe Cloud do not allow Server Scripts, so any condition or notification that depends on them will need a dedicated bench or a different hosting model. Verify this with the current hosting terms before you design around it.
Whether logic requires custom apps
Decide whether the required rules fit standard workflow states, transitions and conditions, or whether they need Server Scripts, client scripts or a custom app. Server Scripts are disabled by default from version 15 and must be enabled, so confirm that setting in your environment. Custom app code adds build, testing and upgrade effort on every ERPNext release, so ask who will maintain it after go-live.
How DeployOpen scopes and delivers ERPNext approval workflows
DeployOpen plans, builds, tests, documents and supports ERPNext approval workflows inside your own infrastructure, starting from a written scope that names the documents, amount thresholds and approver roles involved. Engagements are fixed-scope, so the deliverables and the handover are agreed before build work begins.
How we scope
- Map which documents need approval, such as purchase orders, quotations, invoices or expense claims, and who decides at each level.
- Define workflow states, transition actions, amount conditions and the roles allowed to approve, reject or return a document.
- Agree in writing which notification emails approvers receive and which permission checks the approval design must respect.
How we build
- Configure Workflow documents and transitions in a development environment, then test each path from submission to final approval.
- Test rejection, return for correction and cancellation paths, plus users who hold more than one approver role.
- Review role permissions and field access so that approvers see only the records their level allows.
How we hand over
- Deliver the workflow configuration as exported customizations so changes can be reviewed and moved between environments.
- Document each state, transition, condition and role in a written runbook your administrators can follow.
- Walk your finance and operations administrators through adding approvers, changing thresholds and reading the approval history.
How we support
- Re-test approval paths after each ERPNext minor release, since both supported major versions receive frequent updates.
- Review workflow changes when your approval policy, organization chart or amount limits change.
- Offer ongoing support, upgrades and testing as a retainer, with scope and response terms agreed in writing.
