> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hr-easy.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Pre-boarding and onboarding

> The journey between an accepted offer and a productive first week.

Two distinct phases, often confused:

* **Pre-boarding** is everything between "yes" and the first day. The person is not yet
  an employee; they still sign in as an applicant.
* **Onboarding** starts once employment does. It is a checklist of things the
  organization must do.

## Pre-boarding

The moment an application is marked hired, a **pre-boarding journey** starts. It is
orchestrated by events rather than by someone remembering to click next: the
orchestrator listens for personal-data submission, document uploads, and contract
signature, and advances the journey itself.

### The journey

<Steps>
  <Step title="Welcome">
    The new hire receives a magic link to their portal. The link is long-lived by design — the
    default onboarding link expiry is seven days (`ONBOARDING_LINK_EXPIRY_MINUTES`) — because a new
    hire's first interaction should not be a expired-link error.
  </Step>

  <Step title="Personalstammblatt">
    They complete the personal-data form: full identity, addresses, AHV number, bank details,
    marital status and children, permit where applicable. This is the data payroll needs, collected
    once, by the person who actually knows it.
  </Step>

  <Step title="Documents">
    They upload exactly the documents the position's document matrix requires — ID, diplomas,
    **Privatauszug**, **Sonderprivatauszug** for work with minors. The matrix is defined on the
    position, so nobody has to remember what a given role needs.
  </Step>

  <Step title="Contract">
    The agreed terms captured at hire flow into a generated contract, which is sent for signature.
    See [Contracts](/guides/lifecycle/contracts).
  </Step>

  <Step title="Finalisation">
    When every blocking step is complete and the contract is signed, the journey finalises: the
    draft employee is promoted to a real employee record with its first employment period.
  </Step>
</Steps>

### The cockpit

HR works pre-boarding from a cockpit listing every in-flight journey, which step each
is on, and what is blocking it. Steps can be resent, skipped where they are not
blocking, or the whole journey cancelled.

| Capability              | Role        |
| ----------------------- | ----------- |
| `preboarding:view`      | `HR_STAFF`+ |
| `preboarding:manage`    | `HR_STAFF`+ |
| `preboarding:configure` | `ADMIN`+    |

Journey **templates** are `ADMIN`-only, mirroring pipeline configuration: a template
change shapes every future hire's journey.

<Note>
  Pre-boarding also covers re-hires and internal moves. Someone who already holds an `EMPLOYEE` or
  `MANAGER` role keeps it while pre-boarding into a new position — the self-service journey is gated
  on audience, not on being an applicant.
</Note>

## Onboarding

Once employment starts, the onboarding checklist runs. Unlike pre-boarding, this is
work *your organization* does.

### Task templates

Checklists are seeded from **onboarding task templates**. Each template carries a
title, a description, a category, and a sort order — and, crucially, **match rules**:

| Match rule   | Effect                                   |
| ------------ | ---------------------------------------- |
| `jobTitle`   | Only seed for hires with this job title. |
| `department` | Only seed for this department.           |
| `locationId` | Only seed at this Standort.              |
| *(null)*     | Applies to everyone.                     |

So a "Sonderprivatauszug on file" task attaches to teaching roles and a "workshop
safety briefing" to a caretaker, without anyone curating a per-hire list.

Categories are `IT_SETUP`, `HR_ADMIN`, `TEAM_INTRO`, `TRAINING`, `COMPLIANCE`,
`INTEGRATION` and `OTHER`.

Seeded tasks get an assignee and a due date on the actual plan, and move through a
status from pending to complete. Overdue documents are chased by a scheduled reminder
job.

### Integration tasks

A task can be an **integration** rather than a checklist item. Three types run
automatically instead of waiting for a person:

| Type                   | What it does                                                                            |
| ---------------------- | --------------------------------------------------------------------------------------- |
| `M365_USER_PROVISION`  | Creates the Microsoft 365 user and assigns licences and roles.                          |
| `DORMAKABA_KEY_ASSIGN` | Assigns the digital door key, with its access zones.                                    |
| `EMAIL_NOTIFICATION`   | Sends the employee's data to a responsible person, with a per-locale subject and intro. |

Each carries its own status — `IDLE`, `EXECUTING`, `SUCCESS`, `FAILED`, `SKIPPED` —
plus the external IDs it produced, the last error, and when it last ran. A failed
provisioning is visible and retryable, not a task that quietly stays open.

A task can also start a **workflow** instead, linking the checklist item to a
[workflow instance](/guides/admin/workflows) for anything that needs approval steps.

### Document reminders

A scheduled job chases outstanding onboarding documents. It is the difference between
noticing a missing Privatauszug in week one and noticing it in month three.