Manage Global Roles & Permissions

1. What does this feature do? (High-Level Overview)

Global Roles grant users system-wide access that is not tied to any specific location. Users with a global role are presented with the Admin View at login, which provides a centralized workspace to manage locations, users, tickets, workspaces, and administrative settings across the entire system. This feature is currently available.

2. Who is this for? (Roles & Permissions)

• Superadmin: Full access to all Admin View sections, including Feature Flags. Bypasses every permission check in the system. Should be reserved for trusted system administrators only.
• Admin: Access to all Admin View sections except Feature Flags. Cannot modify the manage_roles permission on any role.

Required permissions:

• use_admin_tools — to access the Administration section within Admin View.
• manage_roles — to create, edit, or delete global roles.
• assign_roles — to assign a global role to a user.
• view_employees — to view the Users list in Admin View.
• impersonate_users — to impersonate a user (Superadmin only).

3. Business Rules & Enforcements

• Admin View is exclusive to global roles. Only users assigned a global role (Superadmin or Admin) see the Admin View card at the location selection screen. Users without a global role never have access to this view.
• Superadmin without locations sees Admin View only. If a Superadmin has no locations assigned, the location selection screen shows only the Admin View card. If they are also assigned to one or more locations, those locations appear as additional cards and are accessible with the role defined at each of those locations — not with Superadmin privileges.
• Superadmin is the only immutable system role. The built-in Superadmin role cannot be deleted or renamed. It is marked with a “System” badge in the roles list. All other roles, including Admin, can be edited or deleted.
• Admin cannot hold or assign manage_roles. The built-in Admin role includes all permissions except manage_roles, preventing Admins from escalating themselves or others to full system control.
• Role assignment is hierarchical. A user can only assign roles that carry fewer permissions than their own. Superadmins are exempt from this constraint and can assign any role freely.
• A role cannot be deleted while assigned to users. If a role is currently assigned to one or more employees, the system blocks deletion. The role must be unassigned from all users before it can be removed.
• Global roles apply across all locations. Permissions granted by a global role are enforced everywhere in the system, regardless of location context.
• Custom global roles can be created with any combination of available global permissions, subject to the assigner’s own permission ceiling.

4. UI Placement

1. Location selection screen — After login, users with a global role see an Admin View card. Clicking it enters the Admin View context.
2. Admin View sidebar — The sidebar in Admin View includes: Home (Workspaces), Users, Insurance, Locations, Reports, Tickets, and Administration.
3. Administration > System Roles and Permissions (/settings/roles) — Lists all global roles. Requires manage_roles permission.
4. Administration > System Roles > Register (/roles/register) — Form to create a new global role.
5. Administration > System Roles > Edit (/roles/list/edit/:id) — Edit an existing global role’s name and permissions.

5. How-To Guide (Step-by-Step)

Scenario A: Creating a custom global role

1. Log in and select Admin View from the location selection screen.
2. In the sidebar, navigate to Administration.
3. Click System Roles and Permissions.
4. Click Register to open the creation form.
5. Enter a descriptive role name (e.g., Billing Supervisor).
6. Browse the categorized permission list and toggle on each permission this role should carry. Hover over a permission to read its description.
7. Click Save. The new role appears immediately in the list and is available for assignment.

6. What happens if…? (Edge Cases / FAQ)

• Q: If a Superadmin is also assigned to a location, do they use Superadmin permissions inside that location?

  • A: No. When a Superadmin enters a specific location from the location selection screen, they operate with the role assigned to them at that location (e.g., BCBA, Manager). Superadmin privileges are only active within the Admin View context.

• Q: Can a user hold both a global role and a location role simultaneously?

  • A: Yes. A user can have a global role and also be assigned a location-scoped role at one or more locations. The contexts are independent — the global role is exercised in Admin View, and the location role governs access when working inside a specific location.

• Q: Why can’t a role be deleted even though it appears to have no active users?

  • A: The system blocks deletion of any role that is currently assigned to at least one employee, including inactive ones. To delete the role, first reassign or remove it from all users, then proceed with deletion.