Previewing a Migration

The Preview tab runs a read-only dry-run of the Migrate Records step against a sample of source records. The transformation pipeline, lookups, key-match classification, validation rules, and output variables all execute exactly as they would during real execution — but no records are written to the target, no attachments are uploaded, and the procedure's output variables are not mutated.

Use preview to verify field mappings, lookups, and filter logic against real source data before committing to a full migration.

Accessing the Preview Tab

Open a Migrate Records step in the editor. The Preview tab sits between Output and Advanced. The tab is available on any saved step — preview operates on the in-memory step configuration, so unsaved edits are previewed without saving first.

The cached project must exist on the server. If the project has never been saved, save it once before running preview.

Running a Preview

Click Run preview to fetch the first 100 records matching the source filter and process them through the full pipeline. The default sample size of 100 is the maximum; smaller samples are not currently exposed in the UI.

If the source filter references any procedure variables (those declared with ${variable} syntax in the filter query), the Provide preview values dialog opens before the run. Supply an indicative value for each referenced variable and click Apply. These values are remembered for the duration of the browser session, keyed by step id, and pre-fill the dialog on every subsequent run.

Reading the Results

The Preview tab shows a row per previewed source record with the following columns:

Column	Meaning
#	Row index in the previewed sample
Source ID	Primary-key value from the source record. Hidden by default when the source table has display fields configured
Source: \<field>	One column per source display field, where configured
Target ID	Existing target record id when the key mapping matched; empty when the record would be created
Action	`create`, `update`, `skip`, or `error` — the action that would be taken at real execution time
Attachments	When attachment migration is enabled, the count of attachments that would be migrated vs. skipped (over the size cap)
Validation	`passed`, `warning`, `failed`, or `skipped`, based on configured custom validation rules and any pipeline errors
Message	The first warning or error message attached to the record, if any
Bug icon	Opens the per-record drilldown dialog

Clicking any row also opens the drilldown.

Per-Record Drilldown

The drilldown dialog has four tabs:

Tab	Contents
Source	The full source record as a field/value table
Field mappings	Every target field, its computed result value, and the debug-step chain that produced it (lookup hits, formula intermediate values, ID-correlation matches)
Attachments	Per-attachment outcome with file name, file type, file size, and the reason for any SKIPPED entry
Validation	Per-rule outcomes for the step's custom validation rules, plus any pipeline-level error message

Source booleans, strings, lists, and dicts render in JSON form (true/false, no surrounding quotes on strings, dicts as {"a": 1}) so the source and target representations always match.

Per-Field Preview Drawer

The Field Mappings tab in the step editor exposes an Eye icon next to each field mapping. Clicking it opens a drawer that runs the same 100-record preview, but with one column per input to that specific mapping:

One Source: \<field> column for every source field the mapping reads
One Variable: \<name> column for every procedure or mapping variable the mapping reads
One Target: \<field> column showing the mapping's computed result value

This is the fastest way to debug a formula or lookup mapping — every input that feeds the result is visible alongside the output.

The drawer shares the underlying preview run with the Preview tab, so opening it after a run on the Preview tab does not re-fetch source records. Editing the mapping marks the field-scoped staleness flag, and a banner prompts a re-run.

Output Variables

When the step has output variables configured, a JSON panel appears beneath the records table showing the values those variables would hold after processing the previewed sample. The values are computed using the same _apply_output_variables helper as real execution, against a deep-copied list — the live procedure variables are not affected by preview runs.

Note that these are sample-scoped values: at real execution time, the variables accumulate across the full source set, not just the previewed records.

Staleness

When the step's configuration changes after a preview run (field mappings, lookups, filter, options, output variables), a staleness banner appears above the results inviting a re-run. The per-field drawer uses field-scoped staleness — editing one mapping marks only that drawer as stale, not every other field's drawer.

What Preview Does Not Cover

Preview executes the transformation side of Migrate Records in full, but stops short of any operation that requires writing to the target:

No target inserts or updates — _simulate_upsert_actions calls the same connection.process_record_upserts method the real path uses, but only to classify records as create vs. update; no writes occur.
No attachment uploads — attachment metadata is read from the source so the per-record outcome can be shown, but no bytes are transferred.
No output-variable persistence — the values shown in the Output Variables panel are computed against a deep-copied list and discarded when the dialog closes.
No sampling validation — the post-migration sampling check (configured under Advanced → Sampling Validation) requires the actual insert to have happened and is not run during preview.
No CSV logging — the dry-run report stays in memory and does not write to execution.json or any per-record CSV.

For the post-migration sampling check, see Advanced Options — Sampling Validation.

Troubleshooting

"No records returned by the source filter for the configured sample size." The filter matched zero records. Check the filter query (Filter tab) and any procedure-variable values supplied in the Provide preview values dialog.

"Source lookup is not defined" or a similar mapping error A single broken mapping does not abort the whole batch in preview — the record's row shows failed with the error message, and the other mappings still evaluate. Open the drilldown's Field mappings tab to see exactly which mapping raised and review its configuration. Real execution would re-raise this as a fatal error for the step.

Pipeline-level error banner above the results A failure outside any individual mapping (e.g. a misconfigured connection, an uninitialised lookup) is reported as a pipeline error. The partial state — whatever rows had already been built — is still shown so you can see how far the run got.

Configuring Field Mappings — how to define the mappings that preview exercises
Configuring the Filter — controlling which records preview pulls
Advanced Options — including sampling validation, the post-migration counterpart to preview