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 one of these files up to 10MB:

  • OrgSpec YAML (.orgspec.yml, .orgspec.yaml, .yml, or .yaml) - recommended
  • OrgSpec JSON (.orgspec.json or .json)
  • OrgSpec bridge JSON (.json) - advanced compatibility format
  • BambooHR CSV
  • Orgonaut CSV (or .txt)

Validate a canonical file before uploading when you have the OrgSpec CLI:

Bash
orgspec validate organization.orgspec.yaml

Orgonaut also validates canonical files during upload. The older orgonaut.import.v0.1 bridge remains supported for automated workflows that already produce it.

2) Format

Orgonaut attempts auto-detection, then lets you confirm:

  • OrgSpec.yml The primary format. Imports actors, including people, agents, and robots, plus explicit units, hierarchy, managers, positions, placements, and relationships.
  • OrgSpec JSON The canonical JSON representation of the same OrgSpec 0.1 document.
  • OrgSpec bridge JSON An advanced compatibility format for existing automation.
  • 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 record counts.

OrgSpec imports use the same run, snapshot, target, progress, and finalization safeguards as CSV imports, but use a graph-aware importer internally. Canonical YAML and JSON are validated against OrgSpec 0.1, checked for broken references and cycles, then normalized to the same internal import contract. Stable OrgSpec source IDs make repeated imports update matching actors, units, positions, and placements instead of creating duplicates.

OrgSpec behavior:

  • the selected Orgonaut tenant and Live View or scenario supply the target context
  • department and team units create their corresponding metadata records
  • other unit kinds remain canonical org units
  • unsupported protocol fields remain under meta.orgspec
  • non-reporting relationships and compatibility warnings remain attached to the import metadata
  • compensation is not part of OrgSpec v0.1

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 records
  • imported records
  • quarantined records
  • 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

OrgSpec quarantines are read-only records. Correct the source OrgSpec document, validate it, and start a new import. CSV rows can still be edited and reprocessed from the quarantine review page.