How the onboarding portal works

1The shape of it

Three layers, each doing what it's best at:

• This portal — the candidate's guided screen, your admin board, sessions, the stage machine, and the reminder engine.
• SharePoint (the StaffOnboarding site) — the engine room: a Candidates list, the Tasks list, an Events audit trail, and the document library where uploaded files are copied with their verdicts.
• R2 file storage — the durable home of every uploaded file and signing certificate, so a candidate's upload never fails because SharePoint is having a moment.

2What we call people

Three words, and the portal picks between them from the record rather than leaving it to whoever writes the next screen:

• Applicant — they've applied and nobody has read it yet. They sit in the Applications inbox.
• Candidate — someone has read it and they're in the hiring pipeline.
• Staff member — they've been hired. This happens the moment they reach Provisioning, and the date is stamped once and kept. They appear on Staff and stay there until they leave.

Being hired is treated as an event, not a position in the list. Move a new starter back to Contract to reissue a document and they're still staff, with their original start date — which is what you'd expect, and what a "are they past stage 8?" test would get wrong. You'll see a green Staff chip against their name once it's happened.

3The pipeline

Shortlisting → Interview → Reference checks → Letter of offer → Verification → Sign-off → Contract → Provisioning & orientation → Profile & launch. A candidate can also be marked Not progressing or Withdrawn at any point — that closes their record and revokes their portal sign-in.

References come before the offer, not after. An offer is never made to a candidate whose references are outstanding. Sign-off is its own stage because it is a different person's job: Admin gathers the evidence, an owner confirms it is complete and valid before the contract issues.

The candidate does not see all of this. Until there is an offer on the table they see four steps — application received, interview, references, offer. The rest appears once they have been offered the role, so nobody is shown a contract stage for a job they may not get.

The candidate sees a friendlier eight-step version (Shortlist is invisible to them; the two setup stages read as "Getting you set up").

4Working a candidate

1. They arrive one of two ways — through the public application form (see §5), or created by hand on the Candidates screen when someone comes to you directly. Name and email is enough.
2. Copy link mints their private sign-in link (emailed automatically when email is configured; always shown for copy-paste). It signs them in on their device and keeps them signed in.
3. Manage opens their action items: uploads (with redo rounds — earlier rounds are kept, never overwritten), sign & return PDFs, acknowledgements (tick + typed name → certificate PDF with the file's SHA-256), approvals, confirms and info notes. Items start hidden so you can stage a batch, then reveal.
4. Move the stage from the dropdown as things progress. View as shows their portal exactly as they see it.

5Applications

People apply themselves. Two public pages: /apply when a role is advertised, and /apply/interest for anyone who wants to register interest with nothing open. Both take a name, email, what they're after, a short note and up to two files — a CV and a cover letter. Their documents land in SharePoint straight away, tagged as a CV, under a folder in their own name.

They don't go on the board. Applications wait in Applications until someone reads them. That's deliberate: the board answers who is stuck, and forty unread applicants would bury the two people who need you today. Shortlist puts them on the board. It doesn't move their stage — Shortlisting is stage 1, and "we've read this" isn't "they've been interviewed".

Telling people no. Tick as many as you like and choose Not progressing. You see the actual email, for a real person, before anything is sent — and nothing is written until you press send. There's also a tickbox to close records without emailing, for the ones you've already spoken to. Closing revokes their sign-in and keeps the stage they reached, so you can still answer "where do we lose people".

The wording is yours. Three templates — after application, after interview, after references — because a no after someone has arranged referees should not read like a no after a CV. Edit them rather than living with ours.

What the form tells applicants about their own data. It says their details are stored securely and used only to consider them for a role, then links out to your privacy and data retention policy for how long you keep things and how to ask for a copy or deletion. The link comes from the PRIVACY_URL setting. Until that's filled in the form shows a dashed [link to your privacy and data retention policy] marker instead — deliberately obvious, because a form that quietly says nothing about retention is worse than one that admits the gap.

6Staff

Hiring ends; employment doesn't. The board is a queue people leave — by being hired, or by not being. Staff is the opposite: everyone who has been hired, since when, and what they owe. Nobody leaves it until they leave you.

They arrive automatically. Moving someone to Provisioning & orientation puts them on the register and writes them to a separate Staff list in SharePoint. That's a different list from Candidates on purpose: applicant records get cleared out after six months and staff records are kept for as long as someone works with you, and two retention rules can't share one list. Their hiring record stays behind, linked, so you can still see how they were recruited.

When someone leaves, use Mark as left and give their last day. They stay on the register as Left, with everything they ever sent intact — what stops is the chasing. Without that, a former employee's expired police check would sit on the screen forever looking like a live problem.

The onboarding run starts itself. Reaching Provisioning doesn't just add them to the register — it creates everything that has to happen next, split by who actually does it. Your half appears as tick-lists on their Manage screen and is never shown to them: setting up their Microsoft account (first name plus the first letter of the surname, so it matches the rest of the tenant), SharePoint access, and for clinical staff the Medicare run and Halaxy. Their half is ordinary items on their own portal: personal details, practice preferences, the NDIS Worker Orientation Module, the policy pack, and their bio and photo. Everything lands hidden, as always — reveal their half when you're ready for them to see it, and work through yours meanwhile.

Order matters in one place and the portal keeps it. PRODA, then the Medicare provider number, then Halaxy — you can't get a provider number without PRODA, and Halaxy can't bill without the number. It's one task with three ticks rather than three tasks, because it's one job somebody does in one sitting.

A clinical hire gets the Medicare, Halaxy and WorkSafe/TAC run; an administrative one doesn't. If a role doesn't match either, the portal says so on the stage move rather than quietly handing over a short list — a clinician who skipped Medicare would be discovered by a rejected claim.

Expiry dates are read back, and acted on. Every time you accept a document that expires (police check, WWCC, AHPRA or AASW registration, professional indemnity) you're asked for its expiry date. The register reads those dates and shows each person's worst item first: Lapsed (expired — cannot practise), Overdue (past the date you asked for it by), Due soon, Clear, or Not tracked when nothing has a date yet. Ahead of an expiry the portal emails the person at 90, 60, 30 and 7 days out, calmly and with the date, and anything lapsed leads your morning digest until it's fixed. Request it asks them for a missing or expiring document through their portal; Record a document I already have is for one that arrived by hand, so it's tracked like the rest. Preview both sweeps from Settings — they send nothing.

7Checklists

Nobody builds a list by hand. When you add someone you pick two things — the engagement type (contractor, casual, employee, volunteer, student placement) and the role (Social Worker, OT, Psychologist…). The portal composes their checklist from three pieces: what everyone owes, what that engagement type owes, and what that role owes. A contractor social worker gets the core police check and photo ID, the contractor's ABN and insurances, and the social worker's AASW registration — ten items, none of them typed out by you.

Why two lists instead of one per situation. How someone is engaged and what they're registered to practise vary independently. Five engagement types across six roles would be thirty separate checklists to keep in step, and thirty places to edit when the police-check wording changes. Kept apart, it's eleven pieces and one edit. Edit them on Checklists, and use Preview a combination there to see exactly what any pairing produces before it reaches a real person.

Everything arrives hidden. A composed checklist is created but not visible to the candidate until you reveal it, so you can adjust, add or delete items first. Applying a checklist a second time appends — it doesn't sync — so two applies means two copies. If a request appears in both the type and the role list, it's asked once, not twice.

Documents and expiry. An upload task can name a document type. That's what makes the file land in SharePoint tagged as, say, an AHPRA registration rather than an anonymous PDF — and for the types that expire (police check, WWCC, AHPRA, AASW, professional indemnity) it's what lets the portal ask for the expiry date at the moment you're already looking at the certificate.

8What's deliberately not here yet

This is the walking skeleton (Phase 0–1 of the build). Coming in later phases, in order: per-role checklist templates that seed a new candidate's items; the interview item type (Teams link + time confirm/reschedule); referee capture; document types & expiry dates recorded at verification; the expiry engine (watches registrations/insurance and warns before they lapse); and the checked delete dialog. The SharePoint lists this page references also need creating once — see LIFT-AND-SHIFT.md in the repo for the column spec.

9One-time setup (SharePoint)

The Graph app can't create columns, so this is a human step, once per tenant: on the StaffOnboarding site create a Candidates list (Title, CandidateId text, Email, Phone, Role choice, Stage choice, StageChangedAt, Source, RegistrationBody, RegistrationNumber, Notes), a Tasks list (same columns as the Engage portal's Tasks, with the lookup named Candidate), an Events list, and add DocType, ExpiryDate, DocStatus, Round and a Candidate lookup to the Documents library. Until they exist the portal degrades gracefully — the candidate list works from D1 alone; tasks show "not connected yet".