# Entity User Management Workflow

This document describes how administrators manage users (evaluators, managers, entity admins) in the CWI application via the **Users** page and related backend scripts.

## Access

- **Page**: `html/?s=user&p=users&insID={instanceID}&atID={adminTypeID}`  
- **Single entity**: add `&eid={entityID}`
- **Who can access**: Users with an active administrator assignment on the instance (Super/System/Entity/Unit admin, Manager, Evaluator) or legacy system admin. Enforced by `AdminAuth::canAccessUsersPage()`.
- **Entity scope**: Entity admins only see and manage entities they are assigned to. Super/System admins see all entities in the instance.

## Admin types

| ID | Role |
|----|------|
| 1 | Super Admin |
| 2 | System Admin |
| 3 | Entity Admin |
| 4 | Unit Admin |
| 5 | Manager |
| 6 | Evaluator |

Entity admins cannot assign or edit types **1** or **2** (enforced in UI and on the server).

## Add a new user

1. Open **Users** from the instance home card (“Manage Evaluators”).
2. Click **Add User** on the target entity card.
3. Select **Admin Type**.
4. Either:
   - **New person**: Enter first name, surname, email; optionally check **Create Regular User Profile**.
   - **Existing person**: Enable **Select from database** and pick a user from the list.
5. Submit → `php/scripts/admin/manage_instance_admin.php`:
   - Creates or links a `people` record.
   - Inserts `sbsl_administrators` with `instanceID`, `entityID`, and `adminTypeID`.
   - For new users: creates registration tokens and sends a welcome email (skipped on **localhost**).
   - Rejects duplicate assignments for the same user + entity + admin type.

## Manage an existing user

1. In the users table, use **Edit** (pencil).
2. Update **Main Evaluator**, **Admin Type**, or **Suspend User**.
3. Submit → `php/scripts/admin/manage_instance_admin_change.php` (CSRF-protected, entity-scoped).

## Reset password

1. Click the envelope icon on a user row.
2. Confirm in the **Reset Email** modal.
3. Submit → `php/scripts/admin/reset_email.php`:
   - Sets `NeedsToChangePassword` and invalidates login until reset.
   - Sends reset link email (skipped on **localhost**).

## Related files

| File | Purpose |
|------|---------|
| `html/pages/user/users.php` | Main UI |
| `html/includes/scripts/views/user/entity_users_table.php` | Shared users table |
| `html/includes/scripts/modals/manage_instance_admin.php` | Add-user form fields |
| `php/scripts/admin/manage_instance_admin.php` | Add user handler |
| `php/scripts/admin/manage_instance_admin_change.php` | Update assignment handler |
| `php/scripts/admin/reset_email.php` | Password reset handler |
| `php/classes/adminauth.php` | Authorization helpers |
| `php/classes/mailsender.php` | SMTP with localhost guard |
| `php/classes/adminaudit.php` | Optional audit logging |

## Optional audit log

Run `docs/sql/admin_audit_log.sql` on the database to enable change logging via `AdminAudit::log()`.