Import Existing Spreadsheets

Most data teams already maintain source-to-target mappings somewhere — usually a long-running Excel workbook, occasionally a Google Sheet, occasionally a Confluence table exported to CSV. That work represents real institutional knowledge, and rebuilding it from scratch is both expensive and risky. Magellan's import path is designed so that knowledge becomes a governed asset on day one, not week six.

Each import atomically creates a versioned **mapping** (`<Mapping Name>`) together with the **source schema(s)** and **target schema(s)** it references. When a side has exactly one schema it is named `<Mapping Name> Source Schema` or `<Mapping Name> Target Schema`; when the spreadsheet draws from more than one source system or writes into more than one target structure, each is qualified (e.g. `<Mapping Name> Source Schema — HRIS`, `<Mapping Name> Source Schema — Payroll`). A mapping can therefore reference more than one schema on either side. **At the moment of import**, all artifacts produced from a single spreadsheet are stamped at the **same version** (typically `1.0.0` on first import). After that, under Schema & Map Version Control, each schema and the mapping version **independently** — a target schema may advance to `1.4.0` while the mapping is still at `1.1.0` and a source schema sits at `1.2.0`. The mapping always pins the exact source‑schema and target‑schema versions it was authored against, so any reviewer looking at mapping `1.1.0` can resolve the precise schema revisions that mapping was authored against, even when those schemas have since moved on.

The importer accepts `.xlsx`, `.xls`, and `.csv` directly, with a configurable column-mapping profile that names which column carries Source System, Source Table/Path, Source Field, Target Table/Path, Target Field, Transformation, and Notes. Profiles are themselves versioned MetaModel artifacts, so two teams importing differently-shaped spreadsheets can each pin the profile they used.

Each spreadsheet ingest writes a `SchemaIngested` entry for the source spreadsheet bytes (carrying the SHA-256 of the file) and a `MappingImported` entry per resolved mapping row (carrying the row's canonical payload hash, the column-profile ULID, and the actor's role at time of action). A reviewer can prove that a specific Magellan mapping was derived from a specific row in a specific spreadsheet revision.

Rows that cannot be resolved unambiguously — for example a target column that does not yet exist in any registered target schema — write `MappingImportDeferred` rather than `MappingImported`. Deferred rows surface in the Source‑to‑Target Mapping editor for a Contributor to resolve, instead of being silently dropped.

After import, the spreadsheet is no longer the source of truth. Subsequent edits write `MappingRevised` to the ledger; the spreadsheet remains as a provenance artifact stamped to a ULID, but it is intentionally read-only inside Magellan. This avoids the trap of two parallel mapping records drifting out of sync.

The same path is used to ingest mappings exported from legacy ETL tools (Informatica XML, Talend `.item`, dbt YAML), provided a Custom Import adapter is registered. The audit ledger semantics are identical — a row from a CSV and a row from an Informatica XML produce the same `MappingImported` entry shape.