Creating a Reference Form Mapping (ServiceNow-ServiceNow)

Most of the templates provided with Precision Bridge include the required Reference Form Mappings at the top of the mappings list.  However, if the required reference mapping is not included, you can create your own.  Note this is only necessary if the SYS-IDs of the corresponding records are different on the source and target tables.  The reference mapping is used to match the records using a different field or set of fields so that the corresponding SYS-ID can be extracted and used in subsequent field reference mappings to maintain relational integrity.

The Reference Form Mapping must be positioned to run BEFORE any other form mappings that reference it.  Usually this means positioning towards the top of the mappings list.

Simply follow the steps to create a new Form Mapping, (in this example, map the source User table to the target User table), then just map the fields required to uniquely match the corresponding records.  Since the SYS-ID values are different, use a different field or set of fields that uniquely identify the records.  For the User table, use the User_ID or Name.  Try to avoid using lookup field mappings or reference field mappings unless you need them.

Then on the Key Mapping tab select the same fields that you mapped from the field list:

Enabling and Disabling Reference Form Mappings

Note it is not necessary to enable the Reference Form Mapping - it is only used to generate an internal cache of the records based on the mapped fields. 

However, sometimes it might be necessary or more efficient in terms of performance to enable the reference mapping to ‘build’ the map of all source-to-target id’s.  This might be the case if:

• The number of records in the referenced table is small and the number of records being migrated is large.
• The key mapping in for the referenced table is complex, for example involving reference mappings, temporary variables in an assignment expression or lookups.

In this case, make sure that the mapping is enabled and then navigate to the Options tab and set the Entry Exists on Target Action and No Entry Exists on Target Action to Skip Entry like this:…

Otherwise, simply leave the reference form mapping disabled for optimal performance.

The reference form mapping can now be used in subsequent reference field mappings that are executed later in the same project.

Notes on use of Key Mapping in Reference Form Mappings

1. If the Key Mapping uses ‘Selected Key Mappings’ no match will be found unless all target values match the translated source values. Note that the source field value is not mapped directly, it is the value derived from the source mapping that is used. For Example: If you use a value mapping for the status field [New->Assigned] as the key mapping, the target entry with value ‘Assigned’ will match with the source entry ‘New’.
2. If the Key mapping  uses  ‘Server Defined  Record ID’ , no match will be found UNLESS a source record with the same ID that is referenced was previously successfully migrated (either in this execution or in an earlier execution) - Note that Server DefinedRecord ID Key Mappings will deprecated in Precision Bridge 7.0 and should no longer be used.