ID Mappings

ID mappings are the primary way correlations are consumed. They automatically translate source record IDs into target record IDs using a table correlation cache. This is essential for maintaining reference field relationships during migration.

The Problem ID Mappings Solve

Consider migrating incidents. Each incident has an assigned_to field containing a user's sys_id from the source system. In the target system, that user has a different sys_id. If you copy the source value directly, the reference is broken.

An ID mapping solves this by looking up the source user ID in the users correlation and replacing it with the corresponding target user ID — automatically, for every record.

Configuring an ID Mapping

1. Open the child Migrate Records step (e.g., Migrate Incidents)
2. Navigate to the Fields tab
3. Select the reference field (e.g., assigned_to)
4. Choose ID as the mapping type
5. Configure:
   • Source expression — The field containing the source parent ID (e.g., [assigned_to])
   • Correlation — Select the correlation to look up (e.g., users)
   • Target field — The field to retrieve from the correlation (typically sys_id)

During execution, for each record, the ID mapping:

1. Evaluates the source expression to get the source parent ID
2. Looks it up in the specified correlation cache
3. Writes the corresponding target ID to the target field

Multiple ID Mappings on a Single Step

A step can have as many ID mappings as it needs. Each one independently references its own correlation. For example, an incident migration step might have:

Target Field	Source Expression	Correlation	Description
assigned_to	[assigned_to]	users	Translate the assigned user
caller_id	[caller_id]	users	Translate the caller
assignment_group	[assignment_group]	groups	Translate the assignment group
cmdb_ci	[cmdb_ci]	configuration_items	Translate the configuration item

Each mapping looks up a different correlation — or the same one (both assigned_to and caller_id reference users). They do not interfere with each other.

What Happens When a Lookup Fails

If the source ID is not found in the correlation cache, the ID mapping returns no value (the target field is left empty). This typically happens when:

• The parent record was not migrated — The user exists in the source but was excluded by the parent step's filter
• The parent step has not run yet — The correlation cache is empty
• The source field is empty — A null assigned_to produces no match (this is normal)

To handle missing lookups gracefully, you can use a Formula mapping with correlation_cache() instead, which allows you to provide a fallback value:

if_null(correlation_cache("users", [assigned_to]), "default_user_id")

See correlation_cache() for details.

ID Mappings vs Formula-Based Lookups

Both approaches achieve the same result — translating source IDs to target IDs. Choose based on your needs:

Aspect	ID Mapping	Formula with correlation_cache()
Setup	Select correlation from dropdown	Write formula expression
Fallback handling	No built-in fallback (empty on miss)	Can use if_null() for custom fallback
Readability	Clear and declarative	Requires understanding formula syntax
Best for	Standard reference fields	Cases needing fallbacks or conditional logic

For most reference fields, ID mappings are simpler and clearer. Use formula-based lookups when you need conditional logic or fallback values.

Prerequisites

For ID mappings to work:

1. A correlation must exist — Created on the parent step's Output tab (see Setting Up Correlations)
2. The parent step must have run — The correlation cache is populated during execution
3. The correlation cache must contain the referenced IDs — Parent records must have been successfully migrated

Example: Incidents Referencing Users and Groups

Setup:

1. Step 1: Migrate Users — Table correlation enabled → creates users correlation
2. Step 2: Migrate Groups — Table correlation enabled → creates groups correlation; ID mapping on manager field references users correlation
3. Step 3: Migrate Incidents — ID mappings reference both users and groups correlations

Step 3 field mappings:

Target Field	Type	Configuration
short_description	Source Field	[short_description]
assigned_to	ID	Correlation: users, source: [assigned_to]
caller_id	ID	Correlation: users, source: [caller_id]
assignment_group	ID	Correlation: groups, source: [assignment_group]
priority	Match	Priority value translation

The step translates three reference fields using two different correlations, alongside standard field mappings.

Related Documentation

• Why Use Table Correlations — Motivation and when to use correlations
• Setting Up Correlations — Enabling correlations on the Output tab
• Filtering Child Records — Using correlations to auto-filter child steps
• Chaining Correlations — When parent tables have their own reference fields
• Configuring Field Mappings — All mapping types on the Fields tab
• Advanced Mappings (Getting Started) — Introduction to Match, Lookup, and ID mapping types
• correlation_cache() — Formula function alternative to ID mappings