Roles & permissions
What a person can open and do in the suite is set by the permissions on their own account. Roles are templates you copy from. This page explains the model and shows how to create templates, apply them and adjust one person.
How it works
- Permissions live on each person. Every account carries its own list of permissions, such as
view_paymentsorapprove_requests. The menu, the pages and the server all check that list. - A role is a template. Role & Permissions holds named sets of permissions (Employee, Head of Department / Unit, Registry Officer…). Applying one copies its permissions onto a person. The person is not linked to the template afterwards.
- So editing a template does not change anyone. People who were given it earlier keep what they had. If you want existing people to have the change, apply the template to them again.
- Two people with the same template can differ, because you can add or remove single permissions for one person.
- The “Role” on a person is different. The Role field on Edit User › Employment (User, Head, Accountant, Administrator…) is used by approval steps of the kind “anyone with a role”. It does not grant permissions by itself.
Administrators (role Administrator or Super Admin) are given every permission.
The role templates
- Search by name or code.
- Add role. Create a new template.
- Permissions. How many permissions each template grants. Select a row to see them all.
The standard templates are described, area by area, in Roles at a glance. Besides those, the hospital has office-holder templates:
| Template (code) | For | Adds |
|---|---|---|
Chairman, Medical Advisory Committee (CMAC_OFFICE) | Head of CMAC | Executive access, without approving payments. |
Director of Administration (DA_OFFICE) | Head of ADMIN | Executive access plus viewing staff and units. |
Director of Finance & Accounts (DFA_OFFICE) | Head of FIN / FIN-021 | Finance and head access, managing voucher types, approving payments. |
Finance Officer (FINANCE_OFFICER) | Staff in Finance units 022–029 | Accounts work plus deciding finance request steps. |
Checking Officer (CHECKING_OFFICER) | Members of FIN-023 | Deciding Checking steps, viewing the vouchers they check. |
Billing Officer (BILLING_OFFICER) | Members of FIN-026 | Accounts work plus deciding refund steps. |
Head of Audit (AUDIT_HOD) | Head of AUDIT | Head access plus read access to finance for pre- and post-audit. |
Audit Officer (AUDIT_STAFF) | Members of AUDIT | Deciding steps routed to the Audit desk, viewing vouchers. |
Registry Officer (REGISTRY_OFFICER) | Registries and the CMD Secretary | Documents, the registry desk and registry export. |
Anyone who decides an approval step needs approve_requests as well as the task itself. Heads have it through their template. Desk staff (Checking, Audit, Finance units) get it from the office templates above. If an approver says the decision buttons are greyed out, this permission is usually missing.
The Internal Auditor (read-only) template is for visiting auditors who only look. The hospital's own audit staff use Audit Officer so that they can decide.
Create or edit a template
- Role name. Required.
- Code. Optional, for example
HR_MGR. The bulk import and the seed look templates up by code. - Visual / JSON. Tick permissions, or paste a JSON list of
true/falsevalues. - Search permissions by name, key or description.
- Show only granted hides what is not ticked.
- Enable all / Clear all. Each area also has All and None. Permissions added in a recent release are marked New.
- Select Add role (or open a template and select Edit).
- Name it and give it a code.
- Tick the permissions. Start from what the job needs day to day; you can add later.
- Select Create role (or Update role).
If the JSON contains a key the suite does not know, saving is blocked until you select Remove unknown keys.
Deleting a template does not take anything away from people created from it. The template itself cannot be restored.
Apply a role to a person
There is no “assign role” button on the template. You copy a template on the person's own page:
- New person: on Add User, choose the template in Copy from role (optional). The permissions panel fills in.
- Existing person: open them, select Edit User, go to the Permissions tab and set the permissions to match the template (for example with Clear all, then the areas and permissions it grants, or by pasting the template's JSON on the JSON tab).
- Select Save Permissions.
- If the job also changes how they approve (they become a head or an accountant), change Role on the Employment tab and select Save Employment.
For office holders, the ICT team can instead re-run npm run db:seed:uath -- --skip-users. It applies the office templates to whoever heads or sits in each office unit, so you only need to get the heads and members right in Departments & Units.
Give one person one extra permission
- Open the person › Edit User › Permissions.
- Search for the permission, for example “export”.
- Tick it and select Save Permissions.
The change is recorded in the audit log as a permission change, with the before and after lists. To see what someone can do without editing, open them and look at the Permissions tab.
After an upgrade: permissions backfill
New releases sometimes add permissions (they show as New in the matrix). Stored templates and people do not get them automatically. After each upgrade the ICT team runs:
- Preview:
npm run permissions:backfill -- --dry-run - Apply:
npm run permissions:backfill
For every template and every person it:
- drops keys the suite no longer knows and adds every current key (off unless granted);
- gives administrators every permission, including new ones;
- adds a few compatibility grants so people keep what they could already do: anyone who could view requests can view their own; heads and approvers can view all requests; memo-template managers get the new memo-template permissions; members and heads of a registry office get
view_registry(skip these with--no-compat).
It only writes rows that change and is safe to run again.