Add, import and manage users

Every member of staff who signs in to the suite has a user account. This page shows how to create accounts one at a time or in bulk from the nominal roll, and how to look after them afterwards.

You work on People › Users. What you can do depends on your permissions: view_users to see the list, add_users, edit_users, deactivate_users, reactivate_users, reset_user_password, reset_user_onboarding, edit_locked_user_fields and export_users for the rest. See Users permissions.

Find a user

The users list, searched for “Test” to show only the test accounts.

Search. Type part of a name, an email address or a staff number.
Filters. Narrow the list by unit (Department / Unit), status (Active or Inactive) and role. Reset clears them.
Export. Download the people matching your search and filters as Excel or CSV. Choose the columns; salary columns need view_payroll.
Add User. Opens the form for a new account.
Counts. How many people match, how many are active, how many units and how many roles are in use.
A user. Select a row to open that person's details.

What the status means

Pending activation: The account exists but the person has not signed in yet. At first sign-in they must set their own password.
Onboarding required: The person must confirm their photo, contact numbers and signature at their next sign-in before they can use the suite.
Active: Signed in and set up.
Inactive: Deactivated: cannot sign in. Records and history are kept.

Add one user

The Create New User form. Nothing is saved until you select Create User.

Personal Information. First, last and full name, email, phone, date of birth and gender. All are required.
Temporary Password. At least 8 characters. The person must change it at first sign-in.
User Groups. The departments or units the person belongs to. You can pick more than one; access checks use all of them.
Copy from role. Pick a role template to fill in the permissions on the right. You can still change them.
Permissions. The access matrix: tick single permissions, or use All / None for a whole area.
Create User. Saves the account.

Open Add User.
Fill in the personal details. The email is what the person signs in with (they can also sign in with their staff number once it is set).
Set a temporary password you can pass to the person privately.
Fill in the employment details: user groups, Position, Employee ID (the staff number, optional), Hire Date and Annual Salary (₦). Salary is required and must be more than zero.
Choose permissions. For most staff, pick Employee in Copy from role (optional). For office holders, see Office holders.
Select Create User. The person appears in the list as Pending activation.

A new account is created with the role User (employee). If the person is a head, an accountant or an administrator, change Role afterwards on the Employment tab of Edit User. The role decides who they are as an approver; their permissions decide what they can open.

Bulk import from the nominal roll

To create many accounts at once, the ICT team runs the import script against HR's Staff Nominal Roll by States spreadsheet. There is no upload screen: it runs on the server.

Get the spreadsheet from HR. The script finds the header row by its S/N and NAME cells, so the column order does not matter.
Preview. npm run users:import -- --file "NOMINAL ROLL BY STATES.xlsx" --dry-run reads the sheet, works out every email address and writes a report, without creating anyone.
Read the report in imports/. Look at the warnings column: odd phone numbers, unknown sex codes, unreadable dates, duplicate file or IPPIS numbers, and email addresses that needed a number added.
Import. Run the same command without --dry-run. Each row becomes an account in Pending activation with a temporary password written to the report. No emails are sent.
Hand out the credentials privately, then delete the report: it contains passwords.
Finish each record in the app: put people in their units, and give heads and office holders their role and permissions.

What the import fills in

Spreadsheet column	User field
NAME	Last name (first word), first names, full name, and the email address: the first names and surname, lower case, joined by dots, at the hospital's domain (for example `amajuoyi.i.frank@uath.gov.ng`). Titles such as Dr. and Prof. are dropped.
SEX	Gender (M / F)
RANK	Position
FILE NO.	Employee ID (staff number)
SAL. SCALE	Salary scale (salary itself is set to 0)
DATE OF 1ST APPT / DATE OF PRE. APPT.	Hire date / date of present appointment
QUALIFICATIONS, DATE OF BIRTH, STATE, LGA, PHONE NO., IPPIS NO	The matching fields

Useful options: --domain (email domain; default from the USER_EMAIL_DOMAIN setting), --role (default employee; permissions are copied from the role template with that code), --limit (first n rows only), --report (reuse one report file across runs), --reissue-passwords (new temporary passwords for pending accounts whose password was lost). Re-running is safe: people already imported are skipped. Each run writes one USER_BULK_IMPORT entry to the audit log.

Edit a user

Open the person from the list, then select Edit User. The edit page has three tabs, each saved with its own button.

Details: Names, email, phone, date of birth, gender, state of origin and LGA. Save Details.
Employment: User groups, Role, position, employee ID, hire date, salary, salary scale, date of present appointment, IPPIS number and qualifications. Save Employment.
Permissions: The same access matrix as on the new-user form. Save Permissions. Reset puts back what is saved.

The Employment tab for a head of unit (a test account).

User Groups. Add or remove the person's units. This is how you move someone between units.
Role. User, Head (HOD / HOU), HR Manager, Accountant, Administrator, Managing Director or Super Admin. Approval steps of the kind “anyone with a role” use this.
Save Employment.
Leadership Assignments. The units this person heads. You change a head on the unit, not here: see Set or change a head.
Account password. Set a new password for the person (see below).

Locked fields

At the end of onboarding each person confirms their phone number and date of birth, and the record is locked (the user's details show Record: Locked and the date). After that:

The person cannot change these two fields from their own profile; they are told to contact HR.
On the edit page the fields are greyed out unless you hold edit_locked_user_fields (“Edit locked record fields”). With it you can correct them; every change is audited.

Reset a password

Open the person and select the Admin Actions tab (or use Account password on the edit page, where the button is Set new password).
Type a new password of at least 8 characters.
Select Reset Password. The person gets an email saying their password was changed. The email does not contain the password, so tell them yourself.

People can also reset their own password from the sign-in page. See Find your account & reset password.

A user's details with the Admin Actions tab open.

Edit User. Opens the three-tab edit page.
Reset Password.
Account Status. Deactivate User or Reactivate User.
Onboarding. Reset onboarding.
Quick Stats. Status, years of service, salary, whether onboarding is done and whether the record is locked. A warning appears here if account lookup is locked after repeated failed attempts.

Reset onboarding

Use this when a person's photo, contact numbers or signature need to be captured again, for example after a wrong signature was uploaded.

Open the person › Admin Actions.
Select Reset onboarding, then confirm.

At their next sign-in they must confirm their photo, contact numbers and signature again. Their locked phone number and date of birth are not changed. The button is disabled while the account is still pending activation or already waiting for onboarding.

Deactivate or reactivate

Open the person and select Deactivate at the top (or Deactivate User on Admin Actions).
Confirm. They can no longer sign in. Their records, requests and history are kept.

To bring them back, open them (set the list's status filter to Inactive to find them) and select Reactivate. They sign in again with their existing password.

Before deactivating a head of unit, give the unit a new head first. Pending approvals move to the new head automatically only when you change the head; a deactivated person cannot act on anything still assigned to them.

The other tabs on a user

Personal Info / Employment: Read-only views of the record, including nominal-roll fields (state of origin, salary scale, IPPIS number, qualifications).
Permissions: What the person can do, grouped by area.
Logs: The last 50 audit entries about this person. Select one to see the before and after values.