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_actionscalls the sameconnection.process_record_upsertsmethod 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.jsonor 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.
Related Documentation
- 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
Comments
0 comments
Please sign in to leave a comment.