Staff journey
Who this is for: whoever onboards employees, gives them access, and runs the rota.
Source: guides/workforce.md, guides/access-control.md, guides/identity-access.md. This page
is the order those things happen in and what goes wrong between them; each guide is the detail.
The shape of it
register → give a login → roles & scopes → credentials → rota → leave
⚠ These are separate acts, and the two most common onboarding problems are assuming otherwise:
- Registering a staff member does not give them a login. The account is created separately.
- Having a login does not give them access to anything. Roles do that.
So a new colleague who "cannot get in" is usually missing an account, and one who gets in but sees an empty product is usually missing roles.
1. Register the staff member
⚠ Never a direct person write. Staff are created through staff registration, which creates the underlying person record as part of registering them — the same rule as patients and providers. A person record reachable on its own would be a way to read or change someone's identity without the checks each registration applies.
Registration asks for more than a name, because several of these fields are what later screens filter on:
| What it asks for | Why it matters later |
|---|---|
| Department, then unit | Units are offered based on the department, and the rota is organised by unit |
| Job role and job level | Together they determine the available grade — the level is not decorative |
| Address (country, division, street) | Country and division come from the geography tree, not free text |
⚠ If the person already exists, link them — do not register them twice
The registration form has an "Existing person UHP ID" field. Use it when the person is already known to the platform — most often a member of staff who is also a patient at the same facility.
Registering them fresh instead creates a second person record for one human, which is the kind of duplicate that is easy to make and unpleasant to unpick later: their clinical history and their employment record end up attached to different identities.
→ Guide: Staff and workforce
2. Give them a login
The Account action on the staff detail page creates and manages the login. This is deliberately a second step: employing someone and granting them access to a clinical system are different decisions, often made by different people, and sometimes at different times.
→ Guide: Identity and visibility
3. Roles and scopes
An account by itself can reach almost nothing. Roles carry permissions, and scope limits which records those permissions apply to.
⚠ A permission must be declared by a module before it can be granted. If a permission you expect is not offered anywhere in the list, it has not been declared — looking harder will not find it.
⚠ A menu item needs two things: the user's permission, and the screen's route being registered. Missing for one person is a permission question; missing for everyone is a registration question.
→ Guide: Access control
4. Credentials
Credentials record what someone is qualified to do — with an issuer and an expiry.
⚠ These are not decorative, because the rota can enforce them. See the credential gate below.
5. Rota
The rota is built in a fixed order, and each step needs the previous one:
shift pattern → generate roster → assign or claim shifts → attendance
Unit roster policy decides how open shifts get filled:
- Lead only — only leaders assign staff
- Self-pick / hybrid — eligible staff may claim open shifts
- Require valid credential — staff cannot be assigned to, or claim, a shift without at least one active, non-expired credential
⚠ The credential gate does not act retrospectively
Turning the gate on stops new assignments and claims by anyone without a valid credential. It does not remove someone from a shift they already hold if their credential expires mid-shift — releasing them is a separate, deliberate action.
That distinction matters both ways round. Pulling someone off a shift automatically would leave a unit unexpectedly short with nobody told; leaving them on it means somebody has to notice. Enabling the gate is not the same as auditing who is currently rostered, and if your reason for enabling it is a compliance concern, the second step is the one that answers it.
→ Guide: Workforce
6. Leave and approvals
Leave requests are routed for approval through the workflow engine.
:::caution Deliberately brief M34 replaces this flow with envelope-based routing. Documenting it in depth now would be work that M34 rewrites, so this stays a paragraph and a link until then; M34's own tickets expand it when it ships. :::
Also used for: the workflow engine behind leave approval is the same one that runs patient check-in, shift swaps and critical-result review. If you have configured a patient journey, you already know how this works — only the subject differs.
What stops this working
| What you see | What it actually is | What to do |
|---|---|---|
| A new colleague cannot sign in at all | They were registered, but no account was created | Use Account on their staff detail page |
| They sign in but the product looks empty | They have an account but no roles | Assign roles; check scope too |
| They have the role but still cannot see a screen | The module is not enabled for the tenant | No permission will reveal a disabled module |
| A permission you want is not in the list | No module has declared it | It must be declared in code first |
| One person is missing a menu item everyone else has | A permission question | Check their roles |
| Everyone is missing a menu item | The screen's route is not registered | A build-level fix — raise it |
| Two records exist for the same human | They were registered fresh instead of linked | Use Existing person UHP ID next time; existing duplicates need merging |
| A grade cannot be chosen | Grades depend on job role and job level — one is missing | Set both |
| No units are offered | Units are filtered by the chosen department | Choose the department first |
| Staff cannot be assigned to a shift | The unit requires a valid credential and theirs is missing or expired | Renew the credential, or change the unit policy |
| Someone with an expired credential is still on a shift | The gate does not act retrospectively | Release them explicitly if that is what you intend |
| A record was created but cannot be found | It was created under a different facility | Scope comes from your session — check the selector |
Where to go next
- Setting up tenants, facilities and modules → Platform administrator journey
- Clinical staff, credentialling and privileges → Provider journey
- Patients from arrival to discharge → Patient journey