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

1

Open Data Import

Navigate to /settings/data-import. The page shows import shortcut cards and your organisation’s recent import history.
2

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

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

Review recent imports

The Recent imports table shows each batch with row counts for created, skipped, and failed records.
5

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.

​
Key concepts

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

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

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