Creating an ID Replacement Field Mapping

Scope: ServiceNow -> ServiceNow migrations

ID Replacement Mappings can be used for ServiceNow to ServiceNow migrations when the source value contains one or more references to records in other tables using the SysID.  During execution, Precision Bridge searches the target instance for the corresponding records and replaces the SysID values with the corresponding SysIDs on the target so that the expression remains valid.

For example the source string could be an encoded query expression like this:

assignment_group=1fcde0abdba1d3005b32f2f5ab961902^state=2^assigned_to=56826bf03710200044e0bfc8bcbe5dca^EQ

Here the ID values represent a group, state and user on the source instance.  The ID Replacement mapping will convert these to the corresponding IDs on the target instance.

The source field can be

a) a single SysID value

b) a list of SysID values or

c) a conditional expression that includes one or more SysID values.

d) an embedded attachment id, as used in HTML values where an image is to be displayed. For example in a Knowledge Article.

The source value can either be another ServiceNow field or a temporary variable of type string.

If you specify the Source Type to be ‘Source Field’, then you must select the source field from the drop down list.  Similarly if you specify the Source Type to be Temporary Variable, you must select the variable name from the drop-down list.

When searching for the corresponding values on the target instance, you can control the behaviour when no match is found by specifying the No Match Action.  This can be set to either ‘Use Source’ (replace with the source value), ‘Set Null’, ‘Skip Record’ or ‘Log Error’.   

Similarly if multiple matches are found, you can control the behaviour by specifying the Multiple Match Action. This can be set to ‘Use Source’, ‘Use First’ (use the first record returned), ‘Set Null’, ‘Skip Record’ or ‘Log Error’.

Next, you need to specify whether to include a single/List of ID values or to include ID’s from an encoded query string expression or both.

If you specify a Single/List of ID values then you must also provide the name of the source and target reference tables that the ID value(s) relate to using the Single and List Replacement tab:

If you specify, ‘Include IDs from Encoded Query Strings’ then you must also specify the source and target tables from which the fields in the query string originate using the Encoded Query Replacement tab:

In this case, you can either select the table names explicitly from the drop-down lists or select ‘Source Table from Field Mapping’ and select the field mapping that holds the name of the referenced table in each case.

If you specify 'Include Embedded Attachments' then you must also specify a mapping that will provide the sys_id of the target record. This implies that the target record must already exist (and this form mapping will be updating it)

Notes on use of the ID Replacement mapping

1. When replacing SysIds using this field mapping, the SysIDs are normally matched using the field display values. If two records on the target have the same display value, the multi-match option is applied. The exception to this is when the SysIDs reference the User table.  In this case the UserID field is used to match instead.
2. For Multi-Match or No-Match options the 'Use Source', 'Set NULL' or 'Use First' selections will generate a warning for the target record which can be viewed in the migration report, if configured.
3. When replacing references to embedded attachments, the target record and the attachments must already exist on the target server. It may however, be created in a form mapping that executes before the current one.
4. The ID Replacement mapping cannot currently convert expressions that include ‘dot-walking’ references to other tables. For example:

 assignment_group=1fcde0abdba1d3005b32f2f5ab961902^state=2^assigned_to=56826bf03710200044e0bfc8bcbe5dca^closed_by.cost_center=5bc4b4c2db775300a03460535b961976^EQ

In this case, the source field closed_by.cost_center will not be recognized as it is not on the current table, leading to its value remaining unchanged in the transformed string. In this case, a warning would be shown in the migration report.