Setting Up Correlations

This article walks through enabling and configuring table correlations on a Migrate Records step.

Enabling a Table Correlation

Open a Migrate Records step (e.g., Migrate Users)
Navigate to the Output tab
Locate the Table Correlation section
Enable the toggle to save record IDs to a correlation cache
If no correlation exists for this source-target table pair, click to create a new correlation and give it a descriptive name (e.g., users, incidents, departments)

That's it. When the step executes, PB automatically stores every source-to-target ID pair in the correlation cache.

Naming Correlations

Choose clear, descriptive names that identify the table being correlated:

Good names	Why
`users`	Identifies the table clearly
`incidents`	Easy to reference from other steps
`departments`	Obvious what it contains

Avoid generic names like correlation1 or cache — you will reference these by name in ID mappings and formulas, so clarity matters.

What Gets Stored

For each record migrated by the step, the correlation cache stores:

Source ID — The primary key value from the source record (e.g., sys_id)
Target ID — The primary key value of the created or updated target record

This mapping is what allows later steps to translate source references into target references.

Correlation Cache Behavior

Property	Behavior
In-memory per run	The cache exists only for the duration of an execution. It starts empty at the beginning of every run and is discarded when the run ends.
Populated two ways	The parent Migrate Records step writes pairs into the cache as it inserts or updates records. When a downstream step asks for a source ID that isn't already cached, PB runs the correlation's query against the target system and caches the result for the rest of the run.
Project-scoped within a run	Any step in any procedure executed in the same run can reuse cache entries that have already been populated during that run.
Re-runs work via the query	On a re-run the cache starts empty again, but the configured query continues to find the same target records — provided they still exist and the matching fields haven't changed. The cache itself is not what makes correlations re-runnable; the query is.

Validation

When a correlation uses a query to re-find records (rather than a simple primary-key mapping), Precision Bridge checks that query for references that cannot be resolved. If the query references a procedure variable or a source field that no longer exists — for example, after a source field is renamed or removed — the correlation is flagged in the Validation column of the correlations table. Resolve the broken reference before running the procedure.

These checks depend on the source and target table metadata. While that metadata loads, validation shows a transient "validating" state and the broken-reference checks run once the metadata is available. Reassigning the correlation's source or target connection re-runs the checks automatically.

Combining with Output Variables

Output variables and table correlations are configured on the same Output tab but are independent features. It is common to use both:

Table correlation — For source-to-target ID tracking used by ID mappings and child filter auto-configuration
Output variable (record count) — For validation logic in subsequent steps (e.g., migrated_count > 0)
Output variable (ID map) — For formula-based lookups within the same procedure (a lightweight alternative to correlations for simple cases)

These do not interfere with each other.

Why Use Table Correlations — Motivation and when to enable correlations
ID Mappings — Using correlations to translate reference fields on child steps
Filtering Child Records — Automatic child filter configuration using correlation caches
Output and Correlations (Migrate Records) — The Output tab on Migrate Records, covering both output variables and correlations