Key Mappings and Duplicate Handling
The Key Mappings section on a Migrate Records step defines how Precision Bridge determines whether a target record already exists. By configuring key fields, you control whether PB inserts a new record, updates an existing one, skips it, or raises an error when a match is found.
Why Key Mappings Matter
Without key mappings, every execution of a Migrate Records step would insert new records into the target — even if those records already exist. This leads to duplicates. Key mappings solve this problem by establishing a matching strategy that PB uses to check the target system before loading each record.
Key mappings are essential for:
- Re-runnable migrations — Run the same step multiple times without creating duplicates
- Incremental syncs — Update existing records with new data from the source while inserting records that do not yet exist
- Idempotent operations — Ensure the same outcome regardless of how many times the step is executed
Configuring Key Fields
To set up key mappings:
- Open the Migrate Records step
- Navigate to the Key Mappings section
- Add one or more key fields — these are target fields whose values will be used to check for existing records
For each record being loaded, PB queries the target system using the key field values. If a target record is found with matching values in all key fields, it is considered a match.
Single Key Field
The simplest configuration uses a single field as the key. For example:
- Key field:
sys_id - PB checks the target for a record where
sys_idequals the value being loaded
Multi-Field (Composite) Keys
You can configure multiple fields as a composite key. All key fields must match for a record to be considered a duplicate:
- Key fields:
emailANDdepartment - PB checks the target for a record where both
emailanddepartmentmatch the values being loaded - A match on
emailalone (with a differentdepartment) is not considered a duplicate
Match Actions
The Migrate Records step has two independent action settings — one for the "record exists" case and one for the "record does not exist" case. Both are configurable on the Tables tab.
Record Exists Action
When PB queries the target and finds a matching record, the Record Exists Action determines what happens:
| Action | Behaviour |
|---|---|
| Update | Update the existing target record with the new values from the field mappings. The record is overwritten with the transformed source data. Most common for sync scenarios. |
| Update with warning | Update the record, but also log a warning. Useful when updates should happen but you want them flagged for review. |
| Skip | Skip the record entirely — no insert and no update. The existing target record is left unchanged. Useful for one-time migrations where some target records may have been manually corrected after a previous run. |
| Log Error | Log an error for the record. Depending on your error handling configuration, this may stop the step or log the error and continue. Useful when duplicates are unexpected and should be investigated. |
Record Does Not Exist Action
When PB queries the target and finds no matching record, the Record Does Not Exist Action determines what happens:
| Action | Behaviour |
|---|---|
| Create | Insert a new record into the target. This is the default and most common action. |
| Create with warning | Insert the record, but also log a warning. Useful when new inserts should happen but you want them flagged for review (e.g. on an incremental sync where you expect most records to already exist). |
| Skip | Skip the record entirely. Useful for update-only flows where new source records should not be created in the target. |
| Log Error | Log an error for the record. Useful when missing target records indicate a data-integrity problem that should be investigated rather than silently corrected. |
The two actions are independent: you can, for example, choose Update when a record exists and Skip when it does not (effectively an update-only flow), or Skip when it exists and Create when it does not (an insert-only flow).
Choosing Key Fields
The choice of key fields depends on your data and migration strategy. Here are common patterns:
Natural Keys
Natural keys are business-meaningful fields that uniquely identify a record:
| Field | Use case |
|---|---|
email |
User records where email is unique |
employee_id |
HR records with a stable employee identifier |
order_number |
Order records with a unique order number |
name + category |
Composite key for records identified by a name within a category |
Advantages: Stable across systems, meaningful, easy to verify.
Risks: May not be truly unique (e.g., duplicate emails), may change over time (e.g., name changes).
System IDs
System-generated identifiers that are guaranteed unique within a system:
| Field | Use case |
|---|---|
sys_id |
ServiceNow record unique identifier |
id |
Database primary key |
key |
Jira issue key (e.g., PROJ-123) |
Advantages: Guaranteed unique, stable, no ambiguity.
Risks: May not exist in the target system if the record was created outside of PB. When migrating between different system types, the source system's ID format may not match the target's expected key.
Mapped Keys
In some cases, you may create a target field specifically for key matching. For example, adding a u_source_id field to the target table that stores the original source system ID. This field is populated by a field mapping and used as the key.
Advantages: Works even when source and target use different ID systems. Allows key matching without relying on business data.
Pattern:
1. Add a field mapping: target u_source_id mapped from source sys_id
2. Configure key mapping on u_source_id
3. On first run, records are inserted with u_source_id populated
4. On subsequent runs, PB matches on u_source_id and updates existing records
Common Patterns by System
ServiceNow to ServiceNow
- Key field:
sys_id(if preserving IDs) or a mappedu_source_sys_idfield - Match action: Update (for syncs) or Skip (for one-time migrations)
Database to Database
- Key field: Primary key column or a unique business key
- Match action: Update
CSV Import
- Key field: A unique identifier column in the CSV (e.g.,
id,email) - Match action: Update or Skip depending on whether existing records should be refreshed
Jira
- Key field: Jira issue key (e.g.,
PROJ-123) or a custom field storing the source ID - Match action: Update
Tips
- Always configure key mappings for production migrations to prevent duplicates. The only exception is a truly one-time insert into an empty target table.
- Test with a small sample first — Run the step with record sampling enabled to verify that key matching works correctly before processing the full dataset.
- Use Update for iterative development — During testing, the Update action lets you re-run the step repeatedly without creating duplicates, making it easy to refine field mappings.
- Check for uniqueness — Before choosing a key field, verify that it is actually unique in the target table. Non-unique keys can lead to unexpected update behavior.
- Consider composite keys — If no single field is unique, combining two or more fields may produce a unique identifier.
Comments
0 comments
Please sign in to leave a comment.