Skip to content

role.md

Latest commit

 

History

History
89 lines (70 loc) · 7.47 KB

role.md

File metadata and controls

89 lines (70 loc) · 7.47 KB

Frappe Core Doctype: Role

The Role Doctype is a cornerstone of Frappe's security and permissions model. It allows administrators to define different roles within the system (e.g., "Sales Manager", "Accountant", "HR User"). These roles are then assigned to Users, and permissions to access various Doctypes, Pages, Reports, and specific actions are granted based on these roles.

Core Purpose

  • To define distinct sets of responsibilities and access levels within the Frappe application.
  • To act as the primary entity to which permissions (DocPerms, Custom DocPerms, Custom Roles for Pages/Reports) are assigned.
  • To enable a flexible and granular permission system by assigning one or more roles to each user.
  • To manage user capabilities like Desk Access, Two-Factor Authentication requirements, and default home pages based on roles.

Key Files Defining Role

  • role.json: Defines the schema (fields, properties, permissions) of the Role Doctype itself.
  • role.py: Contains the server-side Python controller logic, handling validations, actions on role changes (like updating user types), and providing utility functions.
  • role.js: Handles client-side JavaScript for the Role form, adding informational messages and navigation buttons.
  • README.md: Provides a brief overview of the Role Doctype.
  • test_role.py: Contains unit tests for the role logic.
  • patches/: Includes migration scripts for schema changes related to Roles over different Frappe versions.

role.json - Schema Definition

This JSON file outlines the structure for each Role document.

  • **autoname: "field:role_name"andnaming_rule: "By fieldname"**: The value entered in the role_name` field becomes the unique name (ID) of the Role document.
  • Key Fields:
    • role_name (Data, Required, Unique): The descriptive name of the role (e.g., "Sales User", "Stock Manager"). This is the primary identifier.
    • desk_access (Check, Default: 1, In List View): If checked, users assigned this role are granted access to the Frappe Desk (the main application interface). If unchecked, the role is typically for Website Users or API-only access.
    • disabled (Check, Default: 0): If checked, the role is considered disabled. The system logic in role.py will remove this role from all users it was assigned to. Standard system roles cannot be disabled.
    • is_custom (Check, Default: 0, In List View): A flag indicating whether the role was created by a user/administrator (custom) or is a standard role provided by Frappe or an installed application. Only Administrators can modify this flag.
    • home_page (Data): Allows specifying a custom landing page (route, e.g., /app/user-dashboard) for users whose primary role is set to this one.
    • restrict_to_domain (Link to Domain): If domain separation is active, this field can restrict the applicability of the role to a specific domain.
    • two_factor_auth (Check, Default: 0): If checked, this role can be configured to enforce Two-Factor Authentication for users, often in conjunction with system-wide 2FA settings.
  • Permissions (for the "Role" Doctype itself):
    • Only users with the "System Manager" role can create, modify, and delete Role documents.
  • Other Properties:
    • track_changes: 1 - Modifications to Role definitions are versioned.
    • translated_doctype: 1 - The role_name can be translated into different languages.
  • Module: "Core"

role.py - Server-Side Logic

The Python controller for the Role Doctype manages critical aspects of role behavior and its impact on users.

  • STANDARD_ROLES Constant: Defines a tuple of core system roles ("Administrator", "System Manager", "Script Manager", "All", "Guest") that have special handling and restrictions (e.g., cannot be renamed or disabled).
  • Role(Document) Class:
    • before_rename(): Prevents renaming of STANDARD_ROLES.
    • after_insert(): Clears the "roles" cache for the "Administrator" user.
    • validate():
      • If disabled is checked, calls disable_role().
      • Ensures "Guest" role always has desk_access = 0.
      • Validates the home_page path and clears routing cache if it changes.
    • disable_role(): Prevents disabling STANDARD_ROLES and calls remove_roles() for other roles.
    • remove_roles(): Deletes all "Has Role" entries linking this role to users, effectively unassigning it, and clears relevant caches.
    • on_update(): If the desk_access property of the role has changed, it calls update_user_type_on_change().
    • update_user_type_on_change(): This important method iterates through all users assigned the modified role. It re-evaluates each user's "User Type" (System User vs. Website User) based on their combined roles and updates it if necessary. This ensures that if a role loses desk access, users who relied solely on that role for desk access are correctly re-classified.
  • Global Utility Functions:
    • get_info_based_on_role(): Retrieves specific information (e.g., email addresses) for all enabled users assigned a given role.
    • get_users(): Returns a list of usernames assigned a specific role.
    • role_query() (Whitelisted): Provides a search function for Link fields pointing to "Role", typically filtering for non-custom, non-"All" roles.

role.js - Client-Side Logic

The client-side script enhances the Role form with informational messages and quick navigation.

  • refresh(frm):
    • Displays informational comments in the form's dashboard for special roles like "All" and "Desk User" to clarify their system-wide implications.
    • Makes the is_custom checkbox read-only for users other than "Administrator".
    • Adds a "Role Permissions Manager" button that navigates to the Permission Manager, pre-filtered for the current role.
    • Adds a "Show Users" button that navigates to the User list, filtered to show users assigned the current role.

README.md Overview

The README concisely explains that roles are assigned to users and permissions on Doctypes are defined based on these roles. It also lists key standard roles.

How Roles Are Used

  1. Definition: System Managers create and define Roles (e.g., "Accountant", "Salesperson").
  2. Assignment to Users: Each User in Frappe is assigned one or more Roles through the "User" Doctype (in its "Roles" child table, which uses the "Has Role" Doctype).
  3. Permission Assignment:
    • Doctype Permissions: In the "DocType" definition (or via "Custom DocPerm"), permissions (read, write, create, delete, submit, etc.) for various Doctypes are granted to specific Roles at different permission levels.
    • Page/Report Permissions: Using "Custom Role", specific Pages and Reports are assigned to Roles to control access.
  4. Access Control: When a user attempts to access a document, view a page/report, or perform an action:
    • Frappe's permission engine checks all the roles assigned to that user.
    • It then checks the permission rules defined for those roles against the target resource (Doctype, Page, Report).
    • The most permissive rule usually applies (though specific configurations can alter this).
  5. UI & Behavior: Roles can also influence UI aspects like the default home_page for a user and whether they have desk_access.

Roles are the linchpin of Frappe's robust and flexible security model, enabling detailed control over data access and system functionality.