The mapping editor
Open a mapping from the migration’s Sources tab — expand the source
you want and click Open mapping — or directly via /mappings/<id>.
The editor is three panels side by side:
| Panel | What it does |
|---|---|
| Source (left) | The fields of one sample record, searchable, click to drop a field into the expression. |
| Mapping (middle) | The JSONata expression, with a Valid / Invalid indicator beside the JSONata label. |
| Preview (right) | What that sample record turns into, re-evaluated as you type. |
The bar across the top names the resource you’re editing, the route
(magento → shopify), and the version you’re on — with a dot that turns
blue the moment you have unsaved changes. Version history and
Publish live at the right-hand end.
Source panel
Three views, switched with the control in the panel header:
| View | What it shows |
|---|---|
| Source | Every field on the current sample record, with its value. A dot marks a field the mapping already reads, and the header counts how many of them you’re using. |
| Target | Every destination field you can map for this resource, marked mapped or unmapped, with a coverage bar. Toggle Unmapped only to focus on the gaps. |
| Raw | The sample record exactly as it was read from the source, as collapsible JSON. |
Clicking a field in Source inserts its path at the cursor. Clicking an unmapped field in Target inserts the destination key ready to fill in.
Some destination fields are filled in for you from what you’ve already mapped (product variants and SEO, for example). Those appear in a separate Computed group and are read-only — you don’t map them directly.
Mapping panel
The indicator beside the JSONata label reads Valid or Invalid
as you type. When it reads Invalid, a strip under the header says what is
wrong with the expression, and Publish stays disabled until you fix
it — an expression that can’t be parsed would fail every record on the
next run.
Help opens a searchable list of every function available in a
mapping, each with its signature and one line of what it does. Click one
to insert it. It covers JSONata’s own functions plus the Graftport
helpers, so things like $join(care, ", ") are something you find rather
than something you have to already know.
Preview panel
Three views, again switched from the panel header:
| View | What it shows |
|---|---|
| Preview | A resource-aware rendered view of the Shopify result — labelled fields, images, variants, metafields. This is what a non-technical reviewer can read without learning JSON. |
| Output | The raw result of evaluating the expression, as collapsible JSON — handy for debugging the expression itself. |
| Lookups | Pull a value from another source — another resource (a gift card’s owning customer via its order) or another source of this same resource — and use it in the mapping as $._refs.<name>. See Cross-resource lookups. |
Both Preview and Output update automatically as you edit. They differ in what they evaluate:
- Output runs the expression in your browser and prints the raw result.
- Preview sends the record and the expression to Graftport, which evaluates it and applies the same preparation the transform phase does — so source-side fields are folded into metafields, variants and the rest exactly as they would be before a load, rather than shown as raw passthrough.
If the record would be rejected by Shopify, Preview says so above the payload and explains which field is at fault.
Stepping through sample records
The Row 1 of 5 control in the Preview header pages through the sample records loaded for this resource. Use the arrows to move one at a time, or click the label to open the picker and search by record ID. Every panel — source fields, preview, output — follows the record you pick.
Use real records from a recent extract; synthetic samples lie. If the resource has no records yet, run an extract for the migration first.
Publishing a change
Publish v‹n› creates a new mapping version and asks you to confirm first. You can add a short note describing what changed — it shows up next to the version in history. The migration automatically advances to the new version, and the publish is recorded in your workspace’s audit trail.
Publishing a mapping does not re-run anything. Records that were already prepared keep their old payloads until the next transform run touches them.
Version history
Version history opens the list of every published version, newest first, with its note and when it was published.
Open a version to see a line-by-line diff between it and the expression you currently have in the editor — green for added lines, red for removed, with unchanged stretches collapsed. This is what you want when you’re unsure what changed between the run that worked and the run that didn’t.
Restore loads that version back into the editor as a draft. Versions are never rewritten, so putting an old one back means publishing it again as the next version — the editor says as much, and nothing changes for any run until you do.
Forking a default template
You can’t edit a default template directly. Clicking Fork to edit on a migration’s mapping does three things:
- Copies the current default template’s version into a new workspace-owned template.
- Repoints this migration’s mapping at the fork.
- Leaves other migrations untouched — they stay on the default.
After forking, publishing writes into your fork’s version history.
The iteration loop
- Extract (or reuse recent extract data).
- Step to a real record in the Preview header.
- Tweak the expression until Preview looks right.
- Publish — new version, migration auto-advances.
- Run a transform-only pass and inspect the prepared records.
- Run load when you’re happy.
Nothing in steps 1–3 writes anything: the editor evaluates against sample records only, and no version is created until you publish.