# Creating and Managing User Roles ## Overview A User Role is a named set of privileges that can be assigned to many users at once. Creating well-structured roles is the foundation of HMIS access control — it allows you to onboard new staff quickly and consistently, and to update access for an entire job group by changing one role instead of editing each user individually. ## When to Use - Creating a new job category that needs a standard set of permissions - Changing the access level for an entire group of staff - Reviewing what a role currently allows before assigning it to a new user ## Navigating to Role Management 1. Click **Administration** → **Manage Users** 2. The **View Users** screen is the base page; roles are managed from the same index area 3. The role management screen is reached via the administration navigation — look for **Manage Roles** or navigate from within user management > **Required privilege:** AdminManagingUsers ## The Role Management Screen The screen shows two panels side by side: **Left panel — Role list:** - A scrollable, filterable listbox of all existing roles - Type to filter by role name - Click a role to select it and see its details on the right **Right panel — Role details:** | Field | Description | |---|---| | **Role Name** | The name shown in dropdowns and on user accounts | | **Description** | Optional free-text explanation of the role's purpose | | **Active** | Toggle switch — when off, the role cannot be assigned to new users | ## Creating a New Role 1. Click **Add New** (green button above the role list) 2. The right panel clears for entry 3. Enter a **Role Name** (required) 4. Optionally enter a **Description** 5. Ensure the **Active** toggle is on 6. Click **Save** 7. The new role appears in the list ## Editing a Role 1. Click the role in the left list to select it 2. The details appear in the right panel 3. Update the name, description, or active status as needed 4. Click **Save** ## Deleting a Role 1. Select the role in the left list 2. Click **Delete** (red button, requires confirmation) > **Warning:** Deleting a role removes it from all users currently assigned to it. Their access will revert to only their individual privilege assignments. Deactivating (toggling **Active** to off) is safer — it prevents new assignments without breaking existing ones. ## After Creating a Role — Next Steps A new role has no privileges until you assign them. Click **Manage Privileges** in the right action panel (or navigate to the role privilege screen) to define what the role can do. See [Assigning Privileges to a Role](Admin-Assigning-Privileges-to-a-Role). You can also: - Click **Manage User Role Icons** to assign shortcut icons to the role - Click **Manage User Role Subscriptions** to configure alert subscriptions for the role ## Technical Notes (Admin/Developer) Roles are stored as `WebUserRole` entities. Each user can be assigned one role via the `WebUser.webUserRole` field. Role-privilege mappings are stored as `WebUserRolePrivilege` records. The role list is populated by `webUserRoleController.items`; saving calls `webUserRoleController.saveCurrent()`. ## Related Features - [Understanding Roles and Privileges](Admin-Roles-and-Privileges-Overview) - [Assigning Privileges to a Role](Admin-Assigning-Privileges-to-a-Role) - [Assigning Users to a Role](Admin-Assigning-Users-to-a-Role) - [Role Icons](Admin-Role-Icons)