Setting Up Correlations

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

Enabling a Table Correlation

1. Open a Migrate Records step (e.g., Migrate Users)
2. Navigate to the Output tab
3. Locate the Table Correlation section
4. Enable the toggle to save record IDs to a correlation cache
5. 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.

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.

Related Documentation

• 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