Perm Level, short for Permission Level, is a field-level permission system in ERPNext and Frappe. It lets administrators control access to sensitive fields within a DocType without hiding or restricting the entire document.
What Perm Levels Control
Every field in a DocType has a Perm Level. By default, fields are at perm level 0. Fields at level 0 are controlled by the normal permissions for the DocType.
When a field is assigned a higher perm level, such as 1 or 2, users need a matching permission row for that level in Role Permission Manager. Without that matching permission, the user may still be able to open the document, but the higher-level field can be hidden or read-only depending on the configured permissions.
Why Perm Levels Are Useful
Perm levels are useful when most users should work with a document, but only some users should see or edit sensitive information. This avoids creating separate DocTypes or custom workflows just to protect a few fields.
- Sales: A sales user may create a quotation, while only a manager can edit the discount approval field.
- HR: An HR user may view an Employee record, while salary details are available only to payroll roles.
- Accounts: A user may view a supplier invoice, while bank or tax-related fields are restricted to accounts managers.
- Support: A support user may update ticket details, while internal escalation notes are visible only to senior users.
How Perm Levels Work
- A field is assigned a perm level in the DocType or Customize Form.
- Role Permission Manager is used to define what each role can do at each perm level.
- When a user opens a document, ERPNext checks both the user's roles and the permission level of each field.
- If the user has permission for the field's perm level, the field is available according to the allowed actions, such as read or write.
- If the user does not have permission for that perm level, the field is restricted even if the user can access the document itself.
Example
Suppose a Sales Order has these fields:
- Customer at perm level 0
- Items at perm level 0
- Delivery Date at perm level 0
- Approved Discount at perm level 1
- Management Remarks at perm level 2
A Sales User with permission only at level 0 can work with the regular sales order fields. A Sales Manager with level 1 permission can also read or update the Approved Discount field. A Sales Director with level 2 permission can access Management Remarks as well.
Perm Levels And Role Permission Manager
Perm levels become useful only when they are paired with role permissions. In Role Permission Manager, each permission row has a Level value. That value must match the field's perm level.
For example, if a field is set to perm level 1, a role needs a permission row for level 1 on that DocType. The row can then allow actions such as read, write, create, submit, cancel, or amend depending on the DocType and business requirement.
Good Practices
- Keep most fields at perm level 0.
- Use higher perm levels only for fields that genuinely need extra control.
- Use clear field labels so restricted fields are easy to identify during configuration.
- Test permissions with a non-administrator user before relying on the setup.
- Avoid creating too many levels, because permission rules can become hard to audit.
- Document why each restricted field was assigned a higher perm level.
Common Mistakes
- Setting a field to level 1 but not adding level 1 role permissions: Users may lose access to the field unexpectedly.
- Assuming document access means field access: A user can have access to the document but still not have access to higher-level fields.
- Using perm levels instead of workflow approvals: Perm levels control field access. They do not replace approval workflows where business process control is required.
- Testing only as Administrator: Administrator access can hide permission problems. Always test with the target role.