Table Correlations

Table correlations track the mapping between source and target record IDs across migration steps. They simplify the process of maintaining reference field relationships when migrating parent-child or related records.

Purpose

When migrating data, records receive new IDs in the target system. If a child record (e.g., a journal entry) references a parent record (e.g., an incident) by ID, you need a way to translate the source parent ID to the target parent ID.

Table correlations provide this translation. A correlation is a configured matching rule between a source and target table; during a run, PB maintains an in-memory cache of source-to-target ID pairs for the correlation, populated as the parent step migrates records.

Setting Up a Table Correlation

Enable Correlation on the Parent Step

1. Open the parent Migrate Records step (e.g., Incidents)
2. Navigate to the Output tab
3. Under Table Correlation, enable the toggle to save record IDs to a correlation cache
4. Create a correlation if none exists

Use an ID Mapping on the Child Step

1. Open the child Migrate Records step (e.g., Journal Entries)
2. Navigate to the Fields tab
3. For the reference field (e.g., u_parent_id), create an ID mapping:
   • Source expression: The source record ID — e.g., [element_id]
   • Correlation: Select the incident correlation created above
   • Target field: Select sys_id (the target incident ID)

Correlation vs. Formula Approach

You can achieve similar results with either approach:

Approach	How It Works	When to Use
Table Correlation + ID Mapping	Builds an in-memory cache of source-to-target ID pairs during each run; on re-runs the correlation's configured query re-identifies the same target records. ID mapping looks up target IDs automatically.	When you need reusable ID translation across multiple steps or procedures, including across re-runs
Output Variable + Formula	Stores an ID dictionary in a variable; formula expression looks up values	For simple, single-use scenarios within one procedure

Example

Without correlation (using formula): - Incidents step output variable: incident_id_map (dictionary of source → target IDs) - Journal entries u_parent_id mapping: Formula incident_id_map.get([element_id])

With correlation (using ID mapping): - Incidents step: Table correlation enabled - Journal entries u_parent_id mapping: ID mapping using the incident correlation

Both approaches produce the same result — the correlation approach is cleaner for complex projects with many reference relationships.

Next Steps

For the comprehensive guide to table correlations, see the dedicated Table Correlations category:

• Why Use Table Correlations — Motivation, use cases, and when to enable correlations
• Setting Up Correlations — Detailed setup and configuration guide
• ID Mappings — Using correlations to translate reference fields
• Filtering Child Records — Automatic child filter configuration
• Chaining Correlations — When parent tables have reference fields to other parents