ServiceNow Import Sets and Transform Maps: A Practical Guide

Import Sets are how data gets into ServiceNow from external sources — CSV files, database connections, REST feeds, spreadsheets. Done correctly, they are reliable and efficient. Done incorrectly, they create duplicate records and data quality problems that take weeks to clean up. This guide covers the right way.

The Import Process

External Data Source
    → Import Set Table (staging area)
    → Transform Map (mapping + transformation)
    → Target Table (incident, cmdb_ci, etc.)

The Import Set Table is a temporary staging table that holds the raw imported data before transformation. Always review the data in the staging table before running the transform — it is much easier to catch problems here than after they have been written to production tables.

Coalesce Keys — The Most Important Setting

A coalesce key tells ServiceNow how to determine if an incoming record matches an existing one. Without a coalesce key, every import creates new records regardless of whether they already exist.

// Example: Importing user data
// Coalesce on: email (unique per user)
// If email matches existing user → update
// If email not found → create

// Example: Importing CIs
// Coalesce on: serial_number
// If serial_number matches existing CI → update
// If serial_number not found → create CI

Choosing the right coalesce key is the most important decision in any import configuration. The key must be:

• Unique in the source data
• Stable — it should not change between imports
• Present on all records — null coalesce keys always create new records

Transform Scripts

Transform Map field mappings handle simple value transfers. Transform Scripts handle everything else — data cleaning, conditional logic, lookups, and record relationships.

// onBefore script: runs before each record transforms
// Use to: skip invalid records, set defaults

// Skip records with no email address
if (!source.email) {
    ignore = true;
    return;
}

// Clean phone number format
source.phone = source.phone
    .replace(/[^0-9+]/g, '');

// onAfter script: runs after each record transforms
// Use to: create related records, trigger workflows

// Create a task after each user is created
if (action === 'insert') {
    var task = new GlideRecord('task');
    task.short_description = 'Welcome ' + target.first_name;
    task.assigned_to = target.sys_id;
    task.insert();
}

Reference Field Mapping

Mapping reference fields (like assigned_to which points to sys_user) requires telling ServiceNow how to look up the referenced record. Use the Reference qualifier in the field map:

• Source field: assigned_to_email
• Target field: assigned_to
• Reference qualifier: email (look up user by email)

If the reference lookup fails (user not found), the field is left blank unless you handle it in a transform script.

Large Volume Imports

Importing more than 10,000 records has performance implications you need to plan for:

• Use scheduled imports during off-peak hours — large imports consume significant database resources
• Chunk large files into batches of 5,000-10,000 records
• Disable business rules during the import using the Run business rules option if the rules are not needed for the import data
• Monitor the Import Set queue — imports queue behind each other and a large import blocks subsequent ones

Testing Your Transform

1. Load a small test file (10-20 records) that covers all your edge cases
2. Run the transform
3. Check the Transform History for errors and warnings
4. Verify the records in the target table — check both the values and the reference fields
5. Run the same file again — verify that it updates rather than creates duplicates (coalesce working correctly)

Common Import Failures

• All records inserted as new — coalesce key is wrong or not configured
• Reference fields blank — the lookup field doesn't match any existing records
• Transform script errors — check the Transform History log for line numbers
• Import hangs — check system logs for timeout errors, reduce batch size