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

# Onboarding

> Onboarding is the checklist of things that have to happen for a new joiner before and around their first day — collecting documents, signing the…

Onboarding is the checklist of things that have to happen for a new joiner before and around their first day — collecting documents, signing the appointment letter, setting up IT accounts, arranging a desk, an induction, and so on. In Hitaji 360 an *onboarding* is a live instance of one of those checklists, attached to a specific employee, that HR and others work through and tick off.

You rarely build an onboarding by hand. Instead you keep a few reusable **onboarding templates** (see [Onboarding templates](/hr/user/lifecycle/onboarding-templates)) and *instantiate* one against a new employee. That copies the template's activities onto the employee, dates each one, and gives you a progress tracker. This page covers the onboarding *instance* — what it shows, who does what, and how it completes.

**You'll find this at:** `/hr/onboardings/:id`

> You usually reach an onboarding from the **Onboarding** tab on an employee's profile (`/hr/employees/:id`), or it is created automatically when a job offer is accepted (see below).

> 📷 *Screenshot: an employee onboarding detail page with the progress bar and the activity checklist — to be added.*

***

## Before you start

* **Which business am I in?** An onboarding belongs to a single business. If you run more than one business, confirm the business switcher at the top of the app is set correctly before instantiating — an onboarding created in the wrong business is invisible to HR working in the right one, and the system will refuse to let someone in another business open or edit it (you'll get a "not found").
* **One active onboarding per employee.** An employee can only have one onboarding running at a time. If you try to start a second while one is still **In Progress**, the system returns the existing one rather than creating a duplicate.

***

## The onboarding lifecycle (statuses)

Each onboarding carries a **status**:

| Status          | Meaning                                                                                      | What you can do                                             |
| --------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| **In Progress** | The default state once created; activities are being worked through.                         | Tick activities off, edit notes/assignee/due dates, cancel. |
| **Completed**   | Every activity is either Completed or Skipped. Stamped automatically with a completion time. | View only — no further changes.                             |
| **Cancelled**   | The onboarding was abandoned.                                                                | View only — no further changes.                             |

Two things happen automatically:

* **When the last outstanding activity is ticked off** (everything is Completed or Skipped), the onboarding flips to **Completed** and records the completion time for you.
* **If you re-open a completed activity** while the onboarding is Completed, it drops back to **In Progress** and clears the completion time.

***

## The activity checklist

The body of an onboarding is its list of **activities** (the individual tasks). Each row shows:

| Field             | Notes                                                                                                                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title**         | What needs doing (e.g. "Collect national ID", "Sign appointment letter").                                                                                                                               |
| **Description**   | Optional longer detail.                                                                                                                                                                                 |
| **Assigned role** | Who is responsible for the task by role — **HR**, **Manager**, **Employee** or **IT**. This comes from the template.                                                                                    |
| **Assignee**      | An optional *specific* person to do the task. You can set or change this per activity; it overrides the role.                                                                                           |
| **Due date**      | When the task should be done. Calculated from the start date plus the template's day-offset, and never lands on a weekend — if it would, it rolls forward to the next working day. You can override it. |
| **Status**        | **Pending**, **In Progress**, **Completed** or **Skipped**.                                                                                                                                             |
| **Notes**         | Free text on the activity, saved when you click away.                                                                                                                                                   |

> **Who is "assigned"?** At the moment an onboarding is instantiated, activities carry only a *role* (HR/Manager/Employee/IT), not a named person. You can attach a specific assignee to any activity afterwards on this page.

### Ticking activities off

Mark an activity **Completed** to record who completed it and when. Re-opening it (back to **Pending**) clears those stamps. You can also mark an activity **Skipped** if it doesn't apply — skipped activities still count as "done" for completion purposes, so an onboarding with skipped items can still reach **Completed**.

The progress indicator at the top is simply *done ÷ total*, where "done" counts both Completed and Skipped activities.

***

## Where onboardings come from

There are two ways an onboarding starts:

1. **Manually, from a template.** On the employee's **Onboarding** tab, choose to start a new onboarding, pick a **template** (only **active** templates appear) and an optional **start date** (defaults to today). The template's activities are copied onto the new onboarding and dated from the start date.

2. **Automatically, on job-offer acceptance.** When a candidate accepts a job offer, Hitaji 360 fires off an onboarding for them using the business's **default** onboarding template (the one marked default and active). This means a new hire often already has an onboarding waiting when HR opens their profile.

> 📷 *Screenshot: the "start onboarding from template" dialog with the template picker and start date — to be added.*

***

## Cancelling an onboarding

If a joiner falls through, cancel the onboarding. Cancelling sets it to **Cancelled** and marks every activity that wasn't already Completed as **Skipped** (completed activities are left intact for the record). A cancelled onboarding can't be edited afterwards.

***

## Notifications

> ⚠️ **Current state:** There is a *"notify users by email"* option when starting an onboarding, and the choice is saved, but **no emails are actually sent yet**. Activities only carry a role at instantiation (not a named recipient), so the system can't yet resolve who to email. Treat task hand-offs as a manual conversation for now. (Flagged for the team.)

***

## Permissions

| Action                                       | Permission |
| -------------------------------------------- | ---------- |
| View onboardings and templates               | `hr:read`  |
| Start an onboarding, tick activities, cancel | `hr:write` |

> The pages themselves are reached behind the `hr-employees:read` route guard. Note that HR roles in practice hold the coarse `hr:read` / `hr:write` slugs above — that is what actually governs what you can do here.

***

## Related

* [Onboarding templates](/hr/user/lifecycle/onboarding-templates) — build the reusable checklists onboardings are made from
* [Adding an employee](/hr/user/employees/create-employee) — create the person an onboarding attaches to
* [Job offers](/hr/user/recruitment/job-offers) — accepting an offer can auto-start an onboarding
* [The employee profile & its tabs](/hr/user/employees/employee-profile) — where you reach an employee's onboarding
* [Separation (offboarding)](/hr/user/lifecycle/separation) — the mirror-image process when someone leaves