Manage Location Roles & Permissions

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

Location Roles control what each staff member can see and do within a specific clinic or office location. Owners and Managers can create custom roles, define their permissions, and assign them to employees — all scoped to a single location so that access at one site does not carry over to another. This feature is currently available.

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

• Owner: Can manage roles and assignments within their assigned location(s).
• Manager (with manage_roles): Can manage roles within their location if the manage_roles permission has been explicitly granted.

Required permissions:

• manage_roles — to create, edit, or delete location roles.
• assign_roles — to assign a location role to a user.
• view_employees — to view the employee list for assignment.

3. Business Rules & Enforcements

• Location roles are scoped to a single location. A role created at Location A is only visible and applicable at Location A. It does not appear at any other location.
• All location roles can be edited or deleted. There are no protected or immutable roles at the location level. Any role — including Owner, Manager, BCBA, and RBT — can have its name and permissions changed, or be deleted entirely.
• A role cannot be deleted while assigned to users. If a role is currently assigned to one or more employees at the location, the system blocks deletion. All assignments must be removed before the role can be deleted.
• Only location-scoped permissions are available. When creating or editing a location role, only permissions relevant to location-level operations are shown. System-wide permissions (such as manage_locations or use_admin_tools) are not available for location roles.
• Role assignment is hierarchical. A user can only assign roles that carry fewer permissions than their own at that location. An RBT cannot assign an Owner role, for example.
• A user can only hold one role per location. Assigning a new role to a user at a location replaces their previous role at that location.
• Employees must be assigned to the location first. A location role can only be assigned to a user who is already a member of that location.

4. UI Placement

1. Sidebar > Roles — Visible to users with manage_roles at the current location. Leads to the location roles list for the active location.
2. Roles > List (/location-roles/list) — Displays all roles for the current location with their permission count and user count.
3. Roles > Register (/location-roles/register) — Form to create a new location role with a name and a selection of location-scoped permissions.
4. Roles > List > Edit (/location-roles/list/edit/:id) — Edit an existing location role’s name and permissions.

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

Scenario A: Creating a custom location role

1. Make sure you are in the correct location context (check the location selector in the header).
2. In the sidebar, click Roles.
3. Click Register to open the creation form.
4. Enter a descriptive role name (e.g., Lead BCBA).
5. Browse the permission list and toggle on the permissions this role should carry. Hover over a permission name to read its description.
6. Click Save. The new role appears in the list immediately and is available for assignment at this location only.

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

• Q: What happens to an employee’s access if their location role is edited after assignment?

  • A: Changes to a role’s permissions take effect immediately for all users assigned to that role at the location. No reassignment is needed.

• Q: Can the same employee have different roles at different locations?

  • A: Yes. An employee can be assigned a different role at each location they belong to. For example, they may be a Manager at one location and a BCBA at another.

• Q: Why can’t a role be deleted even though it seems unused?

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