Purpose of Table Correlations

When migrating data between systems, every record receives a new ID in the target. A user with sys_id = abc123 in the source might become sys_id = xyz789 in the target. This is fine for the user record itself, but the hundreds of other records that reference that user — every incident assigned to them, every group they manage, every comment they authored — still contain the source user ID, which is meaningless in the target system.

Table correlations solve this problem by defining how to match source records to target records and maintaining an in-memory cache of source-to-target ID pairs during procedure execution.

The Problem

Consider migrating incidents from one ServiceNow instance to another. Each incident has reference fields like assigned_to, assignment_group, and caller_id that point to other records by ID. When an incident is migrated:

1. The incident record is created in the target with a new sys_id
2. But the assigned_to field still contains the source user's sys_id
3. That source ID doesn't exist in the target — the reference is broken

Without a translation mechanism, every reference field on every migrated record would be empty or invalid.

What Correlations Do

A table correlation is a configured matching rule — a source table, a target table, and a query that identifies which target record corresponds to a given source record. During a procedure run, PB maintains an in-memory cache of source-to-target ID pairs for the correlation. When you enable a correlation on a step:

1. The step migrates records from source to target
2. For each record, PB stores the pair source sys_id → target sys_id in the in-memory cache
3. Later steps in the same run reuse the cached pairs; for any source ID that isn't already cached, PB runs the correlation's query against the target system to find the match, and caches the result for the remainder of the run

The cache is rebuilt every run — it is not saved to disk. What makes correlations work across re-runs is the configured query, which continues to identify the same target records as long as they still exist and the matching fields haven't changed.

Two Ways Correlations Are Used

1. Translating Reference Fields with ID Mappings

The most common use. When a child step migrates records that contain reference fields pointing to already-migrated parent records, ID mappings use the parent's correlation to translate each source reference to the corresponding target ID.

Example: Migrating incidents after users have already been migrated. The incident's assigned_to field contains a source user ID. An ID mapping on assigned_to references the users correlation to look up the target user ID automatically.

See ID Mappings for the full guide.

2. Filtering Child Records

When migrating child records (e.g., journal entries for incidents), you only want to extract children that belong to parents that were actually migrated. Precision Bridge can automatically configure the child step's filter using the parent's correlation cache — extracting only records whose reference field matches a source ID in the cache.

Example: After migrating 500 incidents, the journal entries step automatically filters to only extract entries for those 500 incidents — no manual filter configuration needed.

See Filtering Child Records for the full guide.

Correlations vs Output Variables

You can also achieve ID translation using output variables and formula expressions. Both approaches work, but they serve different scenarios:

Aspect	Table Correlations	Output Variables + Formulas
Persistence	In-memory cache during each run; on re-run, the configured query re-identifies the same target records	Recalculated each execution; lost when the procedure ends
Scope	Project-wide — any step in any procedure can reference them by name	Procedure-scoped — only available to subsequent steps in the same run
Reference fields	ID mapping type handles lookup automatically	Requires formula expressions (e.g., id_map.get([assigned_to]))
Child filtering	Enables automatic child filter configuration	Requires manual IN-list filter construction
Best for	Multi-procedure projects, re-runnable migrations, many reference fields	Simple one-off migrations within a single procedure

For most projects, table correlations are the recommended approach. They are cleaner, more maintainable, and enable features (ID mappings, child filter auto-configuration) that output variables cannot.

When to Enable Correlations

Enable a table correlation on a Migrate Records step when:

• Other steps will reference this table's records — If any later step has a reference field pointing to records migrated by this step, you need a correlation
• You need to filter child records — Correlations power automatic child filter configuration
• You expect to re-run the migration — On a re-run the correlation's query re-identifies the same target records, so ID lookups stay valid without having to re-execute the parent step
• Multiple procedures reference the same parent data — Correlations are project-scoped, so they can be referenced by name from any procedure

There is no downside to enabling correlations — the overhead is minimal and the cache is useful for debugging even if no other step references it.

Next Steps

• Setting Up Correlations — How to enable and configure correlations on the Output tab
• ID Mappings — Using correlations to translate reference fields
• Filtering Child Records — Automatic child filter configuration using correlation caches
• Chaining Correlations — When parent tables themselves have reference fields to other parents