custom_docperm.md

Frappe Core Doctype: Custom DocPerm

The Custom DocPerm Doctype in Frappe is used to define and store custom permission rules for other Doctypes. These rules override or extend the standard permissions defined within a Doctype's own permissions table (which are "DocPerm" records). "Custom DocPerm" allows administrators to tailor access controls without modifying the core definitions of standard Doctypes, ensuring that customizations persist through system updates.

Core Purpose

• To provide a mechanism for creating site-specific permission rules that augment or override the default permissions of any Doctype.
• To enable fine-grained control over user access (read, write, create, delete, submit, etc.) for specific roles and permission levels on a target Doctype.
• To ensure that custom permission settings are stored separately from the standard Doctype definitions, making them upgrade-safe.

Key Files Defining Custom DocPerm

• custom_docperm.json: Defines the schema (fields, properties) of the Custom DocPerm Doctype itself.
• custom_docperm.py: Contains the server-side Python controller logic, primarily for cache management.
• custom_docperm.js: The client-side JavaScript file for the Custom DocPerm form (which is minimal).
• test_custom_docperm.py: Contains unit tests for the server-side logic.

custom_docperm.json - Schema Definition

This JSON file outlines the structure for each Custom DocPerm record.

• autoname: "hash": Each custom permission rule is assigned a unique hash ID as its name.
• Key Fields:
  • parent (Data, Read Only, Search Index): This crucial field stores the name of the Doctype for which this custom permission rule applies (e.g., "Sales Order", "Item", "User").
  • role (Link to Role, Required): The specific user role (e.g., "Sales User", "Accountant") to which this permission rule will grant or deny access.
  • permlevel (Integer, Default: 0): The permission level (0-9) at which this rule applies. This interacts with field-level permissions defined within the target Doctype.
  • if_owner (Check, Default: 0): If checked, this permission rule only applies if the current user is the owner of the specific document instance.
  • Permission Flags (Check type, e.g., read, write, create, delete, submit, cancel, amend, report, export, import, share, print, email, select): A series of checkboxes that determine the specific actions allowed or denied for the given role at the specified permlevel on the parent Doctype.
    • read (Default: 1): Typically, custom permissions start by granting read access.
• read_only: 1: Custom DocPerm records themselves are generally marked as read-only after creation. They are managed through dedicated interfaces like the "Role Permissions Manager" or via "Customize Form" > "Permission Rules", rather than direct editing of Custom DocPerm documents.
• Permissions (for Custom DocPerm Doctype itself):
  • Only "System Manager" role has full CRUD permissions on Custom DocPerm records.
• Module: "Core"
• title_field: "parent": In list views of Custom DocPerms, the name of the Doctype being customized is shown prominently.

custom_docperm.py - Server-Side Logic

The Python controller for Custom DocPerm handles cache invalidation.

• CustomDocPerm(Document) Class:
  • on_update(): When a Custom DocPerm record is created or modified, this method is triggered. Its primary action is to call frappe.clear_cache(doctype=self.parent). This is essential because Frappe heavily caches Doctype metadata, including permission rules. Clearing the cache for the target Doctype (self.parent) ensures that the newly applied custom permission rule takes effect immediately for all users.
  • get_permission_log_options(): This method integrates with Frappe's permission logging system. It specifies that any changes to a Custom DocPerm record should be logged as a modification to the "DocType" Doctype, specifically for the self.parent document (which is the name of the Doctype whose permissions are being customized).
• update_custom_docperm(docperm, values) (Global Function):
  • A utility function that allows for the programmatic update of an existing Custom DocPerm record by its name. It fetches the record, applies the new values, and saves it, bypassing standard permission checks for this administrative task.

custom_docperm.js - Client-Side Logic

The client-side JavaScript for the Custom DocPerm Doctype's own form view is very simple.

• frappe.ui.form.on("Custom DocPerm", { refresh: function (frm) {}, });
  • The refresh function is empty. This indicates that the direct form view of a Custom DocPerm document doesn't require any special client-side behavior. As mentioned, these records are typically not managed by opening their individual forms.

How It's Used

Custom DocPerms are a powerful way to tailor application security:

1. Scenario: You want to allow "Sales User" role to only read "Item" documents but not create or write them, overriding the default Item permissions.
2. Action: A System Manager would typically use the "Role Permissions Manager".
   • They select the "Item" Doctype.
   • They select the "Sales User" role.
   • They uncheck "Write", "Create", "Delete" permissions, leaving "Read" checked (or set specific permlevels).
3. Behind the Scenes: This action creates or updates a "Custom DocPerm" record where:
   • parent: "Item"
   • role: "Sales User"
   • read: 1
   • write: 0
   • create: 0
   • ... and other flags as set.
4. Effect: When any user with the "Sales User" role tries to access "Item" documents, Frappe's permission engine will evaluate both the standard DocPerms for "Item" and any applicable "Custom DocPerms". The Custom DocPerms will take precedence or be combined according to Frappe's permission logic to determine the effective permissions.

Custom DocPerms are crucial for adapting Frappe's permission model to specific business needs without altering the core application code.