🔁 Recap: the Permission Chain
Part 1's Users, Roles & Permission Flow section introduced the idea that ERPNext never checks a single "can this user do this?" flag — every allowed action is the output of a layered chain evaluated in order. This article goes deep on each link in that chain, one section at a time, so it's worth restating the whole shape up front before we zoom in:
Every section below maps onto exactly one link in that chain: user types and roles (link 1–2), the Role Permission Manager and User Permission tools (link 3–4), and Document Share plus workflow permissions (link 5).
👤 User Types & Standard Roles
Two records get confused constantly by beginners because they sound related but serve different purposes. A User is a login/authentication record — it has an email, a password (or SSO identity), a set of assigned Roles, and it's what the framework checks on every request. An Employee is an HR master record — name, department, designation, reporting manager, joining date — that exists whether or not that person ever logs into the system. An Employee record can optionally be linked to a User record (so, for example, a Leave Application can resolve "whose leave is this" back to a login), but plenty of Employees in a real deployment (shop-floor staff, for instance) never get a User account at all, and plenty of Users (an external accountant, an API integration account) are not Employees.
ERPNext ships a set of standard roles that map to job function, all ultimately subordinate to System Manager, which has unrestricted administrative access to the whole site:
A User can hold several roles at once — a small-business bookkeeper might reasonably be both Accounts Manager and Sales User. Assigning roles one at a time gets tedious for a growing team, which is what a Role Profile solves: it's a named bundle of roles (e.g. "Regional Sales Rep" = Sales User + Stock User) that can be applied to a new User in one step instead of ticking every role individually, and updating the Role Profile later can cascade the change to everyone assigned it. Individual role assignment is still the right tool for a one-off exception — granting a single extra role to one User without changing the bundle everyone else shares.
🛂 Role Permission Manager vs User Permission Manager
These two tools — plus Document Share and workflow permissions — are easy to mix up because they all say "permission" in the name, but they operate at completely different levels of the chain:
| Tool | Grants access at the level of | Example |
|---|---|---|
| Role Permission Manager | DocType level — read/write/create/submit/cancel/delete/amend, per role | Sales User role can create Sales Order but not submit it |
| User Permission | Record level — restricts a user to specific documents within a DocType they already have role access to | Restrict a regional sales rep to only see customers in their Territory |
| Document Share | One specific document, ad-hoc, bypassing normal role rules | Share one confidential Purchase Order with an auditor who has no Purchase role |
| Workflow permission | State-gated — only a specific role can transition a document out of a given workflow state | Only Department Manager role can move a Purchase Request from Pending to Approved |
The order matters: Role Permission decides whether the door to a DocType exists at all for that role; User Permission narrows which rooms behind that door a specific user can enter; Document Share and workflow permissions are exceptions layered on top of both, for the "just this one document" and "just at this stage" cases respectively.
🖱️ Annotated UI Tour
Almost the entire application lives inside one interface, called the Desk. Rather than a specific screenshot — which would go stale the moment the UI is restyled in a future version — the table below is an illustrative annotation list of the elements a new user runs into first, in the rough order they'll notice them:
| # | Element | What a beginner should notice first |
|---|---|---|
| 1 | Sidebar | Lists the modules and workspaces this user's roles give them access to — it's effectively a personalized menu, not a fixed one |
| 2 | Workspace | The landing page after clicking a sidebar item — shortcuts, charts, and links curated for that module or role |
| 3 | Awesome Bar (global search) | Type a DocType name, a document number, or even a command like "new sales invoice" — it's usually faster than navigating menus |
| 4 | User menu | Profile, account settings, and where to switch between Desk and any customer-facing portal |
| 5 | Notifications | Assignments, mentions, and document events targeted specifically at the logged-in user |
| 6 | Document List (List View) | The default entry point into any DocType — a filterable, sortable table of its records |
| 7 | Filters | Standard and saved filters on any list — the difference between scrolling through everything and finding one record |
| 8 | Actions (Save / Submit / Cancel / Print) | Document-level buttons on a form — which of these actually appear depends entirely on the current user's permissions |
| 9 | Reports link | Aggregate/spreadsheet-style views over a DocType's data, available only for DocTypes the user has read access to |
📋 List View, Form View & Report View
Three view types cover almost every screen in ERPNext. List View shows many documents of one DocType as a filterable table. Form View opens exactly one document for reading, editing, or submitting. Report View shows many documents again, but grouped, aggregated, and pivotable rather than row-by-row — the same underlying data, read for a different purpose.
That progression isn't a strict pipeline every user walks through — it's a description of who tends to live in which view. A clerk mostly works in List and Form View all day; a manager mostly checks a Dashboard and drills into Report View when a number looks wrong.
🙋 Normal User Features
A "normal" (non-admin) ERPNext user is not a distinct product tier — it's simply a User whose assigned roles happen not to include System Manager or another administrative role. What that user can typically do:
| Capability | Condition |
|---|---|
| Log in | Account must be enabled |
| View assigned Workspace(s) | Determined by assigned roles |
| Create documents | Requires Create permission on that DocType via a role |
| Edit / submit documents | Requires Write / Submit permission respectively — these are separate grants |
| Use global search (Awesome Bar) | Always available; results are still filtered by the user's read permissions |
| Apply filters on a list | Always available on any list the user can already view |
| Run reports | Requires read access to the underlying DocType(s) |
| Print / export documents | Requires access to the document plus print/export enabled for that DocType |
| Receive notifications | Always, scoped to what's relevant to that user |
| Add comments | On any document the user can already view |
| Add attachments | On documents the user can view/edit, subject to attachment settings |
| See documents assigned to them (ToDo) | Always — assignments are personal and don't require broader role access |
🛡️ System Manager / Administrator Features
The table below shows the typical shape of how three tiers of access differ — not a fixed spec:
| Feature | Normal User | Manager-level Role | System Manager |
|---|---|---|---|
| Create Document | ✓ | ✓ | ✓ |
| Submit | Based on permission | ✓ | ✓ |
| Approve | Usually no | ✓ | ✓ |
| User Management | No | Limited | ✓ |
| Role Management | No | No–Limited | ✓ |
| Customize DocType | No | Limited | ✓ |
| System Settings | No | Limited | ✓ |
| Developer Mode toggle | No | No | ✓ |
🧑💻 Developer Mode (Brief)
Developer Mode is a site-wide setting, not a role or permission in the usual sense — it's typically toggled by a System Manager with server/config access. With it on, changes to DocTypes, Reports, and Pages that would normally live only as rows in the database get exported as JSON/Python files on disk instead, which is what makes them trackable in version control and shippable as part of a custom app. This one setting is the hinge between "customizing a site" and "building a custom Frappe app" — the full workflow it enables (creating DocTypes as code, writing controllers, packaging an app) is covered in depth in Part 7: Custom Frappe App Development.
⚠️ Common Permission Mistakes
| Mistake | Why it bites you |
|---|---|
| Granting System Manager broadly "to save time" | Destroys the audit value of roles — once everyone is effectively an admin, "who can do X" stops being an answerable question |
| Confusing Role Permission with User Permission | Assuming a role grant alone restricts a user to their own records — it doesn't; without a User Permission, a role that can read a DocType can read every record of it |
| Forgetting Cancel/Amend need their own grant | Write permission does not imply Cancel or Amend on submitted documents — these are separate checkboxes in the Role Permission Manager and are easy to leave unset |
| Only testing as Administrator | Administrator/System Manager bypasses most permission checks, so a permission bug for a restricted role can sit invisible until a real user hits it in production |
| Over-customizing Role Permission Manager for approval chains | A static role check can't express "only the document's own reporting manager may approve it" — that needs a stateful Workflow, not a bigger permission matrix |
➡️ What's Next
With the permission chain now covered link by link, Part 3: Modules & Business Workflows goes module by module through the actual business documents these roles and permissions get applied to — Selling, Buying, Stock, Manufacturing, HR, and the rest. If you landed on this article first, Part 1: The Architecture Guide covers the foundational architecture, installation, and database concepts this series builds on.