Admin Creating and Managing Users - hmislk/hmis GitHub Wiki
Creating and Managing Users
Overview
User accounts control who can log in to the HMIS and what they can do. Each user is linked to a staff member, assigned to an institution and department, and given a login page, a role, and specific privileges. This page covers creating new users, editing existing ones, and the full set of management actions available from the user list.
When to Use
- Onboarding a new staff member who needs system access
- Changing a user's institution, department, or login page
- Deactivating a user who has left the organisation
- Reviewing or correcting user details
Navigating to User Management
- Click Administration in the main menu
- Click Manage Users
- The View Users screen opens, showing a table of all users
Required privilege: AdminManagingUsers
The User List
The user table shows the following columns:
| Column | Description |
|---|---|
| User Name | The login username |
| Name | The user's full name (shown if enabled in configuration) |
| Code | An optional short code for the user |
| Staff Name | The staff member linked to this account |
| Institution | The institution the user belongs to |
| Department | The user's primary department |
You can filter any column by typing in the filter box below the column heading. Click a row to select it — the action buttons on the right become active.
Creating a New User
- Navigate to Administration → Manage Users
- The View Users screen does not have a direct "Add New" button on the list; instead, the system navigates to the Add New User page via the menu or from within the index
- On the Add New User page, fill in the Basic tab:
| Field | Description |
|---|---|
| Title | Honorific (e.g. Dr, Mr, Ms) |
| Name | Full name of the person |
| Address | Contact address |
| Mobile | Mobile phone number |
| Speciality | Medical speciality (type to search) |
| Institution | The institution this user belongs to |
| Site | Physical site within the institution (optional) |
| Department | Department within the institution/site |
| Login Page | The page the user lands on after logging in |
| User Role | The role that defines the user's base privileges |
| User Name | The login name (must be unique) |
| Password | Set an initial password |
| Re-enter Password | Must match the password above |
- Open the Advance tab for optional settings:
| Field | Description |
|---|---|
| User is Active | Tick to allow login; untick to disable without deleting |
| Add Only User | Creates a login account without creating a new staff record |
| Add User To Existing Staff | Links this login to a staff member who already exists in the system |
| Staff | Appears when "Add User To Existing Staff" is ticked — search and select the existing staff member |
| Code | Optional short code for the user |
- Click Save User (top right of the panel) to create the account
Tip: If the person already exists as a staff member (doctor, nurse, etc.), use Add User To Existing Staff rather than creating duplicate person records.
Managing an Existing User
- On the View Users list, click a user row to select it
- Click Manage User in the action panel on the right
The Manage User form opens with the following editable fields:
| Field | Description |
|---|---|
| User Name | Display only — the login name cannot be changed here |
| Staff | Link or change the staff member associated with this account |
| Institution | Change the user's primary institution |
| Site | Change the physical site |
| Department | Change the primary department |
| Login Page | Change the landing page after login |
| Contact email address | |
| Mobile | Contact mobile number |
| Code | Short code |
| User is Active | Tick/untick to activate or deactivate the account |
- Click Save to apply changes
Action Buttons on the User List
When a user row is selected, the following actions are available in the right panel:
| Button | What It Does |
|---|---|
| Remove | Permanently removes the user account (confirmation required) |
| Manage User | Opens the edit form for user details |
| Manage Password | Opens the password reset form for the selected user |
| Manage Staff | Opens the staff record linked to this user |
| Manage User Departments | Assigns the user to multiple departments |
| Manage User Routes | Configures delivery routes for this user |
| Manage User Role | Assigns or changes the user's role |
| Manage Privileges | Sets individual privileges for this user in a specific department |
| Manage User Payment Schemes | Controls which payment methods this user can accept |
| Manage User Icons | Assigns custom icons to the user's menu |
| Manage User Icons (Bulk) | Assigns icons in bulk using a tree view |
| Manage User Subscriptions | Configures alert/notification subscriptions for this user |
| Manage Signature | Uploads or manages the user's electronic signature |
| Manage Dashboards | Configures which dashboards appear for this user |
| View Drawers | Views and manages cashier drawer access for this user |
| Manage Preferences | Opens user-specific preference settings |
Deactivating a User
To temporarily prevent a user from logging in without deleting their account:
- Select the user in the list
- Click Manage User
- Untick User is Active
- Click Save
The user will no longer be able to log in. All their historical records remain intact.
Best Practices
- Always link users to their correct staff record — this ensures their name appears on bills, reports, and prescriptions
- Set the Login Page to the module the user works in most (e.g. OPD cashier, pharmacy, channelling) to save navigation time every day
- Use User Roles for common privilege sets; use individual Manage Privileges only for exceptions
- Deactivate rather than delete users who have left — deletion removes audit trail linkage
Troubleshooting
User cannot log in
Symptoms: User enters correct credentials but access is denied
Cause: Account may be deactivated
Solution: Open the user record via Manage User and check that User is Active is ticked
User sees "Not Authorised" on a page
Symptoms: User navigates to a page but sees an access-denied message
Cause: The required privilege is not assigned
Solution: Use Manage Privileges or update the user's role — see Assigning Privileges to a Role
Department dropdown is empty when creating a user
Symptoms: No departments appear in the dropdown
Cause: No departments exist for the selected institution/site
Solution: First create departments under Manage Institutions — see Creating and Managing Departments
Technical Notes (Admin/Developer)
The user list queries the WebUser entity. Each WebUser has a one-to-one link to a Staff person record. The activated flag controls login. The Login Page field maps to the LoginPage enum, which determines the JSF navigation outcome after successful authentication. Privileges are stored as UserPrivilege records linked to WebUser + Department combinations; role-based privileges come from WebUserRole linked privileges which apply system-wide regardless of department.