Admin View Users List

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

The Admin View Users List gives authorized administrators a cross-location view of employee accounts so they can monitor access, update account status, and perform security-sensitive actions from one place. It also lets them manage a user’s role and location-specific status together inside the same location assignment flow.

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

• Superadmin / Admin (or any role with view_employees): Can open and review the Users list in Admin View.
• Roles with update_employees: Can update user status, change passwords, and update a user’s status inside a selected location.
• Roles with assign_roles: Can assign or remove global roles and update a user’s role at a selected location.
• Roles with impersonate_users: Can start an impersonation session from the list.

Required permissions by action:

• view_employees — open and view the Admin View Users list.
• update_employees — change user status, change location-specific status, and change password.
• assign_roles — assign/remove global roles and assign location roles.
• impersonate_users — impersonate users.

3. Business Rules & Enforcements

• Admin-view listing is explicit and permission-gated. The list is requested with admin_view=true, and cross-location listing is only allowed when the signed-in user has access_admin_view.
• Default list state is active users. The page initializes with status=active, sorted by name ascending.
• Filters are server-side. Role, status, location, and search filters are sent as query params and applied by the API.
• Location scoping still applies when required. If Admin View bypass is not authorized, user listing remains location-scoped.
• Global role updates require assignment permission. Only users with assign_roles can assign or clear global roles.
• Location assignment is managed one location at a time. The Admin View location action works on one selected location per confirmation.
• Role and status are edited in one modal. For an existing location relation, the modal preloads the current role and the current location-specific status so the admin can update one or both values together.
• Location status uses the location-level values only. In this flow, the available location-specific statuses are Active, Inactive, Black list, and Incoming.
• Creating a new location relation requires both fields. If the user is not yet assigned to the selected location, the admin must provide both a role and a status in the same flow.
• Creating a new location relation requires both permissions. Admin View only allows creation of a new location relation when the signed-in user can update both the role and the status for that location assignment.
• If both values change, role is applied before status. This keeps the location relation consistent when a new assignment is being created.
• Admin View shows the real location status before editing. The assignment modal loads the selected user’s data in the context of the chosen location so inactive or non-default relations are still shown correctly.
• Global admins can complete location status updates from Admin View when allowed by global permissions. The system can bypass personal membership in the target location for this action when the required access is granted through a global role.
• SUPERADMIN accounts are protected in sensitive actions. The UI blocks password change and impersonation for SUPERADMIN targets.
• Concurrent impersonation is blocked. If the admin is already impersonating someone, starting a new impersonation is disabled.

4. UI Placement

1. Admin View > Sidebar > Users (/doctors/users) — opens the Admin View users list.
2. Users List filters (top area) — Role, Status, Location, and Search.
3. Users table — Full Name, Email, Phone, Role, Status, and Actions.
4. Actions column — password change, impersonation, and assign-to-location role/status actions (permission-based).
5. Pagination footer — page navigation and entry counts.

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

Scenario A: Find and review user accounts across locations

1. Switch to Admin View.
2. Open Users from the sidebar.
3. Use Role, Status, and Location filters to narrow the list.
4. Use Search to find users by name, surname, or email.
5. Click a user name to open their profile and review details.

Scenario B: Update access configuration for an employee

1. In Admin View > Users, locate the target employee.
2. To change global role, use the edit action in the Role column and confirm the warning.
3. To change a location assignment, use the location action in the Actions column.
4. Pick the target location.
5. Review the current role and current location-specific status shown in the modal.
6. Update the role, the status, or both, then confirm.
7. If the user is not yet assigned to that location, select both a role and a status so the new relation can be created in one step.
8. To change the user’s global account status, update the Status selector in the row.
9. If needed, use the password action to set a new password (not available for SUPERADMIN users).

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

• Q: Why can I open Admin View but still not see users from all locations?

  • A: Cross-location listing requires Admin View listing authorization (access_admin_view). Without it, listing remains scoped to accessible locations.

• Q: What if the user does not belong to the location I selected?

  • A: The Admin View assignment flow can create the location relation in one confirmation, but it requires both a location role and a location-specific status.

• Q: Can I update only the role or only the status for a location, and what if one part fails?

  • A: Yes. If the user already has a relation with that location, the modal allows changing only the field that needs to be updated, as long as you have permission for that field. If one part succeeds and the other fails, the system reports the result clearly so the admin knows what was saved and what still needs follow-up.