# Understanding Roles and Privileges ## Overview HMIS uses a two-layer access control model: **Roles** and **Privileges**. Every feature in the system is protected by a named privilege. A role is a named collection of privileges that can be assigned to many users at once. Individual privileges can also be granted or denied at the user level for fine-grained control. Understanding this model is essential for any administrator setting up user access. ## The Two Layers ### Layer 1: User Roles (Broad Access) A **User Role** is a template for access. When you create a role called "OPD Cashier" and grant it the privileges `OpdBilling`, `Cashier`, and `ShiftHandoverAcceptAsCashier`, then every user assigned that role gets those three privileges automatically. Roles are best for: - Standard job positions where everyone needs the same access - Groups of staff doing identical functions across different departments - Making it easy to onboard new staff — assign the role and they are ready ### Layer 2: User-Specific Privileges (Fine-Grained Control) Beyond their role, a user can have **individual privileges** added or removed. These are set per-department, meaning the same user can have different access in different departments. Individual privileges are best for: - One-off exceptions ("this nurse also needs billing access in Ward 3") - Temporary elevated access - Restricting a user below their role in a specific context ## The Privilege Tree When you open the privilege management screen (either for a role or for a user), the system displays all privileges in a **checkbox tree**, grouped into categories (e.g. Administration, OPD, Pharmacy, Inward). - Ticking a parent node automatically ticks all privileges in that group - Unticking a child removes only that specific privilege - A half-filled parent checkbox means some but not all children are selected You must click **List Privileges** first to load the tree, then tick/untick as needed, then click **Update** to save. ## Key Administration Privileges | Privilege | What It Controls | |---|---| | Admin | Visibility of the entire Administration menu | | AdminManagingUsers | Create, edit, and deactivate users; manage roles and privileges | | AdminInstitutions | Create and edit institutions, departments, sites, banks, credit companies | | AdminStaff | Create and manage staff and doctor records | | AdminItems | Manage OPD services, item categories, packages, EMR templates | | AdminPrices | Manage all fee configuration | | InwardAdministration | Configure inpatient services | | StoreAdministration | Configure store and inventory | | PharmacyAdministration | Configure pharmacy items | | MembershipAdministration | Configure membership schemes | | HrAdmin | Human resources administration | | LabAdiministrator | Configure laboratory investigations | | ChangeMyPassword | User can change their own password | | ChangePreference | User can manage their own preferences | ## How the System Checks Access Every page and menu item in the system checks `webUserController.hasPrivilege('PrivilegeName')` before rendering. If the check fails: - The menu item does not appear - The page shows a "Not Authorised" message This means granting a privilege is sufficient — the user does not need to know a special URL or code. ## Best Practices - Create roles for every common job type before creating users - Grant the minimum privileges needed for the job (principle of least privilege) - Use individual privilege overrides sparingly — they are harder to audit than role-based access - Review access quarterly, especially when staff change roles or departments - Do not assign the top-level `Admin` privilege to any operational (non-admin) user ## Related Features - [Creating and Managing User Roles](Admin-Creating-and-Managing-Roles) - [Assigning Privileges to a Role](Admin-Assigning-Privileges-to-a-Role) - [Creating and Managing Users](Admin-Creating-and-Managing-Users) - [Adding a New Privilege (Developer Guide)](https://github.com/hmislk/hmis/wiki)