ORGONAUT
Login Signup
Docs
Imports and setup
Import workflow and runs

Import workflow and runs

Use this guide when you need a predictable way to load organisational data into Orgonaut and track exactly what happened during the run.

Orgonaut treats every import as a first-class run with status, stage progress, counts, and review tools.

Imports are visible only to roles that include import management. In the default tenant role bundles that means owner, admin, and manager.

Where imports live

  • Imports list: /imports
  • Progress page: /imports/{importRun}/progress
  • Quarantine review: /imports/{importRun}/review

From the imports list, you can filter by run status (pending, processing, completed, failed) to focus on active work or troubleshoot failures. If your role does not include import management, the import entrypoints stay hidden and direct route access is denied.

Import wizard flow

The import wizard has three explicit steps:

  1. Upload
  2. Format
  3. Target

1) Upload

Upload a CSV (or .txt) up to 10MB.

2) Format

Orgonaut attempts auto-detection, then lets you confirm:

  • BambooHR CSV BambooHR detection now covers both the classic employee export and directory-style files that use headers such as Name, PersonID, SupervisorID, and Email.
  • Orgonaut CSV (canonical)

For BambooHR imports, actor matching now prefers Bamboo source identity on the actor record (source_hris = bamboohr, source_hris_id = PersonID) and only falls back to email for compatibility.

3) Target

Choose where to import:

  • Live Baseline: imports into your current live structure
  • New Scenario: creates a fresh scenario and imports directly into it

If you choose baseline, Orgonaut takes a baseline snapshot before applying data.

What happens after you click Start import

A queued pipeline runs through stages and updates progress in real time.

Typical stage sequence:

  • Parse
  • Actors
  • Managers
  • Teams
  • Departments
  • Placements
  • Positions
  • Compensations
  • Finalize

The progress page shows stage-by-stage completion, percent complete, and row counts.

Actor import behavior now follows source-aware identity rules:

  • BambooHR rows can import without email when PersonID is present.
  • Generic CSV rows can import without email only when you provide source_hris and source_hris_id.
  • SupervisorID is always treated as the BambooHR PersonID of the manager, not an Orgonaut actor ID.

Run outcomes and redirects

When the run completes:

  • If there are quarantined rows, you are directed to review.
  • If no quarantines:
    • scenario import opens the created/target scenario
    • baseline import opens live context

Each run stores summary numbers:

  • total rows
  • imported rows
  • quarantined rows
  • who ran it
  • when it started/completed

Choosing baseline vs scenario imports

Use baseline import when:

  • you are replacing or loading your authoritative live view
  • stakeholders are aligned on immediate baseline changes

Use scenario import when:

  • you want to compare imported structure before promotion
  • you want safe modeling and review first
  • you are testing source data quality with lower risk

Failure handling

If a run fails:

  • inspect failed stage and error details in progress
  • for scenario imports, use retry to spin a clean replacement scenario/run
  • for baseline imports, rerun carefully after fixing source data (baseline retry is intentionally restricted for safety)

Common identity-aware quarantine reasons now include:

  • missing_required_identity
  • duplicate_source_identity
  • identity_conflict