User guide › Apps › Onboarding
What a journey is
Three words carry the whole app, and it's worth being precise about them:
| Thing | Is |
|---|---|
| Template | A reusable list of steps, scoped to who it applies to — a job, a department, a work type, or everyone. |
| Step | One item on that list: a type, who it's assigned to, and how many days from the start date it's due. |
| Journey | Templates made real for one person: dated, assigned, tracked, with a progress bar. |
A step isn't just a checkbox. It sends a contract for signature, hands over a laptop, collects a document, routes an approval or asks a department manager to sign that they trained someone.
This app needs HR records — a journey hangs off an employee record, not a login, because plenty of employees never sign in.
The screens, and who can open them
| Screen | What it's for | Needs |
|---|---|---|
| My onboarding | The new starter's own checklist. | App access |
| My assignments | Steps the signed-in person owes across every journey, plus training they have to sign off. | App access |
| Console | Every journey, what's overdue, what's blocked, what has no owner. | Manage onboarding journeys |
| Journey builder | Authoring templates and their steps, with the effective preview. | Manage onboarding journeys |
The two personal screens deliberately need no HR permission: a new hire and a training manager are exactly the people who don't hold one. The raw record tables — Journeys, Journey steps, Training sign-offs, Journey templates, Template steps — are also in the sidebar for anyone who prefers them, and they follow the ordinary record permissions rather than app access. See Permissions & access for why those are two different systems.
Journeys start themselves
| When | What happens |
|---|---|
| An employee record is created | An onboarding journey, dated from their hire date. |
| An employee's status moves into Notice period or Terminated | An offboarding journey, dated from their termination date. Only on the change — re-saving an already-terminated record raises nothing. |
| An employee is backfilled on HR records' Add existing members screen | Nothing. Those people already work here. |
Notice period counts, not just Terminated, because an offboarding that starts on somebody's last day is a list of things nobody did.
There is no error and no message. If a new starter has no journey, work down When a template doesn't apply — nine times out of ten it's an exact-match scope or a missing job.
What ships with the app
Installing used to leave you in an empty builder. Four templates now come with it. They're yours once seeded: edit one and it stays edited, delete one and it stays deleted.
| Template | Applies to | Steps |
|---|---|---|
| New starter | Everyone (onboarding) | Contract to sign (day −3) · collect ID & bank details (day −1) · equipment handover (day 0) · complete your details (day +1) · week-one manager sign-off (day +5) |
| Leaver | Everyone (offboarding) | Exit interview (day −1, HR) · return equipment (day 0) · final documents (day 0, HR) |
| Existing staff · records catch-up | Everyone, but start by hand only | Upload the signed contract (HR) · confirm equipment held · complete your details |
| External / agency | Work type External | Adjusts the New starter list: removes the contract and the ID & bank collection, swaps the laptop for a site badge, adds an NDA and a safety induction |
New starter has no scope, so the very first employee anybody creates gets a journey — that's the out-of-box value. The catch-up template deliberately has no e-signature step: those contracts were signed years ago, so HR uploads the paper one instead, and filing it that way records "signed elsewhere" rather than "never signed".
External / agency is the worked example of the whole model. It doesn't restate the company checklist, it adjusts it — an external isn't employed by you and the agency pays them, so the contract comes out and a site badge replaces the laptop, while the company induction survives.
You'll get both stacks until you act — your six steps plus the five shipped
ones, because steps without a key always add rather than replace. Two one-off fixes,
both in the builder: switch one template off, or give your steps the same keys the
shipped ones use (contract, id_bank, equipment,
profile, week_one). The effective preview shows exactly which
happened.
Building a journey
Onboarding → Journey builder. Templates down the left, the selected template's steps down the right, everything edited in place and saved as you type.
Scoping a template
A template carries a Kind (Onboarding, Offboarding, Transfer) and three scope axes. Blank on an axis means "any"; a filled axis must match exactly — trimmed and case-insensitive, so "Retail " matches Retail, but Retail Ops does not.
| Axis | Weight | Notes |
|---|---|---|
| Job title | 4 | The role ("Store Manager"), not the individual seat. Two seats of the same job onboard identically. |
| Department | 2 | Matched by name. The department tree is not walked — a template scoped to Retail does not reach teams underneath Retail. |
| Work type | 1 | Full-time, Part-time, Contractor, Intern, Fixed-term, External. |
The weights are the ordering, not decoration: a job alone (4) outranks a department and a work type together (3), because "how we onboard a Store Manager" is a more specific statement than "how we onboard a full-timer into Retail".
Active and Start by hand only are two different switches. Inactive means the template is off. Start by hand only means it is live and startable, it just never matches automatically — which is what keeps a catch-up journey off a genuine new starter. Don't use Active to mean "by hand only": the first admin who "fixes" it silently adds those steps to every hire.
Every matching template stacks
A hire's journey is the merge of every template that applies, walked least-specific first. That's what stops the Store Manager journey having to restate the entire company checklist. Two fields on each step control the merge:
- Key — stack identity. Steps in different templates that share a key are the same step, and the more specific template's version replaces the broader one, in place.
- Removes the inherited step — with a key set, this step drops the inherited one instead of contributing anything. It's how a role template says "not for this role". A removal with no key is ignored, because it names no target; the builder says so at the field.
That's deliberate, and it's also the trap. Write a Store Manager template with an unkeyed "Sign the manager contract" and the hire gets two contracts — yours and the company one. Reuse the broader template's key to replace it instead. When a broader template of the same kind exists, the builder lists the keys on offer next to the field.
The merged list is sorted on each step's position within its own template, not on the day offset — so an add-on can interleave, landing between two steps of the base template rather than only appending to the end. Move a step with the up and down buttons on its card; they swap the underlying order values, which is the thing the merge actually sorts on, so the change survives a reload.
What goes on a step
| Type | What running it does | Configuration |
|---|---|---|
| Task | Nothing — it's a checkbox somebody ticks. | — |
| Document | Raises a row in the employee's document vault. Uploading a file through the step fills that same row and closes the step in one action. | kind=id_card |
| Equipment | Issues the first in-stock asset of that category to the employee. On an offboarding journey it drives the return leg instead. | category=laptop |
| Contract | Composes an e-signature envelope from a template, substitutes the employee's details, sends it, and files a contract in their document vault. | esignTemplate=<template id or title> |
| Training | Creates one training sign-off per department listed, for that department's manager to evaluate and sign. | One department per line |
| Course | Looks for a course-completion log to self-complete against. With none set up, the step says so plainly and is worked by hand. | course=<course id> |
| Approval | Sends the step to the standard Approvals inbox and waits for a verdict. | — |
Assign to resolves to a real person at the moment the journey is created:
| Rule | Resolves to |
|---|---|
| The employee | Their own account. |
| Their manager | Whoever their Reports to points at. |
| Head of their department | The head set on their department. |
| HR | Whoever holds Manage employee records in HR records; workspace admins if nobody does. Terminated people are skipped, so it survives the HR manager leaving. |
| A specific member | The member you name. |
| A role | The first holder of that role. |
When nothing resolves the step stays unassigned and turns up in the console's Unassigned list — better than guessing an owner. Day is the offset from the journey's start date, and it can be negative: −3 is "three days before day one", which is how a contract goes out before the person arrives.
The effective preview
At the bottom of the builder, Effective preview is half the screen's value. Type a hypothetical department, job title and work type and it shows:
- which templates matched, each with its specificity score;
- the merged step list in final order, every step labelled with the template that contributed it;
- a line per contribution reading added, replaced, removed or no effect, naming the template each replacement or removal displaced.
A stacked model without this is guesswork. It is also the fastest way to answer "why does this hire have that step?".
Contract steps and tokens
A Contract step points at an e-signature envelope template — one reusable document, not a record per hire — by id or by title in its configuration. An authored template is re-composed with the employee's details substituted before it goes out; a template built from an uploaded PDF is sent as-is.
| Token | Fills in |
|---|---|
{{employee.name}} | Full name |
{{employee.position}} | Their job title, resolved through the seat they hold |
{{employee.department}} | Department name |
{{employee.work_type}} | Work type, as a label ("Full-time") |
{{employee.start_date}} | Hire date |
{{employee.salary}} | The figure on their latest employment change, unformatted — your own wording carries the currency and the period |
{{employee.tin}} · {{employee.phone}} · {{employee.email}} | Personal ID, phone, work email |
{{today}} | Today's date |
Spaces inside the braces are tolerated, and a token that isn't on this list is left
exactly as written — so a {{company.address}} your own template defines
survives untouched. A token that is on the list always substitutes, so a hire with
no salary typed prints a gap rather than raw braces.
The signed contract lands in the employee's document vault in HR records, and its signature state there reads Awaiting signature, Signed, Declined or Cancelled. Declined means a person read it and refused — the one to act on. A withdrawn or expired envelope reads Cancelled instead, because recording a withdrawal as a refusal puts an untrue fact in somebody's file.
With no e-signature app installed, a Contract step doesn't error — it becomes a checkbox with a line telling you to send the contract your usual way and mark it done. Same for a Course step with no completion log behind it.
Starting a journey by hand
For a transfer, a backfill, or a hire that matched nothing. Two places, one panel: Start a journey on the console, and the same control on the Onboarding tab of an employee's profile — which is where you're standing when you notice a new starter has no journey.
- Pick the person, the kind and the date Leave Template on Stack every matching template to get the normal merge. Naming a template means that template only — someone who chose "Retail leaver" from the picker asked for that list, not for whatever else stacks.
- Preview Resolves the stack, dates every step and writes nothing. You get the matched templates with their scores and the merged list.
- Edit the list if this person is an exception Every row's title, type, assignee rule, day offset and required flag are editable right there, rows can be deleted, and Add step adds one. "This hire is like everyone else except…" stops being a reason to build a one-person template.
- Start What you saw is what gets created, in the order shown. The journey still records which templates it came from, even when somebody edited the list.
A second journey of the same kind is refused while the first is still open — the preview warns you before you press Start. Complete or delete the first one.
Starting one for a group
Start journeys on the console runs one journey for a set of people. It's the answer to "I have 30 people who already work here — how do I collect their paperwork?", and equally to an annual compliance re-training round or re-issuing equipment after an office move.
- Choose the journey Kind, optionally a specific template, optionally a start date.
- Choose the people A search box and tick boxes; Select all takes everyone currently visible. Or arrive from HR records' directory: filter it, tick people, press Start a journey for selected, and this panel opens with that selection already made. Up to 500 people per run.
- Preview Nothing is written. You get N ready · N skipped · N failed, and a row per person who isn't going to start, with the reason.
- Confirm The button counts the people who are actually ready, not the size of your selection, and asks before it writes.
| Outcome | Means |
|---|---|
| Ready / Started | Will start / did start. |
| Skipped — already has an open journey | Never started twice. Finish or delete the first. |
| Skipped — no template matches them | See When a template doesn't apply. |
| Failed — employee record not found | A stale id in the selection. |
| Failed — something went wrong | That one person's data stopped their journey being written. The detail is on the row. |
One person failing does not lose the rest: everyone already written stays written, and the person who failed is rolled back completely, so there's never a half-built journey. Running the same batch again starts nothing new — everyone now has one. The result list stays on screen after the run, because it is the report of who started and who didn't.
What the new joiner sees
Onboarding → My onboarding. Their own journey, a progress bar with done/total, and one card per step showing its type, due date, who owns it, whether it's optional, and any note the step carries. An overdue due date turns amber.
The buttons on a card depend on the step:
| Button | Appears on | Does |
|---|---|---|
| Upload | Document steps | Files the file in the employee's document vault and closes the step. |
| Run | Steps that actually do something | Executes it — sends the contract, issues the equipment, raises the document row, routes the approval. |
| Check signature | A contract that's already out | Pulls the envelope's current state back onto the step and the vault row. |
| Mark done | Everything | Closes it by hand. |
| Skip | Optional steps only | Settles it without doing it. Optional steps never hold a journey open. |
Step states are To do, In progress, Awaiting approval, Blocked, Done and Skipped. Blocked is a step that tried and couldn't — no laptop in stock, an upload that didn't resolve — and the card says which.
Somebody whose account isn't linked to an employee record is told so and pointed at HR; linking is covered in HR records.
What a manager sees
Onboarding → My assignments is everything the signed-in person owes across every journey — not just their own — in three sections: Steps you owe, Training to sign off and Recently done. The step cards are the same ones described above.
Training sign-off
A Training step creates one sign-off row per department the step lists, with the trainer pre-filled from that department's head. The trainer opens Sign off and records:
- Evaluation — 1 to 5, from Needs significant support to Excellent;
- Comments;
- Signature — drawn on screen.
The step only completes when every department has signed, and then the journey rolls up in turn. Signing needs no HR permission — only being the assigned trainer, which the server checks. Someone holding Manage onboarding journeys can also sign, which is the escape hatch for a trainer who has left. A row that's already signed can't be signed twice.
Tracking progress
Onboarding → Console. Four tiles — Active, Leavers, Overdue, Blocked — then every journey as a card with the person's name, its kind, its start date, the templates it was built from, a progress bar and a chip per step showing that step's state.
Underneath are the three lists that actually need chasing: Overdue, Blocked and Unassigned, each row naming the step, the person, the due date and the owner.
A journey's status is rolled up, never typed — Complete, Blocked, Overdue, In progress, Not started, recalculated after every change and again on every read, so an approval settled elsewhere can't leave the journey stale.
The pencil on a journey card opens its steps for editing while it runs: rename a step, move its due date, reassign it, make it optional, add one, remove one.
If it created something real — a contract out for signature, an asset booked out to this person, a document row — deleting the step would orphan it silently: the contract keeps chasing them and the laptop stays on their name with nothing left in the journey to say so. Mark it Skipped instead, which keeps the trail. The console disables the button and gives that reason; the server refuses it either way.
Offboarding
Offboarding is the same machinery with Kind = Offboarding, and it is fully supported rather than implied.
- Set the employment status Move the person to Notice period or Terminated on their HR record. The transition raises the offboarding journey; set the termination date first, because the journey is dated from it.
- The Leaver template runs Exit interview, return equipment, final documents. The two paperwork steps are assigned to HR rather than to a named person, so they don't point at somebody who has themselves left.
- Equipment comes back An Equipment step on an offboarding journey drives the return leg: running it closes the employee's open assignment and puts the asset back in stock, in the condition it came back in.
- Track it exactly like a hire Same console, same chase lists, same roll-up. The Leavers tile counts them separately.
Scope an offboarding template the same way you scope an onboarding one — a Retail leaver template, a Store Manager leaver template — and they stack by the same rules. Someone who was backfilled rather than hired does get an offboarding journey when they leave; the never-onboard rule is about arriving, not leaving.
Transfer is the third kind, for an internal move — new manager, new equipment, new access. Same machinery; it never starts itself, so raise it from the console or the profile tab.
When a template doesn't apply
Nothing errors when a hire matches nothing, which makes this the likeliest support question. Work down the list — and remember the effective preview answers most of it directly.
- Wrong kind An onboarding template never matches a termination.
- Active is switched off Never-set counts as active; only an explicit off switches it off.
- Start by hand only is on A different statement from inactive: the template is live and startable, it just never auto-matches. The shipped catch-up template carries it.
- A filled scope axis doesn't match exactly "Retail " is fine; Retail Ops is not. The department tree is not walked, so somebody in a team under Retail does not match a Retail-scoped template — scope it to their actual department, or leave the axis blank.
- Job-scoped, and the employee has no job The chain is employee → position → job → title. A blank anywhere along it means no job title. Check they have a Position, and that the position has a Job.
- Work type mismatch Full-time is not part-time. A blank axis matches everyone; a filled one doesn't.
- It matched, but its steps vanished in the merge A more specific template replaced or removed them by key. The preview shows exactly that.
- A journey of that kind is already running A second one is refused. Complete or delete the first.
Who can do what
| Permission | Unlocks |
|---|---|
| (app access) | My onboarding, My assignments, running and completing the steps you own, and signing off training you're the trainer for. |
| Manage onboarding journeys | The console and the journey builder — building templates, and starting, editing or cancelling journeys for other people. Also the Start a journey for selected button in HR records' directory. |
Granted under Settings → Module Access; admins pass everything. Hiding a button is only the tidy half — the server re-checks that you own a step on every action, so there's no way round it by URL.
App access alone is enough for the two personal screens: they're served by the app's own procedures, which resolve the caller to their own employee record. Nobody needs read permission on the Journeys entity to see their own checklist. The raw record tables in the sidebar are the exception — those follow ordinary record permissions like any other table.
When something goes wrong
| What you see | What it means |
|---|---|
| A new starter has no journey at all | No template matched. Work down the list above. If they were created on Add existing members, that's correct behaviour — backfilled people never onboard. |
| A hire got two contracts / two of the same step | Two templates contributed a step with no shared key. Give both steps the same key so the more specific one replaces the broader. |
| Blocked — nothing of that category is in stock | An Equipment step found no available asset. Add one, or change the category in the step's configuration. |
| A step sits in the Unassigned list | Its rule resolved to nobody — no manager set, no department head, nobody holding the HR permission. Fix the underlying field, or reassign the step from the console's pencil. |
| The e-signature app isn't installed, so this step is a manual task | Exactly what it says. Send the contract your own way and mark the step done, or install the app. |
| A contract is out but the step never moves | Press Check signature — it pulls the envelope's current state onto the step and the document vault row. |
| An edit in the builder disappeared | You edited a template the app maintains for you — the one derived from HR records' policy questionnaire. It is rebuilt from those answers on every save, and it renders read-only in the builder for that reason. Change the answers instead. |
| Bulk start reported 27 of 30 | The other three are listed with a reason — almost always already has an open journey. That's the panel doing its job, not an error. |
Where it connects
- HR records owns the employee, their documents and their equipment. A contract sent from a journey lands in that vault; equipment issued by a step shows on that profile — HR records.
- Approvals are the standard workspace ones. An Approval step lands in the same inbox as everything else.
- Leave & attendance picks a new starter up from the same employee record — Leave & attendance.
- The whole arc, from an open seat to a leaver's last day, is in Employee lifecycle.