> ## 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 Import

> Hub for starting CSV imports across modules and viewing recent import history; upload CSV, Excel, or JSON files with field mapping and PHI masking.

The Data Import page (`/settings/data-import`) is a central hub for initiating CSV-based bulk imports across the platform and reviewing the history of previously completed imports.

## Overview

The page is gated by `system.organizations.admin` at the route level. It provides a grid of **Start an Import** cards — one per importable entity type — each of which navigates to the relevant module page where the actual import dialog lives. Entity types include employee roster, contacts, credentials, clinical oversight sessions, and custom object records. A **Recent Imports** section below uses `useImportBatchesList` to render a `DataTable` of `pf_import_batches` rows showing date, type, filename, row count, and created/skipped/failed counts. Deleting a history row removes the record from `pf_import_batches` only; imported records are unaffected.

## Who it's for

Requires permission `system.organizations.admin`.

## Before you start

* You must hold `system.organizations.admin` to access this page.
* Individual import actions on module pages may require additional module-level permissions (e.g., `hr.employees.create`).

## Steps

<Steps>
  <Step title="Open Data Import">
    Navigate to `/settings/data-import`. The page shows import shortcut cards and your organisation's recent import history.
  </Step>

  <Step title="Start an import">
    Click a card in the **Start an import** section to navigate to the corresponding module page. Cards are disabled (dimmed) if you lack the required module permission.
  </Step>

  <Step title="Complete the import on the module page">
    Use the Import dialog on the destination page to upload a CSV file and map columns. Return to `/settings/data-import` afterward to see the result in history.
  </Step>

  <Step title="Review recent imports">
    The **Recent imports** table shows each batch with row counts for created, skipped, and failed records.
  </Step>

  <Step title="Remove an import from history">
    Click the trash icon on a history row to remove it. This does not delete the records that were imported.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Import cards and module permissions">
    Each start-import card is conditionally enabled based on a module-level permission check via `useHasPermission`. Cards for permissions you lack appear dimmed and non-interactive.
  </Accordion>

  <Accordion title="Batch history vs. imported records">
    The history table records metadata about each import run. Deleting a history row only removes the metadata; the underlying imported records remain in their respective module tables.
  </Accordion>
</AccordionGroup>

## Uploading a new import

Administrators can upload data files for import at `/settings/imports/upload`. Requires `pf.import.upload`.

The New Import page provides a drag-and-drop file upload area (`useDropzone`) supporting CSV, Excel, and JSON formats. After file selection the platform parses the file using the appropriate adapter (`csvAdapter`, `excelAdapter`, `jsonAdapter`) and displays a preview. Users select the entity type to import (`hr_employee`, `ce_contact`, `hr_credential`, `rh_resident`, `fa_vendor`, `custom`) and map source columns to destination fields via `FieldMappingEditor`. The page checks for duplicates via `DuplicateReviewDialog` before creating an import batch through `useCreateImportBatch()`. Progress is tracked via `useImportProgress()`. All import events are logged via `useImportAudit()`.

1. Navigate to **Settings > Imports > Upload** (`/settings/imports/upload`).
2. Drag and drop your file onto the upload area or click to browse.
3. Select the **Entity Type** that matches your data.
4. Review the file preview and adjust field mappings in the mapping editor.
5. On the **Value Mapping** step, map source values to picklist options for any mapped field with a bound vocabulary.
6. Review and resolve any detected duplicates.
7. Confirm and start the import batch.

## Value mapping

When a field you map (for example, **Employment status**, **Contact type**, or **Resident status**) is bound to a picklist, the importer adds a **Value Mapping** step between field mapping and execution. It collects every distinct incoming value for the bound field and shows you, for each one, the suggested destination option.

Suggestions are produced by a five-tier match chain:

1. Exact match on the picklist item **value**
2. Exact match on the item **label**
3. Normalized match (case- and whitespace-insensitive)
4. Match against an item's **Aliases** (configured in [Picklists](/pf/picklists#aliases))
5. Fuzzy match with similarity ≥ 0.8 — surfaced as a suggestion only, never auto-accepted

Confirm or override each suggestion. Your decisions are saved as transforms on the import batch, so re-running the same file applies the same mapping. If none of the mapped fields are bound to a picklist, this step is skipped automatically.

Adding common typos and synonyms to the **Aliases** field on the destination picklist is the fastest way to improve future matches.

**Entity type** — Determines which table records are written to: `hr_employee` (employees), `ce_contact` (contacts), `hr_credential` (credentials), `rh_resident` (residents), `fa_vendor` (vendors), or `custom`.

**PHI masking** — The file preview applies masking to sensitive columns to prevent PHI display during the mapping review step.

**Import batch** — Each upload creates a tracked batch record enabling progress monitoring and rollback.

## 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/settings/pages/DataImportPage.tsx
  * src/platform/import-batches/hooks/useImportBatchesList.ts
  * src/platform/import/pages/ImportUploadPage.tsx
  * src/platform/import/hooks/useImportProgress.ts
</Accordion>