How to Use References for Transform Maps in ServiceNow

Transform maps in ServiceNow provide a robust mechanism for importing, transforming, and mapping data between source and target tables. When working with transform maps, effectively managing references—whether for related records, choice fields, or cascading data transformations—is a key factor for success. This article explores how to use references in transform maps, outlines the available tools and techniques, and highlights use cases to illustrate practical applications.

Understanding References in Transform Maps

References allow you to associate fields in the source table with fields in the target table that point to related records. These relationships are critical for ensuring data integrity and maintaining logical associations across your ServiceNow instance. Using transform map scripts, you can dynamically manage references during the import process.

Types of Reference Handling in Transform Maps

1. Direct Reference Mapping

For simple reference fields (e.g., Assigned to or Location), you can directly map the source field to the target reference field. The platform will automatically resolve the reference if the display value matches a record in the target table.

Use Case: Importing user data where the Manager field is a reference to another user in the sys_user table.

2. Reference with Choice Action: Create

If the source data contains a reference to a record that does not yet exist in the target table, you can configure the field map to create a new referenced record. This is useful for ensuring no data is dropped due to missing references.

Use Case: Importing incident data where the Category field includes new categories that do not yet exist in the incident_category table.

3. Reference with onForeignInsert Script

An onForeignInsert script runs when a new referenced record is about to be created. This allows you to modify or validate the data being inserted into the referenced table.

Example Script:

if (source.manager_email) {

    var user = new GlideRecord('sys_user');

    user.addQuery('email', source.manager_email);

    user.query();

    if (user.next()) {

        target.manager = user.sys_id;

    } else {

        // Create a new user or log an error

    }

}

Use Case: Importing organizational data where managers are referenced by email but may not yet exist in the sys_user table.

4. Dynamic Reference Resolution

You can use a Field Level Source Script or Record Level Script to dynamically resolve references based on source data. This is helpful when the source data doesn’t match the target display value but includes sufficient information to resolve the reference.

Example Script: Resolving a location reference based on a custom mapping.

var locationMap = {

    'HQ': 'New York Office',

    'SF': 'San Francisco Office'

};

target.location = locationMap[source.location_code] || 'Default Location';

Use Case: Importing data with custom location codes.

5. Reference Rejection

Use the onReject script to handle invalid references gracefully. For example, log the invalid reference for review or send a notification.

Use Case: Logging a missing department reference during employee data import.

Tips for Managing References

1. Validate Data in Advance

   1. Ensure that reference fields in the source data are clean and align with the target system's naming conventions or IDs.

2. Leverage Lookup Tables

   1. Use lookup tables to map non-standard source values to corresponding target values dynamically.

3. Debug with Logs

   1. Use log.info() or log.error() to debug transform map scripts, especially when resolving references dynamically.

4. Utilize Import Set Fields

5. Add temporary fields to the import set table to store intermediate results or custom mappings during the transformation.

Practical Use Cases

1. Importing Employee Data

Scenario: You’re importing a list of employees from an external HR system. Each employee references a Manager, but some managers do not yet exist in the target system.

Solution: Use onForeignInsert to create missing manager records dynamically.

2. Cascading Transformations for Related Data

Scenario: Importing project data where each project references multiple tasks, and tasks reference team members.

Solution: Set up separate transform maps for projects and tasks. Use onAfter scripts to associate tasks with projects and dynamically resolve team member references.

3. Synchronizing Configuration Items

Scenario: Importing hardware assets where some Assigned to references do not exist in the sys_user table.

Solution: Use a Record Level Script to log missing users and assign assets to a default user until the missing records are addressed.

Conclusion

References are a cornerstone of effective data transformation in ServiceNow. Whether creating new referenced records, resolving dynamic mappings, or handling invalid data, transform map scripts provide the flexibility to customize the behavior to meet your needs. By leveraging the right tools and techniques, you can ensure seamless data imports and maintain data integrity across your platform.