Create and manage reusable import mappings

Who can perform the task

Preparers and administrators can create and test drafts. Reviewers and administrators can approve, request changes, and activate tested revisions. Read-only members can inspect active mappings but cannot change them.

Before you begin

Keep a representative CSV, Excel, or ODS source whose entity, period, currency, headers, sheet boundaries, and sample values you understand. You can upload an existing JSON mapping or let the preview propose a mapping for review. Test a new mapping with synthetic or approved non-production data first.

Quick path

1. Open Mappings, create a draft, then choose Start from source file.
2. Select the target filing and upload a CSV, .xlsx, or .ods source.
3. Confirm the detected sheets, table boundaries, headers, and suggested destinations.
4. Review ambiguous fields, then append the proposed pipelines or explicitly replace the draft graph.
5. Test the saved proposal against the same source, resolve every issue, and submit it for approval.

Workbench layout and filing evidence

Mappings and an open mapping now share one consistent workspace frame. Opening a mapping preserves the primary navigation and adds the editor tabs, selected-step settings, and evidence panels needed for detailed work.

The activity rail moves between areas of the workspace — the filing portfolio, mappings, and recovery plans where IRRD is enabled. Inside a mapping, the explorer's own tabs switch between the workspace list, source-file review, and retained revisions, and the editor tabs switch between the pipeline and its JSON document. The bottom panel groups validation problems, test results, governance actions, and history so that reviewing evidence does not take you away from the pipeline.

The Mappings console lists every workspace you can reach with its exact state, active revision, latest change, latest test, and next required action. The filter tabs preserve draft, pending-approval, approved, active, retired, and changes-requested states. A workspace with an open draft is listed by that draft state, because the draft is what a preparer or reviewer acts on next.

When a filing value has imported lineage, its recorded mapping revision opens as a read-only revision in the mapping workspace. This shows the exact graph used for that filing, even if another revision is now active. Preparers and administrators can explicitly create a new draft from that revision; this does not change the filing's existing values, lineage, or active mapping.

Detailed guidance

1. Open Mappings from the activity rail or from Import source data.
2. Choose Create mapping, then choose an organization and name the mapping. You may import a compatible legacy or graph-v2 JSON document instead.
3. Choose Start from source file, select the target filing, and upload the representative CSV, .xlsx, or .ods source. The target filing supplies the pinned taxonomy used for destination suggestions.
4. Review the detected workbook inventory and explicitly include the sheets and table boundaries that belong to this mapping. Formula cells are reported and never executed.
5. Review the deterministic source and destination suggestions. Ambiguous fields remain choices for you to correct. You can optionally request an AI refinement with the selected organization privacy mode; it is never applied automatically.
6. Save the reviewed proposal into a starter graph, then choose Append as new pipeline or explicitly confirm Replace current graph. This changes only the mapping draft, not filing values, and invalidates any prior test evidence.
7. You can still add or edit every step manually. The controls labelled Add field append a new source, filter, shape, destination, or control step; selecting an existing canvas node never creates another step. On a narrow screen, select a step in the ordered list to open its settings. The visual graph remains the primary desktop representation.
8. Add destination outputs. An output can copy a source value, use a fixed or default value, apply a lookup, convert a type, or calculate a value.
9. Calculations use decimal numbers, source columns in square brackets, +, -, *, /, and parentheses, for example ([Gross] - [Ceded]) * [Share]. Choose whether a blank operand rejects the row or is treated as zero. Functions, cell references, macros, names, and spreadsheet formula execution are not supported.
10. Map each output to a canonical cell ID or exact table, row, and column codes. Add context dimensions and required controls where the source contract needs them.
11. Wait for All changes saved and resolve validation issues. Advanced JSON is available for inspection and portability.
12. Choose a test filing and representative CSV, .xlsx, or .ods source, then select Test against selected source. Evidence is bound to the exact graph, source, taxonomy package, filing, actor, and time. Any edit invalidates it.
13. Select Submit tested revision. A reviewer or administrator checks the graph and evidence and selects Approve revision or Request changes.
14. Select Activate revision after approval. The approved revision replaces the prior active revision without changing filing values.
15. Return to Import source data, select the active mapping, and preview the source before applying values.

The earlier inline mapping flow remains available for existing mappings:

1. Expand Import source data and choose the tabular source.
2. Select an existing saved mapping, upload a mapping JSON, or leave both empty to use canonical headers and request suggestions.
3. Select Preview import.
4. For Excel or ODS, confirm the workbook sheets, header rows, and data ranges first, then preview again.
5. In Mapping suggestion review, use each sheet tab to include or exclude the table and inspect:
   • source-header choices;
   • the record-key or field-label column;
   • destination table, row, and column codes;
   • required contextual-dimension sources or fixed members;
   • ambiguity warning;
   • confidence and rationale;
   • the transformed sample values; and
   • exact sample destination identities.
6. Correct the key and source fields, edit target codes, add or remove fields, and verify that each contextual dimension has exactly one source or fixed value.
7. Enter a reusable mapping name and select Save reviewed mapping. Included sheets are saved together as one deterministic workbook mapping and do not call an assistant when replayed.
8. If you requested an AI suggestion, verify its recorded provider, model, prompt contract, privacy mode, time, and confidence. An AI proposal is never approval.
9. If you uploaded an approved JSON mapping, select Save upload for organization.
10. For a confirmed workbook layout, enter Reusable workbook mapping name and select Save confirmed workbook mapping.
11. To change a saved mapping, select it and expand Edit saved mapping. Inspect the added, removed, and changed-path counts. The approval queue identifies the exact path, change category, reason, confidence, and risk; the proposal summary uses its lowest confidence and highest risk so a safe layout change cannot hide a changed destination or transformation. Edit the JSON draft and select Test against selected source. Save a new revision only after the test passes and the proposal is explicitly approved, or select Clone as new mapping to create an independent mapping.
12. On a later period, choose the saved mapping and preview the new source.
13. Review Source schema comparison. Stop when headers are missing, unexpected, changed, or duplicated.
14. Apply only after the replayed mapping, transformed rows, rejected rows, destination values, totals, and lineage are correct.
15. Remove a saved mapping when its source contract is obsolete.

Expected result

The saved mapping is versioned and available only within its organization. Drafts, submitted revisions, approvals, rejections, and activation remain separate from the active import payload. A draft cannot be submitted without a clean test for the exact graph, and only an approved revision can be activated. Selecting the same revision produces the same canonical transformation for a matching source contract. Later imports report schema drift rather than silently adapting the mapping.

How to verify

Preview a small known file, confirm the mapping name and revision, and reconcile targets against the canonical header reference. After apply, confirm Imported value lineage names the same mapping revision and exact source coordinates.

Common problems

• A selected saved mapping and a newly uploaded mapping are mutually exclusive.
• An ambiguous suggestion requires an explicit choice.
• A confidence score is a review aid, not approval.
• A high-confidence layout change does not make another change safe. The queue retains each reason and escalates the overall proposal to its highest risk.
• Missing, unexpected, or duplicate headers mean the source contract drifted. Correct the source or create and test a new mapping instead of forcing the old revision.
• Saving a workbook mapping requires at least one confirmed imported sheet and a name.
• A stale-revision error means another administrator saved the mapping after you opened it. Reload and compare before saving another revision.
• If an unintended step was appended while building manually, select that step and remove it. Selecting an existing step opens its settings and does not modify the pipeline.
• Division by zero, invalid decimals, unknown columns, and rejected blank operands reject the affected source row. No JavaScript or spreadsheet formula engine is invoked.

Data consequences

Saving or deleting a mapping does not change filing values. Applying an import with that mapping does. Preview is mandatory for detecting unintended target changes.

Product limitations

Mappings apply only to CSV, .xlsx, and .ods sources, never XBRL. Arithmetic uses deterministic decimal operations and is deliberately not Excel formula compatibility. Legacy .xls is not supported. Suggestions are based on bounded source structure and, only when the selected privacy mode permits it, sample values. Suggestions do not establish the business meaning or regulatory correctness of a customer column. A saved mapping is not a source-system connector.