Skip to content

custom_role.md

Latest commit

 

History

History
74 lines (56 loc) · 5.91 KB

custom_role.md

File metadata and controls

74 lines (56 loc) · 5.91 KB

Frappe Core Doctype: Custom Role

The Custom Role Doctype in Frappe is used to define specific role-based permissions for accessing Pages and Reports. It does not create new roles in the system (that's handled by the "Role" Doctype) but rather assigns existing roles to particular Page or Report documents, thereby controlling their visibility and accessibility.

Core Purpose

  • To provide a mechanism for setting custom permissions for individual Pages and Reports.
  • To allow administrators to specify which roles can access a particular Page or Report, overriding any default or broader permissions.
  • To ensure these page/report-specific role assignments are stored separately and are upgrade-safe.

Key Files Defining Custom Role

  • custom_role.json: Defines the schema (fields, properties) of the Custom Role Doctype itself.
  • custom_role.py: Contains server-side Python controller logic, including validation and helper functions for retrieving assigned roles.
  • custom_role.js: The client-side JavaScript file for the Custom Role form (which is minimal).
  • test_custom_role.py: Contains unit tests for the server-side logic.

custom_role.json - Schema Definition

This JSON file outlines the structure for each Custom Role permission record.

  • autoname: "hash": Each Custom Role record is assigned a unique hash ID.
  • Key Fields:
    • page (Link to Page): A link to a "Page" document. One of page or report is typically filled.
    • report (Link to Report): A link to a "Report" document. One of page or report is typically filled.
    • ref_doctype (Data): This field is often populated by the system (as seen in custom_role.py) with the ref_doctype of the linked report. This can be useful for context or further permission checks related to the report's underlying data.
    • roles (Table, Options: "Has Role"): This is a child table where each row links to a "Role" Doctype. This table lists all the roles that are granted permission to access the specified page or report. The "Has Role" Doctype is a simple child table usually containing just a role (Link to Role) field.
    • response (HTML): An HTML field, likely used by client-side scripts or specific UIs (like Role Permissions Manager) to display feedback or status messages during permission updates.
  • read_only: 1: Custom Role records are generally marked as read-only after their creation. They are typically managed through dedicated UIs like the "Role Permissions Manager" or within the settings of individual Page or Report documents, rather than by directly editing Custom Role documents.
  • Permissions (for Custom Role Doctype itself):
    • Only "System Manager" role has full CRUD permissions on Custom Role records.
  • Module: "Core"

custom_role.py - Server-Side Logic

The Python controller for Custom Role handles validation and provides utility functions.

  • CustomRole(Document) Class:
    • validate():
      • If a report is linked and the ref_doctype field is empty, this method attempts to fetch and set the ref_doctype from the linked "Report" document's definition. The ref_doctype of a report indicates the primary Doctype it's based on, which can be important for contextual permissions.
    • get_permission_log_options():
      • Integrates with Frappe's permission logging system.
      • When roles for a Page or Report are modified via a "Custom Role" record, this ensures the change is audited correctly against that specific Page or Report document. It logs that the roles field (the child table) was modified.
  • get_custom_allowed_roles(field, name) (Global Function):
    • A utility function designed to be called by other parts of the system (likely Frappe's core permission checking logic for Pages and Reports).
    • field: Expects "page" or "report".
    • name: The name of the specific Page or Report document.
    • It queries the "Custom Role" Doctype to find a matching record for the given Page/Report.
    • If a record exists, it extracts and returns a list of role names from the roles child table.
    • This list represents all roles explicitly granted access to that Page or Report via a Custom Role setting.

custom_role.js - Client-Side Logic

The client-side JavaScript for the Custom Role Doctype's own form view is minimal.

  • frappe.ui.form.on("Custom Role", { refresh: function (frm) {}, });
    • The refresh function is empty. This implies that the direct form view of a Custom Role document doesn't require special client-side behavior. Management of these permissions usually happens through more integrated UIs.

How It's Used

Custom Roles are primarily managed through the "Role Permissions Manager" or directly from Page and Report settings.

  1. Scenario: You want to restrict access to a specific "Sales Analytics" Report to only users with the "Sales Manager" and "Accounts Manager" roles.
  2. Action (via Role Permissions Manager or Report settings):
    • Select the "Sales Analytics" Report.
    • Assign the "Sales Manager" and "Accounts Manager" roles.
  3. Behind the Scenes: This action creates or updates a "Custom Role" record where:
    • report: "Sales Analytics"
    • The roles child table would have two entries: one for "Sales Manager" and one for "Accounts Manager".
  4. Effect: When a user attempts to access the "Sales Analytics" Report:
    • Frappe's permission system will check if any of the user's assigned roles are present in the list of roles defined in the "Custom Role" record for this report (using a function like get_custom_allowed_roles).
    • If there's a match, the user is granted access; otherwise, access is denied (subject to other permission layers like "Allow Guest").

This Doctype provides a targeted way to manage access to specific Pages and Reports, complementing the broader Doctype-level permissions.