Select Key Mappings Option

Selecting this option allows the user to define one or more mapped fields as a primary key for the mapping.  These are then used to identify a matching target record for updating.  If no matching record with the same key value(s) is identified on the target, then a new record is inserted.

Note that if you have selected the Import Set (Scripted) migration method with Migrate Sys-Ids then this will take precedence over any mapped fields that you define here.  In this case, if a matching Sys-Id is found then this record is updated, otherwise Precision Bridge will look for a match based on the Key Fields provided.

In this example the Number field is used as a Key to uniquely identify the target record.

Use the Select Mapped Target Field to Add/Remove fields from the Key Mapping List.  Up to five field mappings can be selected.  

Note that the key mapping is not restricted to Simple mappings. As long as the value derived from the mapping matches the current value on the target, the mapping will operate correctly. So you can use any type of field mapping (assignment, lookup, value match etc) as key mappings.

If more than one target record is found which matches the key then the Multiple Match Action is followed:

Use First: The first record identified is UPDATED.

Skip Record: The current record is skipped and no update is performed.

Log Error: No update is performed and an error is recorded in the migration log.

The diagram below provides a summary of the logic applied when the Select Key Mappings option is selected.

Warning: Changes to the values of source/target fields used in key mappings externally (between executions) can lead to the mapping of the records being ‘broken’. Therefore it is important to choose key fields on the source and target server and are unlikely to change. If changes are made externally to these key fields, ensure they are made on both the source and target record.

Example:

• Use Company name field [simple mapping] as the key field
• Execute the project, source company ‘ACME’ maps to target company ‘ACME’, which gets updated
• Change the target company name to ‘ACME Ltd’
• Subsequent execution will create a new company record ‘ACME’

Additional Key Mapping Options

The following options are also available as part of the key mapping definition:

Option	Meaning
Allow NULL values in key fields	If unchecked, a null in a key value will lead to an error and the entry not being migrated. For reference mappings, if the mapping uses a key with a NULL, the NO Match procedure is followed