Skip to main content
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

1

Start the wizard

Navigate to /settings/imports/onboarding. A new session is created and you are redirected to a session URL.
2

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.
3

Complete Organization Settings (required)

Step 0 is required. Upload or configure organisation settings data. This step is a dependency for every step that follows.
4

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.
5

Import Sites

Complete Step 2 (Sites) to unlock Steps 3 (Employees) and 4 (Patients).
6

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.
7

Rollback a step (if needed)

On a completed step, click Rollback step and confirm the dialog to revert the step’s session status.
8

Complete onboarding

After all steps are done or skipped, advance to the Complete step and click Complete Onboarding to mark the session as completed.

​
Key concepts

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.
Steps with dependsOn show a dependency message and cannot be navigated to until their prerequisite steps are completed. The stepper enforces this check.
Rollback removes the step’s completed status from session state via useRollbackStep. Consult your SME to confirm whether underlying imported records are also removed.

Platform Foundation

Platform Foundation overview.

Governance & parity

Documentation coverage and governance.
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.
  • src/routes/platform.tsx
  • src/platform/import/pages/OnboardingWizardPage.tsx
  • src/platform/import/hooks/useOnboardingSession.ts