Skip to main content

User Role Mapping

The User Role Mapping module (also known as Access Management) is the central command station where you determine exactly who has access to what within your organization.

Why This Page Exists​

In any growing organization, employees change departments, new people are hired, and contractors need temporary access. Without a centralized "mapping" system, administrators would have to manually open every single user's profile and check or uncheck hundreds of individual permissions. This would be tedious, error-prone, and a massive security risk.

User Role Mapping solves this by using a Role-Based Access Control (RBAC) model.

Instead of configuring permissions for people, you configure permissions for roles. Then, you simply drop people into the appropriate role.

Because of this, managing access becomes infinitely easier and safer:

  1. When an employee joins, you assign them one role, instantly giving them exactly what they need.
  2. When an employee leaves, you remove them from the role, instantly revoking everything.
  3. When a team needs a new tool, you add the permission to their role once, and everyone on the team gets it simultaneously.

From Employee Joining to Feature Access​

Understanding the lifecycle of an employee's access will make using this page intuitive.

  1. Employee Joins: A new person is hired.
  2. User Account Created: They are invited to the platform.
  3. Administrator Chooses Role: An admin looks at the available roles (e.g., Finance, Marketing).
  4. User is Mapped to Role: The admin uses the User Role Mapping page to assign the employee to that role.
  5. Role Contains Permissions: The role already contains a pre-approved list of permissions.
  6. Permissions Determine Capabilities: The platform's security system reads these permissions.
  7. Employee Works Securely: The employee is granted access to the specific modules and buttons they need, while everything else remains hidden and protected.

The Mental Model: Three Connected Columns​

To use this page effectively, you must understand the relationship between the three main columns you see on the screen.

  1. ROLE (Left) = What kind of access group are we managing?
  2. ASSIGNED MEMBERS (Middle) = Which people currently belong to that group?
  3. PERMISSIONS (Right) = What are those people allowed to see and do?

📸 Screenshot placeholder: URM-01

Capture: Open User Role Mapping. Do not select a role yet.

Suggested caption: The User Role Mapping page acts as a three-column control center for organizational access.

Roles & Permissions vs User Role Mapping​

It is very common to confuse the Roles & Permissions page with the User Role Mapping page.

  • Roles & Permissions is where you build the blueprint. You define what the roles are and what they should do.
  • User Role Mapping is where you execute the blueprint. You connect actual, living people to those roles and inspect their access.
FeatureRoles & PermissionsUser Role Mapping
Primary focusCreating the rolesAssigning people to roles
Create a new role✅ Yes✅ Yes (Quick add)
Delete a role✅ Yes✅ Yes (If zero members)
Assign users to a role❌ No✅ Yes
View which users have a role❌ No✅ Yes
Manage permissions for a role✅ Yes✅ Yes

Field & Control Reference​

Here is a quick reference guide to every major button and control on the page.

UI ElementPurposeWhen to UseResult
Roles List (Left)Lists all access groupsTo inspect a specific access profileLoads members and permissions in the other columns
+ (Plus) Button (Members)Assign a userWhen a new employee needs accessUser is added to the role
Trash Icon (Members)Revoke accessWhen an employee changes teamsUser loses all role permissions immediately
Search PermissionsFind a capabilityWhen dealing with large permission listsInstantly filters visible permissions
Category FilterNarrow modulesWhen focusing on a specific area (e.g., Security)Hides unrelated categories from the list
Checkbox (☑/☐)Grant/revoke capabilityWhen tweaking a role's accessMarks the permission as changed (unsaved)
Select All / Deselect AllBulk manage a moduleWhen granting full access to a specific toolInstantly checks/unchecks all permissions in that module
Save ButtonPersist changesAfter modifying checkboxesUpdates the role's permissions permanently

Adding and Managing Members​

How to Assign an Employee to a Role​

  1. Select the desired role in the Roles (left) column.
  2. In the Assigned Members (middle) column, click the + (Plus) button at the top right.
  3. A dropdown menu appears showing a list of users who do not currently have this role.
  4. Use the Search bar to find a specific person by name or email.
  5. Click their name to confirm the assignment.

📸 Screenshot placeholder: URM-02

Capture: Click on a standard custom role (e.g., "Finance Team").

Suggested caption: Selecting a role instantly reveals who has it and what they can do.

📸 Screenshot placeholder: URM-03

Capture: Click the + button in the Assigned Members column.

Suggested caption: Searching and adding an employee to the selected role.

⚙️ What happens behind the screen?​

  • User View: The user's name immediately appears in the middle column under the role.
  • System View: The system fires an API request (PUT /org/users) to overwrite the user's role_id. Because users can only have one primary role, assigning a user automatically strips them of any previous role they had.

Removing a Member from a Role​

  1. Select the role they currently belong to.
  2. Find their name in the middle column.
  3. Click the Trash icon next to their name.
  4. Confirm the warning prompt.

📸 Screenshot placeholder: URM-09

Capture: Click the Trash icon next to a member's name.

Suggested caption: Confirming the removal of an employee from a role.

warning

Removing a member strips them of their role entirely. They instantly lose all permissions associated with that role. If they are actively logged in, menu items and modules will disappear from their screen upon their next navigation or refresh.

⚙️ What happens behind the screen?​

  • User View: The user vanishes from the middle column.
  • System View: The system fires an API request (PUT /org/users) setting their role_id to null.

The "No Users Assigned" State​

If you select a role and the middle column says "No users assigned", it is a completely normal state. It simply means the role is dormant.

📸 Screenshot placeholder: URM-04

Capture: Select a role that has zero members.

Suggested caption: A dormant role with zero assigned members.

info

An empty role does not grant access to anyone until users are assigned. It acts as a standby template.

Managing Permissions​

The right column allows you to edit the exact capabilities assigned to the role.

Checking and Unchecking​

  • Click a checkbox to grant (☑) or revoke (☐) a capability.
  • Saving: Changes are not automatically saved. When you make a change, a Save button will appear at the top of the column. You must click Save to apply the changes to the database.

📸 Screenshot placeholder: URM-05

Capture: Check or uncheck a single permission. Do not save yet.

Suggested caption: Unsaved permission changes reveal a Save button.

danger

Changing permissions affects every single member assigned to the selected role. Review the Assigned Members list carefully before saving broad permission changes.

Searching and Filtering​

If your organization has many modules, finding a specific permission can be overwhelming.

  1. Search Bar: Type a word (like "invoice"). The system filters instantly. It searches the permission description, code, module name, and category.
  2. All Categories Dropdown: Use this to hide unrelated modules. Selecting "Security" will hide all Marketing and Finance modules.

📸 Screenshot placeholder: URM-06

Capture: Type a keyword into the permission search bar.

Suggested caption: Filtering the massive permission list using a simple keyword search.

Select All / Deselect All​

When you expand a module (e.g., "Orbit Assistant"), you will see a Select All button.

  • Clicking this instantly checks every permission within that specific module only. It does not check every permission in the entire organization.
  • If all permissions are already checked, it turns into a Deselect All button.

📸 Screenshot placeholder: URM-08

Capture: Expand a module block in the permissions list.

Suggested caption: Quickly granting full access to a specific module using Select All.

The Owner / Administrator Role (Special Behaviour)​

You will notice a role on the left labeled with an Admin badge (often called "Owner" or "Super Admin"). This role behaves very differently from custom roles to protect the security of your organization.

Administrator Full Access​

When you select the Owner role, the right permissions column becomes faded out and completely unclickable. A warning message appears stating: "Administrator role — full access".

📸 Screenshot placeholder: URM-07

Capture: Select the Owner / Admin role.

Suggested caption: The Owner role bypasses permission checks entirely and cannot be edited.

Why is it disabled? This is an intentional security safeguard. The system Owner automatically bypasses all permission checks. They have access to every feature currently in the platform, and every feature that will ever be added. Because they have universal access, checkboxes are irrelevant and locked to prevent accidental lockouts.

"Owner Only" Member Assignment​

If you are logged in as a standard administrator (not the ultimate Organization Owner), the + button in the Assigned Members column disappears when the Owner role is selected. Instead, you see a padlock reading "Owner only".

Only the literal Organization Owner (or a platform Super Admin) is allowed to add new members to the Owner role. This prevents lower-level administrators from escalating their own privileges.

Common Scenarios​

Here are some realistic business examples of how this page is used.

Scenario 1: The New Finance Employee​

A new employee joins the Finance department.

  1. The administrator selects the Finance role.
  2. They click + and assign the new employee.
  3. The employee inherits all Finance permissions instantly, allowing them to view expenses and budgets without the administrator ever needing to check a single permission box.

Scenario 2: An Employee Changes Departments​

An employee transfers from Marketing to Finance.

  1. The administrator selects the Finance role.
  2. They click + and assign the employee.
  3. What happens? The system automatically removes the employee from the Marketing role and applies the Finance role. The employee loses access to the CRM and gains access to the budget tools immediately.

Scenario 3: Temporary Roles With No Members​

You create a "Summer Intern" role in January and configure all the permissions. The role sits at "0 Members" until June. This is perfectly normal and safe—nobody has the access until you assign the interns in June.

Scenario 4: Creating a Read-Only Team​

You create an "Auditor" role. You go through the Permissions column and only check boxes that start with "View" or "Read", leaving all "Delete" and "Create" boxes unchecked. You save the role. When you assign external auditors to this role, they can look at data but physically cannot change anything.

Before You Change Permissions Checklist​

Before clicking the Save button on permission changes, quickly run through this mental checklist:

  • Confirm correct role: Look at the left column. Is the correct role highlighted in blue?
  • Check Assigned Members: Look at the middle column. Are you okay with all of these people receiving this change?
  • Verify the Action: Are you checking (granting) or unchecking (revoking)?
  • Review Bulk Actions: If you used "Select All", are you sure you want them to have Delete/Destructive permissions for that module?

Troubleshooting​

ProblemPossible ReasonWhat to Check / Do
I added someone but cannot find them in the list.They might be assigned to a different role.Use the search bar in the user assignment dropdown. If they are in another role, reassign them.
I cannot edit Owner permissions.It is a protected system role.This is intentional. Owner roles bypass all permission checks and are permanently locked.
The + button is missing.You selected the Owner role, but you are not the Organization Owner.Look for the "Owner Only" warning. Only the true Organization Owner can assign other Owners.
I changed a checkbox but nothing happened.You forgot to save.Changing a checkbox marks the page as "dirty". You must click the Save button at the top to apply changes.
I tried to select a different role but got a popup warning.You have unsaved permission changes.The system protects you from losing work. Click "Cancel", then click Save, then switch roles.
I cannot delete a role.The role still has assigned members, or it is a system role.Look at the middle column. If there are members, remove them first. (System roles can never be deleted).

📸 Screenshot placeholder: URM-12

Capture: Attempt to switch roles while having unsaved permission changes.

Suggested caption: The system warns you if you attempt to leave without saving your permission changes.

FAQ​

Can one user have multiple roles?
No. In Orbit Resolve, a user has exactly one primary organization role. Assigning a new role automatically replaces their previous role.

Do permission changes save automatically?
No. You must click the Save button.

What does Select All do?
It checks every permission within that specific module block (e.g., General Profile). It does not check every permission in the entire system.

What happens if I change permissions for a role with many users?
The change applies to all of them instantly. The next time they refresh their browser or navigate to a new page, the UI will update to reflect their new capabilities.

Technical Reference — Developers & QA​

This section contains implementation details verified directly from OO-frontend source code (/src/routes/org/OrgAccessPage.tsx).

Implementation Details​

  • Route Registration: Mapped to /org/userrole in AppRoutes.tsx and menu-overrides.ts. Protected by the org.userrolesmap.view permission hook.
  • Component: OrgAccessPage.tsx. It handles its own complex state (roles, users, matrix, expanded modules, search queries).
  • Role Selection Logic: Clicking a role triggers an API call (GET /org/roles/permissions?id={id}) to hydrate the checkboxes. It also filters the global users array locally to populate the middle column.
  • Dirty State Handling: The isDirty state tracks unsaved permission toggles. If isDirty is true and a user clicks a different role, a window.confirm dialog intercepts the navigation to prevent data loss.
  • Owner/Admin Protection: Roles with is_org_admin or is_system_role disable the permission UI completely. Furthermore, member assignment to these roles is restricted locally by comparing the logged-in user's ID against orgOwnerId (fetched fresh from GET /org/users to prevent stale JWT token spoofing).

API Interactions​

ActionMethodEndpointTriggerResult
Load RolesGET/org/rolesPage mountPopulates left column.
Load MatrixGET/org/roles/matrixPage mountPopulates right column structure.
Load UsersGET/org/usersPage mountPopulates middle column & gets Org Owner ID.
Load PermissionsGET/org/roles/permissions?id={id}Selecting a rolePopulates active checkboxes.
Save PermissionsPOST/org/roles/permissions?id={id}Clicking SaveSubmits array of permission UUIDs.
Assign MemberPUT/org/users?id={user_id}Clicking a user in + dropdownPayload: { role_id: new_role_id }. Overwrites previous role.
Remove MemberPUT/org/users?id={user_id}Clicking Trash on a memberPayload: { role_id: null }. Revokes role.
Delete RoleDELETE/org/roles?id={id}Clicking Trash on a roleRemoves role (blocked by backend if user_count > 0).

QA Verification Checklist​

When testing this component, ensure the following flows are verified:

  • Role Selection: Clicking different roles updates the member list and fetches the correct permissions.
  • Dirty State Interception: Toggling a permission and clicking a different role triggers a confirmation warning.
  • Member Assignment: Assigning a user successfully updates the UI and removes them from the available users dropdown.
  • Member Removal: Clicking trash successfully removes the member and handles the API response gracefully.
  • Select All / Deselect All: Verifying the toggle correctly adds/removes exactly the UUIDs for that specific module block to the payload.
  • Search & Filter: Search string matches against description, code, module name, and category name simultaneously.
  • Owner Role Protections: The UI correctly locks permissions for is_org_admin. The + member button is hidden unless the active session matches orgOwnerId or is a Super Admin.
  • Empty State: A role with zero users displays the "No users assigned" graphic rather than breaking or showing a blank column.

Downstream Impact​

Changes made on this page propagate globally:

  1. User Role Mapping assigns the role_id to a User.
  2. Role Permissions link the role_id to specific permission codes (e.g., org.users.view).
  3. Frontend Permission Checks (e.g., hasPermission() from useAuthStore) evaluate these codes locally.
  4. Menu / Page / Action Availability: If a permission is revoked here, the ProtectedRoute wrappers and menu-overrides will instantly unmount the components, hiding navigation items and blocking route access on the client.