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_id equals 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: email AND department
PB checks the target for a record where both email and department match the values being loaded
A match on email alone (with a different department) 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 mapped u_source_sys_id field
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.