Chapter 4 — Users, roles and permissions

Module code: ADMIN Features: user_mgmt, role_mgmt

This chapter explains how access is controlled. It is the chapter administrators read most often, because almost every "I cannot see the screen" question is answered here.

4.1 How permission works, in one page

Access is decided at three levels.

              ┌──────────────────────────────────────────┐
              │  MODULE      e.g. INVENTORY              │
              │    │                                     │
              │    ├── FEATURE   item_catalog            │
              │    │     └── rights: view create edit    │
              │    │               delete import export  │
              │    │               approve               │
              │    ├── FEATURE   stock_operations        │
              │    └── FEATURE   inventory_reports       │
              └──────────────────────────────────────────┘

1. Module — a broad app area, such as INVENTORY, HR or SCHOOL.
2. Feature — a group of screens inside it, such as item_catalog.
3. Rights — what you may do with that feature:

View is the gate. If a user lacks view on a feature, the menu item does not appear and the URL is refused even if typed directly. This is deliberate: hiding the menu alone would not be security.

Scope

On top of the rights, a permission can be limited by scope:

Own data only is what makes a self-service account safe: an employee can see their own attendance and payslips and nobody else's.

Two ways to grant

Rights from all a user's active roles, plus any direct grants, are added together. There is no "deny" — a user has a right if any source gives it.

Superusers bypass all of this and can see everything. Keep the number of superusers small.

4.2 Creating a user

Screen: /users/ → Create, or /users/enhanced-create/ for the guided form.

1. Go to /users/ and select Create user.
2. Enter: - Username — used to sign in. It cannot be changed later, so agree a convention first (firstname.lastname works well). - Email — where the activation link goes. Required. - First and last name. - Company and department if the form offers them.
3. Choose how the password is set: - Send activation link (recommended) — the user chooses their own password from the emailed link. You never see or hold their password. - Set a password now — for cases where email is not available. Tell the user to change it at first sign-in.
4. Assign at least one role. A user with no role can sign in but sees an empty home screen.
5. Link an employee record if this person is an employee. This link is what turns on their attendance, leave and payslip screens. Without it, HR self-service is simply absent for them.
6. Save.

Re-sending an activation link

If the user never received or already used the link, open /users/<id>/ and select Send activation link again. The previous link stops working.

Activating and deactivating

• /users/<id>/deactivate/ blocks sign-in immediately. The account and its history remain.
• /users/<id>/activate/ restores it.

Always deactivate rather than delete when someone leaves. Their name must remain attached to the documents they created.

4.3 Creating a role

Screen: /role-management/

1. Go to /role-management/ and select Create role.
2. Enter: - Name — what the role does, from the user's point of view: Warehouse Supervisor, Accounts Officer, Class Teacher. - Code — a short unique identifier. - Description — write down what the role is for. Six months later this is what stops the role drifting.
3. Save. The role now exists with no permissions.
4. Open Permissions on the role (/role-management/<id>/permissions/).
5. You are shown a grid of every module and feature with a tick box per right. Tick what the role needs.
6. Save permissions.

Practical advice on designing roles

• Start from the job, not the screen. List what the person must accomplish, then tick the minimum that allows it.
• Give view first, then add. It is easier to add a missing right on request than to discover months later that everyone can delete invoices.
• Do not build one role per person. If you have forty roles for forty users, the system is being used as direct permissions with extra steps.
• Approve is not edit. A person who may approve a purchase order usually should not be able to edit it. Keeping these separate is the control.

Assigning a role to a user

Either direction works:

• From the user: /users/<id>/ → Assign role.
• From the role: /role-management/<id>/users/ → add users.
• In bulk: /role-management/user-assignments/.

When assigning, you may set the scope — restricting the role to particular companies or departments for that user only.

4.4 Direct user permissions

Screen: /users/<id>/advanced-permissions/

Use this only for genuine exceptions. The screen shows the same module/feature grid as a role, but the grants apply to this one user.

To see the result of roles plus direct grants, use /users/<id>/effective-permissions/. This is the screen to open when someone reports unexpected access — it shows what the user actually has, and where each right came from.

4.5 The authorisation screen

Screen: /authorization/

A single list of users with their status and permission summary, for reviewing access across the workspace rather than one user at a time. Use it for periodic access reviews: sort by role, confirm each person still needs what they hold, and deactivate leavers.

4.6 Menu management

Screen: /administration/menu/

The sidebar menu is data, not code, so it can be adapted to how your organisation talks about its work.

Adding a menu item

1. Select New menu item.
2. Enter the label as users should read it.
3. Choose the target screen from the URL name list. The field offers only real screens, so a menu item cannot point at a page that does not exist.
4. Choose the permission module and feature. The item then appears only for users who hold view rights on it. Leave this blank only for items everyone may use.
5. Choose the parent item, or leave blank for a top-level entry.
6. Set the sequence to control its position, or reorder by dragging afterwards.
7. Save.

Export the menu before making large changes. The export file is a complete backup and can be re-imported to undo.

4.7 Common tasks

"A new starter needs the same access as an existing colleague"

1. Open the colleague at /users/<id>/ and note their roles.
2. Create the new user (section 4.2).
3. Assign the same roles.
4. Check /users/<new-id>/effective-permissions/ — if the colleague had direct grants as well, they will not have been copied, and this screen shows the gap.

"Someone has moved department"

1. Update the department on their employee record in HR.
2. Review any role assignment scoped to their old department at /users/<id>/, and change or remove the scope.

"Someone has left"

1. Deactivate the user at /users/<id>/deactivate/.
2. Reassign any open tickets, tasks or approvals assigned to them.
3. Do not delete the account.

"A screen must be locked down immediately"

Remove view on the feature from every role that grants it. Because view is the gate, this closes the screen for everyone at once, including direct URL access.

4.8 Troubleshooting

4.9 Reference

Every module code and feature code in the product, with the screens each one unlocks, is listed in Appendix A — Permission reference.