Reference Form Mappings - Overview and Worked Example

A Reference Form Mapping is a mapping that is not intended to migrate data, but is created for the sole purpose of providing the key mappings to map a source ID to a target ID.

Worked Example

Consider the following example for a Remedy to Service Now migration.

Both the source and target servers have a user form/table (CTM:People for Remedy and sys_user for Service Now). However, the primary identifier for the Remedy Entries is the Request ID (e.g 1000000000001) while the primary identifier for Service Now records is the sys_id (e.g 32131ed3242ce432423deb3243260ded)

The user wants to migrate incidents (Helpdesk tickets) from Remedy into an incident record in Service Now. The Remedy Helpdesk form has a field Person ID, which records the id of the person raising the ticket. The Service Now also has a field, caller_id which records the sys_id of the user raising the incident. So how can we make sure the caller_id field gets populated with the id of the correct user?

First, we need to identify a field (or set of fields) on the source and target user tables (other than the requestID/sys_id) that uniquely identify the records and can be mapped. For users, this might be the email address, which is usually the same on both systems.

Creating the Reference Form Mapping

• Create a Form Mapping for the User form/table. By convention, prefix the identifier with 'Reference' as shown below:

• The ONLY mapping that is needed is the one for the email address (or other field(s) that uniquely identify the user). See below:

• On the Key Mapping Tab, select the 'Select Key Mappings' option and add the mapping for 'Email'.

• On the options tab, set the 'Entry Exists' and 'No Entry Exists' options to 'Skip Entry'. The mapping can also be disabled - note that we do not want this mapping to actually migrate data. Remember, its only purpose is to provide the key mapping to map the ID's for existing user records on the source and target servers.

This Reference mapping can now be used in the later Incident Form Mapping to set the caller_id field using a reference mapping. See how to do this below.

Create the Reference Field Mapping

• Create a mapping for the Helpdesk/Incident form/table:

• You will of course need to map many fields here to populate the incident, but we are focussing on mapping the caller_id. This needs to be the sys_id of a User record. We can now use the reference form mapping to obtain this sys_id using the RequestID of the user, given by the Person ID field on the Helpdesk ticket. This will be of type Reference Mapping (see below)
• So in the above, the source field is the field that provides the Person ID of the caller on the source record. The User Reference Key Mapping will be leveraged to map this id to the sys_id of the same user on the target.

At Execution Time Precision Bridge will:

• Use the source field value to obtain the key field (email address) from the CTM:People form
• Use this email address to obtain the record User record on the target form
• Populate the target caller_id field with this sys_id.
• Cache the mapping between the Person ID and caller_id in memory. This means that the next time the same Person ID is seen elsewhere in the migration, PB can use the cache to get the correct sys_id thus avoiding looking it up a second time. This caching can greatly improve performance and is one of the benefits of using a reference mapping.

If a target user with a matching email address is not found, the No Match action is followed (set to NULL in this case)

If more than one user with a matching email address is found, the Multiple Match action is followed (use the first result in this case)

Other Considerations

Do I need to explicitly define a disabled Reference Form Mapping?

In this example, we created a Reference Form Mapping to define the key mappings for source and target records. This mapping was disabled, it does not need to migrate anything. However if we were migrating the User records in the same project, the form mapping that migrates the user records could equally be used as a form reference mapping for a later migration of Helpdesk records if a key mapping has been defined. In fact, this would be extremely efficient, since in migrating the user records PB would already have cached all the id mappings between the source and target user records for use later on.

Do I have to use simple mappings for key mapped fields?

In this example we used a simple mapping to map the email address. However, we could have used any other mapping type instead, as long as the target fields in the key mapping uniquely identify the target records. It is advised however to keep the mappings as simple as possible since the use of lookup and other reference mappings in key mappings can reduce performance.

Should I always disable the Reference Form Mapping?

Sometimes it might be necessary, or more efficient in terms of performance, to enable the reference form 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 source table is small and the number of source records being migrated is large. (eg 100 source users, 100,000 source incidents)
• The key mapping for the referenced table is complex, for example involving reference mappings, temporary variables in an assignment expression or lookups. If the mapping is too complex, Precision Bridge may not be able to calculate the reference mappings 'on the fly'. You will recieve a warning if this is the case.

In thiese cases, 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.

All the source records will be processed, mappings to existing target records calculated and cached but no records wil actually be created or updated on the target, all will be skipped.

Related Articles

To find out more about how to best use reference mappings in your specfic use case, please read the articles below:

Creating a Reference Form Mapping (Legacy->ServiceNow)

Creating a Reference Form Mapping (ServiceNow-ServiceNow)

Creating a Reference Field Mapping for Legacy-ServiceNow migrations

Creating a Reference Field Mapping for ServiceNow-ServiceNow migrations

Configuring Reference Mappings to Optimise Performance