Roles and permissions

The Role Management Tool at a glance

Role Management is the control panel for staff accounts and permissions. It opens only for admin accounts that hold the Management Tool Access flag. If you have it, the tool shows in your menu. If you do not, the link is hidden and opening the page sends you to a no-access screen. Every action re-checks the flag on the server, so the protection cannot be bypassed.

The header shows two buttons, Apply Commands and AI Help, and a summary bar with the number of users on the allowlist, the number of roles customized from their built-in defaults, and the total individual exceptions. Below that are five tabs: Users, Role Defaults, Individual Exceptions, System Info, and Email Routing.

Two safety rules protect the flag itself. You cannot remove your own Management Tool Access, and only admin accounts show the toggle. For other roles the Users tab shows N/A.

The four roles and how scope works

There are four built-in roles. Their codes are fixed, though the display names can vary per deployment. Administrator has global scope across all Branches and regions. Regional VP is scoped to the Branches in their assigned region. Branch Executive is scoped to their one assigned Branch. Member has no scope and minimal access.

Scope is a hard filter that sits under capabilities. An RVP with no region assigned sees no Branches at all, so always set the region. Having a view capability never lets someone see data outside their region or Branch. Only the Out-of-Scope capabilities loosen that boundary.

Anyone who signs in but is not on the allowlist is treated as a member by default, which typically means no staff access. Login itself is gated by your union's allowed email domains, not by the allowlist, so removing a user does not block their sign-in. It only strips their access.

Adding and editing staff users

The Users tab lists every account on the allowlist with stat cards for each role, a search box, and a sortable table. Each row shows the user's email, role, scope, the number of overrides on them, the Tool Access toggle for admins, and Edit and Remove actions. Clicking an Overrides badge jumps straight to Individual Exceptions for that user.

Only admin and RVP accounts are created here. Branch Executives are managed in the Branches module and appear here read-only, marked Ext., though you can still give them individual exceptions. Re-adding an email that already exists replaces that account's row and resets its overrides and Tool Access, so use Edit when you only want to change one thing. Creating an account does not send an invitation. The person simply signs in with their work email.

On admin and RVP accounts you can also upload two signature images used on Grievance paperwork: a light signature for the on-screen UI and a dark signature for the printed Step 1 form. Files must be PNG or JPEG, up to 5 MB. They upload immediately without pressing Save Changes, and Clear removes them.

1. 1Open Role Management and stay on the Users tab.
2. 2Click + Add Admin or + Add RVP.
3. 3Enter the person's email. For an RVP, choose the required Region.
4. 4Click Add Admin or Add RVP. The person can now sign in with that email.
5. 5To change a role, scope, or flag later, use Edit instead of re-adding. Only changed fields are sent, and a role or scope change can take up to about 30 seconds to reach the user's own sessions.

Setting role defaults

The Role Defaults tab is a capability matrix with one row per capability and one column per role. There are 47 capabilities in total, organized into groups you can filter with the pills along the top. Hovering a capability name shows a tooltip describing exactly what it gates. Each column header shows how many are on for that role.

Each role ships with code defaults built into the deployment. The first time you change a toggle, a database override is created for that role, shown with a DB badge plus who last changed it and when, and from then on the database version wins. All On and All Off set every capability for a role at once, and Reset deletes the database customization so the built-in defaults apply again.

Toggles save immediately. Role-default changes are cached and take effect within about 30 seconds across all active sessions, so allow half a minute and a page reload before checking.

1. 1Open the Role Defaults tab.
2. 2Use the group pills to narrow the matrix to a feature area if you like.
3. 3Toggle the capability on or off in the column for the role you want to change.
4. 4Wait about 30 seconds for the change to propagate, then have affected users reload.
5. 5To undo a role's customization entirely, use Reset to return it to the built-in defaults.

Granting individual exceptions

Sometimes one person needs more or less than their role allows. The Individual Exceptions tab lets you Grant or Deny specific capabilities for a single user, overriding their role default. Pick a user from the dropdown, or arrive pre-selected by clicking an Overrides badge in the Users tab. Each capability row has a three-state control: Inherit follows the role default, Grant forces it on, and Deny forces it off. An Effective column shows the final result for that user.

This is also how you suspend someone without losing their setup. There is no separate deactivate state, so instead of deleting an account you can Deny the capabilities you want to cut off and flip them back to Inherit later. Clear All Overrides resets a user to pure role defaults after a confirmation.

Individual exceptions also take effect within about 30 seconds, so allow up to half a minute and a page reload for a new Grant or Deny to apply everywhere.

1. 1Open the Individual Exceptions tab and choose the user, or click an Overrides badge on the Users tab.
2. 2Find the capability using the filter box.
3. 3Set it to Grant to force it on, Deny to force it off, or Inherit to fall back to the role default.
4. 4Wait about 30 seconds and have the user reload to see the change.

How a permission is decided

When the app checks whether someone can do something, it resolves in a fixed order and the first match wins. An individual override comes first, then the database role default from the Role Defaults tab, then the deployment's built-in code default. So a per-user Grant or Deny always beats the role default, and a customized role default always beats the shipped one.

Sensitive information is protected in layers. Salary, home address, sensitive dates, notes, and changelog each need their own view capability before the block renders at all. Out-of-scope profiles use a separate set of block switches, so a user can see fewer fields on a member outside their region. For Branch Executives, home-address fields are stripped from the server's response regardless of capability, so granting the view capability will not reveal them.

Several safety rails are built in. You cannot delete the last administrator, you cannot delete your own account or remove your own Management Tool Access, and Branch Executive accounts cannot be re-roled or deleted here. Manage those in the Branches module instead.

Bulk changes, System Info, and Email Routing

Apply Commands opens a modal where you run many permission changes at once as plain text lines in the form SET target capability = value. The target is a role code or a user's email, the value is grant, deny, or inherit. Lines are validated live with a preview and per-line results, and invalid lines are skipped. AI Help is a copy-and-paste helper, not a chatbot. It gives you a reference prompt with a Copy Prompt button that you paste into any outside AI assistant to get the matching SET lines, which you then paste back into Apply Commands.

The System Info tab is a read-only reference for how access control works in your deployment. It documents the role hierarchy, the special flags and who holds them, the full capability reference, and key behaviors like the 30-second cache and last-admin protection.

The Email Routing tab controls who the app's automatic emails come from and who is copied. Values saved here are stored in the database and take effect immediately with no redeploy. Each setting resolves database value first, then a deployment environment variable, then the built-in default. From here you manage Grievance and Anniversary senders and CCs, the Anniversary digest send window and exclusions, Comms Calendar reminders, the Mass Email allowed from-addresses, and the unsubscribe list.

1. 1To make batch changes, open Apply Commands and write one SET line per change.
2. 2Watch the live preview, then click Apply to run the valid lines.
3. 3For email senders and CCs, open Email Routing, click Edit on a field, and save.
4. 4Use Reset to default on a field to clear the database value and fall back to the environment variable or built-in default.