Workforce

What it does

Workforce helps facilities manage staff, credentials, job roles, engagements, and shift rosters — including assigning or claiming open shifts, recording attendance, and reviewing staffing coverage.

Where to find it

Workforce screens live under the Workforce area of the app (Staff directory, staff registration, My staff portal, rosters, and related admin setup). Facility units and leadership used by rosters are managed under Facilities (departments → units → leaders; departments → leads).

📸 Screenshot: staff directory (workforce-staff).

📸 Screenshot: my staff portal (workforce-portal).

📸 Screenshot: rosters (workforce-rosters).

Open your staff portal (non-clinical)

1. After choosing a facility, non–super-admin users are sent through Workforce → portal, which reads your user_type:
   • Care provider (provider flag) → Providers clinician workspace (M16).
   • Everyone else → My staff portal (/workforce/staff-portal).
2. On the portal home you see only your profile, engagements, upcoming/history shifts, open-rota offers, leave, attendance, credentials (with expiry warnings), and identifiers.
3. You can also open Workforce → My staff portal from the nav at any time.

Routable form approvals (envelopes)

1. From the staff portal home, choose Form approvals (or open /workforce/staff-portal/forms).
2. Switch among Draft, Inbox, In progress, Rejected, Approved, Completed, and Archived tabs — each badge shows how many submissions are in that envelope for you.
3. Open a row with View to see routing status, links to the submission record, an Open approval task shortcut when the item is in your inbox, and the merged routing history timeline (approval actions and workflow events).

Form approval notifications

1. The shell Notifications bell shows unread counts for workflow events, including form-approval notices from backend M34-009 (form_approval_pending, form_approval_rejected, form_approval_completed).
2. Click a pending-approval notice to open Form approvals on the Inbox tab; rejection and completion notices open the Rejected or Completed envelope respectively.
3. On the staff portal home, the Pending form approvals card shows your inbox count and an Open inbox shortcut — use it to jump straight to items awaiting your decision.

Note: Live UAT for envelope tabs requires backend M34-008 on the running API. Notification deep links require M34-009 templates on the same API.

Common tasks

Browse the staff directory

1. Open Workforce → Staff directory.
2. Search by display name or staff profile id.
3. Open a row to see status, hire date, provider link, and engagements.
4. Use Account on the detail page for password/admin account actions.

Register or view staff

1. Open Workforce → Register staff (or Register staff from the directory).
2. Create a new person or link an existing one by UHP ID; set user type and hire date.
3. Fill Home engagement: department → unit, job role, salary grade → band, and amount. This creates the first engagement and sets the staff member’s home department/unit for form visibility.
4. Open the staff row → Credentials to add/update/void licenses or certifications (type, optional issuer from Admin → Setup → Credential issuers, number, issuer, issue/expiry, status). Near-expiry or expired rows show an Expiry warning. Optionally link a role (UUID) so lapse only flags that role — it never auto-revokes access.

Assign unit leaders or department leads

1. Open Admin → Facilities → a facility → Departments.
2. For a department: Leads to assign/end a department lead by person id.
3. Open Units on that department, then Leaders on a unit to assign/end a unit leader.
4. Leadership is keyed by the same person UUID as the staff profile (ID-001).

Care providers. Whether a staff member is a care provider is determined by their user type, not a separate checkbox. Mark a user type as a care provider on Setup → User types (the Care provider option); selecting that type during staff registration reveals the provider fields (provider type, provider code, provider identifiers).

Manage job roles, salary grades, and bands

Under Workforce (or Setup → Reference data):

• Job roles — create / void / unvoid.
• Salary grades — create / void / unvoid.
• Salary bands — create under a grade / void / unvoid.

Registration and engagements pick these by id (not free text).

Configure identity document types (KYC)

Identity document types (passport, national ID, …) are administered as reference data — not free text when verifying staff identity:

1. Open Admin → Setup → Credential issuers first if the type needs a named authority (e.g. a national ID board). Global types such as passport may omit an issuer.
2. Create or edit an identity document type for your country scope; optionally pick the issuing authority from the credential-issuer list (KYC-002). The type code is what downstream identity verification uses — not a locally typed label.
3. Staff identity verification records store verdict, issuer, and timestamp only — never a copy of the ID image in Workforce.

Note: Until the identity-document-type admin screen ships in Setup, administrators configure types via the workforce API (/api/v1/workforce/identity-document-types).

Create a shift pattern

1. Open Workforce → Shift patterns.
2. Choose department → unit, days, times, and a required job role with headcount.
3. Optionally pick a skill from the skill lookup (not a free-text code). Patterns without a skill still require only the job role.
4. Create pattern, then generate rosters from it.

Set unit roster policy (including credential gate)

Unit leaders or administrators configure roster policy on Admin → Facilities → Departments → Units → Leaders for each unit:

• Assignment mode — lead only, self-pick, or hybrid.
• Claim rule — instant, lead approval, or bid window (bid-window minutes appear only when that rule is selected).
• Require valid credential — when enabled, staff cannot be assigned to or claim a shift unless they have at least one active, non-expired credential. Turning this on does not remove someone from a shift if a credential expires mid-shift; release is a separate action.
• Fairness quotas — optional caps on weekend/night self-pick claims over a rolling period.
• Labour rule pack — optional UK/US/CA/NG (or tenant custom) pack enforcing rest and hours limits on assign/claim. Leave unset for no country rules.

Manage staff float eligibility

On Workforce → Staff directory → a staff row, the Float eligibility panel lists units the person may cover beyond their home engagement (not a second engagement):

1. Pick department → unit, optional restricted job role, start/end dates, and Add float eligibility.
2. Void removes the row — the staff member can no longer claim open shifts on that unit via float.
3. On Admin → Facilities → … → Units → Leaders, Staff who may float in shows the read-only reverse list for the unit.

Define a shift pattern and generate a roster

1. Open Workforce → Shift patterns.
2. Choose department → unit, days of week, start/end times, shift type, and at least one required job role + headcount; save the pattern.
3. Open Workforce → Rosters, create a roster naming a pattern and period, then Open.
4. Click Generate shifts — the period fills with shifts showing required-role headcounts (overnight end times are shown when the shift crosses midnight).

Work a shift (assign / claim / attendance)

1. Generate a roster from a shift pattern for the period (above).
2. Open a shift (Assign / attendance) from the roster detail page.
3. Review Coverage (required vs assigned headcounts).
4. Assign staff (lead) with staff profile id + job role, or Claim (open rota) when the unit policy allows self-pick / hybrid (LEAD_ONLY rejects claims).
5. Release an assignment if needed; coverage updates after each change.
6. Clock in / out for attendance once the staff member is ASSIGNED on that shift.

Request leave

1. Open Workforce → Leave.
2. Create a leave type if none exist (e.g. Annual Leave).
3. Submit a leave request for a staff profile id (type + period); approve, reject, or cancel pending requests from the staff list.

Request a shift swap

1. Open Workforce → Shift swaps (or copy an assignment id from a shift detail page).
2. Request a swap: from assignment id → to staff profile id.
3. Load the swap request id to approve, reject, or cancel.

Review staffing metrics

1. Open Workforce → Staffing metrics (facility must be selected).
2. Choose a date period; optionally narrow by department → unit; Load metrics.
3. Summary cards show shift count, fully covered share, average coverage, and total shortfall.
4. Shift coverage lines list per-shift/role assigned vs required; Staffing ratios show active engagements vs required headcount for in-progress STANDARD shifts.
5. Per-shift coverage is also on each shift detail page. These feeds also support executive KPI scorecards (M11-007).

Run payroll (calculate → approve → payslips)

1. Open Workforce → Payroll runs.
2. Select an open pay period and a payroll template (country on the template drives statutory rules — Nigeria defaults to seeded PAYE, pension, and NHF when configured).
3. Enter an optional run label and Create run — the run starts in DRAFT.
4. Select the run, then Calculate — payslips are generated from template lines plus country statutory deductions (PAYE bands, pension %, NHF %).
5. Review payslip cards: gross, net, and expandable line detail (earnings and deductions including STAT_PAYE, STAT_PENSION, STAT_NHF when applicable).
6. Approve when totals look correct — status moves to APPROVED (ERP can post via workforce payroll posting summary; POSTED is set when finance marks the run posted).

Statutory rules are administered via API (/api/v1/workforce/payroll-statutory-rules) until a Setup screen ships. Global Nigeria seed bands apply when no tenant override exists.

Tips & limitations

• Credentials that expire may trigger alerts and role-lapse flags; they do not automatically pull staff off a shift already in progress.
• Staffing “patient:nurse” census ratios need inpatient census data and are not available yet.
• Backend support exists for bank / agency eligibility on assign/claim. Dedicated admin screens for those policy knobs may still be incomplete — configure what the UI exposes, and treat API-only fields as administrator/advanced until their screens ship.
• Payroll statutory rules have no dedicated admin UI yet — use the workforce API for country schedules; calculate still applies global seed rules for Nigeria (NGA) when present.
• Super_admin landing after facility select may differ from ordinary staff (portal router targets non–super-admin staff).

---

When something looks wrong

What you see	What it usually is
A new colleague cannot sign in	They were registered, but no account was created
A grade cannot be chosen	Grades depend on job role and job level — set both
Staff cannot be assigned to a shift	The unit requires a valid, non-expired credential
Someone with an expired credential is still rostered	The credential gate does not act retrospectively — releasing them is a separate action
Two records for one person	Use the existing person id when they are already known

For the causes common to every screen — a missing menu item, an empty list, a refusal — see Why a screen will not work.