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

# Data Onboarding

> Multi-step guided wizard for importing core organisation data — sites, employees, patients, and financial data — at /settings/imports/onboarding.

The Data Onboarding wizard (`/settings/imports/onboarding`) guides administrators through a sequential, session-persisted import flow covering the essential entity types needed to set up a new organisation on the platform.

## Overview

The page is gated by `pf.onboarding.manage`. It creates or resumes an onboarding session stored in Supabase, identified by an optional `:sessionId` parameter. If no session ID is present in the URL, a new session is auto-created and the user is redirected to the persisted URL. The wizard uses a **timeline** layout via `WizardShell` with six configurable steps: Organization Settings (`pf_organization_settings`), Review Vocabularies, Sites (`pf_site`), Employees (`hr_employee`), Patients (`pm_patient`), and Financial Data (`fa_account`). Each data step can be completed via CSV import (handled by `OnboardingStepContent`) or skipped; the Review Vocabularies step has no import and completes via explicit user confirmation. Steps with `dependsOn` are blocked until prerequisite steps complete. A rollback action is available for completed steps via `useRollbackStep`. After all steps are processed or skipped, the final **Complete** step summarises outcomes and offers navigation to import history.

When you resume a session saved before the Review Vocabularies step existed, the wizard detects it via `total_steps` and shifts completed-step numbers forward so they keep pointing at the right step.

## Who it's for

Requires permission `pf.onboarding.manage`.

## Before you start

* You must hold `pf.onboarding.manage`.
* Prepare CSV files for each entity type you intend to import. Column requirements vary by entity type — consult the import dialogs on each step.
* Understand the dependency chain: Organization Settings must be completed first; Sites must be completed before Employees or Patients.

## Steps

<Steps>
  <Step title="Start the wizard">
    Navigate to `/settings/imports/onboarding`. A new session is created and you are redirected to a session URL.
  </Step>

  <Step title="Review vocabularies">
    The first step lists the seeded picklists for your organization, grouped by core in an accordion with item counts. Expand a group to spot-check the values, and use the deep link to open any picklist in the editor before importing data that references it. This step is informational — you don't need to mark it complete to proceed.
  </Step>

  <Step title="Complete Organization Settings (required)">
    Step 0 is required. Upload or configure organisation settings data. This step is a dependency for every step that follows.
  </Step>

  <Step title="Review Vocabularies (optional)">
    Step 1 lets you review the picklists and vocabulary defaults your organisation will use during data import. There is no file upload — confirm to mark complete, or skip to revisit later.
  </Step>

  <Step title="Import Sites">
    Complete Step 2 (Sites) to unlock Steps 3 (Employees) and 4 (Patients).
  </Step>

  <Step title="Import Employees, Patients, and Financial Data">
    Complete or skip each remaining step (Employees, Patients, Financial Data). Skipping a step records it as `skipped` in the session; the step remains available for completion later by navigating back.
  </Step>

  <Step title="Rollback a step (if needed)">
    On a completed step, click **Rollback step** and confirm the dialog to revert the step's session status.
  </Step>

  <Step title="Complete onboarding">
    After all steps are done or skipped, advance to the **Complete** step and click **Complete Onboarding** to mark the session as completed.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Session persistence">
    Session state is stored in Supabase. If you close the browser and return to the session URL, progress is restored from `existingSession.step_status`. Sessions started before the Review Vocabularies step was added are automatically shifted on resume so previously completed steps stay aligned with their new step numbers.
  </Accordion>

  <Accordion title="Step dependencies">
    Steps with `dependsOn` show a dependency message and cannot be navigated to until their prerequisite steps are completed. The stepper enforces this check.
  </Accordion>

  <Accordion title="Rollback">
    Rollback removes the step's completed status from session state via `useRollbackStep`. Consult your SME to confirm whether underlying imported records are also removed.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Platform Foundation" icon="layer-group" href="/pf/overview">
    Platform Foundation overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/platform.tsx
  * src/platform/import/pages/OnboardingWizardPage.tsx
  * src/platform/import/hooks/useOnboardingSession.ts
</Accordion>