Admin Creating and Managing Roles - hmislk/hmis GitHub Wiki

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.

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