Manage ingestion mappings

Outcome

A mapping definition that turns a vendor's raw inbound rows (member rosters, charge files, eligibility files) into the platform's canonical entities, dry-run-tested against a real sample, and published with a clear version history.

Prerequisites

Scope	What it lets you do
ingestion.mapping.read	View mappings and versions
ingestion.mapping.write	Create / edit drafts, run dry runs
ingestion.mapping.publish	Publish a draft as the new active version

A registered ingestion feed that this mapping will be bound to — see 5.7 — Manage SFTP feeds & Push API keys. Mappings created without a feed binding are valid but inert.

Anatomy of a mapping

A mapping definition is YAML with three blocks:

# Source schema — what the incoming row looks like
source:
  format: CSV          # or X12, FHIR, HL7v2, FIXED_WIDTH
  encoding: utf-8
  fields:
    - name: member_external_id
    - name: dob
    - name: payer_code

# Target — which canonical entity to produce
target: member

# Field mappings — how to fill the target
mappings:
  - target: externalId
    source: member_external_id
  - target: dateOfBirth
    source: dob
    transform: parseIsoDate
  - target: coveragePolicies[0].payerAlias
    source: payer_code

# Validations — fail the row if these don't hold
validations:
  - field: externalId
    rule: required
  - field: dateOfBirth
    rule: notFuture

Steps

1. Pick Configuration → Ingestion → Mappings at /admin/ingestion/mappings. Each row shows the mapping name, target entity, the feed it is bound to, and the active version number.

2. Click + New mapping or open an existing one. The detail page has three sub-views:

   View	What it does
   YAML	Full Monaco YAML editor. The most expressive option.
   Visual	Form-based field mapper, transform picker, validation builder. Good for quick edits.
   Preview	Drag-drop a sample file and see how rows map.

   The Visual view writes the same YAML — switch between them freely.

3. Use the Visual view's FieldMapper to drag a source field onto a target field. The platform auto-suggests transforms when source and target types disagree (e.g. string → date suggests parseIsoDate). Add a transform from the picker, or chain several.

4. Add validations under the validation builder. Common checks:

   Rule	Meaning
   required	Reject the row if the field is empty.
   regex	Match a pattern.
   oneOf	Value must come from a small set.
   notFuture	Date cannot be in the future.
   range	Numeric range.

5. Dry-run the draft with the Preview view. Drop a sample file (CSV / X12 / FHIR / HL7v2 / fixed-width). The platform parses it client-side, runs your mapping's transforms, and shows:

   • The first 50 rows transformed to the canonical shape.
   • Any validation failures with row + field highlighted.
   • A summary of pass / fail counts.

   Iterate the YAML until the preview is clean.

6. Save the draft. Drafts are client-only — closing the page does not lose them, but they don't activate any production behavior either.

7. Publish with Publish version. The platform validates the YAML one last time against the kind's schema, increments the version, and makes the new version active for the bound feed.

Diff between versions

The detail page's History tab lists every published version with the publishing user and timestamp. Click two versions and pick Diff to see the YAML diff side-by-side. Useful when a recent run produces unexpected rows and you need to confirm what changed.

Validation

Check	Expected
Preview produces clean rows on a sample file	Yes.
Published version visible in History tab	Yes.
Bound feed picks up the new version on next batch	Yes — subsequent batches log the version number.

Troubleshooting

Symptom	Cause	Fix
Preview row count is 0	Source format guess is wrong	Set source.format explicitly; e.g. tab-delimited CSV needs delimiter: "\t".
Transform suggestion missing	Source field type unknown	Add an explicit type: to the source field block.
Publish blocked: "schema mismatch"	YAML drifted from the kind's zod schema	The error message points at the line; fix and retry.
Live batch fails after publish	The new version's transform throws on an edge-case row	Open the batch, copy the failing row, paste into Preview to reproduce; fix and republish.

Next

5.6 — Manage trading partner credentials