Transform Maps & Field Maps

Section 1

What Is a Transform Map?

A Transform Map defines how each row in a staging table becomes a record in a target table. It is the bridge between "what arrived" and "what ServiceNow stores." Without a Transform Map, staging data just sits in the staging table indefinitely — nothing moves to the target table.

A Transform Map has three parts:

Header — which staging table is the source and which table is the target
Field Maps — column-by-column mapping from source to target
Scripts — JavaScript hooks that run at specific points during the transform

📘

Core Concept — One Transform Map, Many Runs A Transform Map is a reusable definition, not a one-time thing. Every time new data lands in the staging table, the same Transform Map processes it. You configure the Transform Map once, and it runs for every import load — scheduled or manual. This is why getting the Transform Map right is so important: errors will repeat for every future load.

Creating a Transform Map

Navigate to System Import Sets → Transform Maps → New. Fill in:

Name — descriptive label for this transform
Source table — the Import Set staging table
Target table — where records should go (e.g., incident, cmdb_ci_server)
Run business rules — whether target table's Business Rules fire during import (usually yes)
Copy empty fields — whether a blank staging field overwrites an existing target value

Section 2

Field Maps — Column to Field Mapping

Each Field Map entry maps one column in the staging table to one field in the target table. You create these in the Field Maps related list on the Transform Map record. For each field map, you specify:

Source field — the column name in the staging table
Target field — the field on the target table to populate
Coalesce — whether this field should be used to detect duplicates (discussed in Section 3)
Transform script — optional JavaScript to transform the source value before writing it to the target

Field-Level Transform Scripts

Sometimes the source value is not in the right format for the target field. A field-level transform script lets you manipulate the value inline. For example, the source CSV has dates in "MM/DD/YYYY" format but ServiceNow expects "YYYY-MM-DD". Your transform script:

// source_field is the incoming raw value
var parts = source_field.split('/');
answer = parts[2] + '-' + parts[0] + '-' + parts[1];

The variable source_field holds the incoming value. You set answer to the transformed value that will be written to the target field.

💡

Tip — Auto Map Matching When you save a new Transform Map, ServiceNow offers "Auto Map Matching Fields." This scans the staging table columns and tries to find target table fields with the same name and creates Field Maps automatically. It's a time-saver for well-named source data, but always review the auto-generated maps — column names in CSV files are often different from ServiceNow field names.

Section 3

Coalesce — Duplicate Detection and Update Logic

Coalesce is the mechanism that prevents duplicates during imports. When the Transform Map processes a staging row, it first checks: does a record already exist in the target table with these same "coalesce field" values? If yes, update that record. If no, create a new one.

Without coalesce configured, every import run always inserts new records — even if the same person, CI, or item was already imported in a previous run. With coalesce, you define which field(s) uniquely identify a record (like an employee ID, asset tag, or serial number) and ServiceNow uses those to decide insert vs. update.

💡

Analogy — Checking the Guest List Coalesce is like a bouncer at a venue who checks the guest list. When someone arrives, the bouncer asks "Are you already on the list?" If yes, they update your status ("arrived"). If not, they add you as a new guest. Without the bouncer checking, every arrival creates a new entry and the list fills up with duplicates.

Coalesce Field Selection Strategy

The coalesce field must be a value that is:

Unique — no two records should have the same value for this field
Stable — the value doesn't change over time (a serial number, not a person's name)
Present in source data — the source system must reliably provide it

Common coalesce fields: employee number, asset tag, serial number, hostname, email address. Bad coalesce fields: name (not unique), description (not stable or unique).

⚠

Exam Trap — Multiple Coalesce Fields You can mark more than one field as "Coalesce" on a Transform Map. When multiple fields are coalesced, ServiceNow looks for a record where ALL coalesced fields match — it's an AND condition, not OR. This is useful when no single field is unique but a combination is. Example: first name + last name + department together identify a person even though none of the three alone is unique.

Section 4

Transform Script Hooks — Full Lifecycle

Transform Maps have six script hooks that run at different points during the transform. These are server-side JavaScript scripts that give you complete control over the import process.

Script Hook	When It Runs	Use Case
onStart	Once before any row is processed	Initialize global variables, log start of import, validate data source availability
onBefore	Before each row is transformed	Validate the row, skip rows that don't meet criteria, set `ignore = true` to skip
onAfter	After each row is transformed (after insert/update)	Create related records, trigger workflows, log per-row results
onComplete	Once after ALL rows are processed	Send summary email, update import log record, clean up temp data
onForeignInsert	When a reference field value is not found in the target table	Create the missing reference record rather than failing
onReject	When a row is rejected due to an error	Log rejected rows, create error notification, store rejected data for review

The onBefore Script — Row Skipping

The onBefore script is the most commonly used hook. To skip a row entirely, set ignore = true in the onBefore script. To force a row to be inserted even if coalesce would update, set action = INSERT. To force an update, set action = UPDATE.

⚠

Exam Trap — Script Hook Execution Order The order is always: onStart (once) → [for each row: onBefore → field maps → onAfter] → onComplete (once). onReject fires instead of onAfter when a row fails. onForeignInsert fires during field mapping when a reference lookup fails. Exam questions often present scenarios and ask which hook fires.

Section 5

Transform Map for CMDB Data

When importing CI data, the Transform Map has an additional concern: should it write directly to the target CI table, or feed through the IRE? As covered in Topic 1, writing directly bypasses IRE — usually a mistake for CMDB data.

For CMDB imports where you need IRE processing, the Transform Map's target is not a CI table directly — it is the CMDB Identification and Reconciliation API. Service Graph Connectors handle this automatically. For custom Import Sets targeting CMDB, you use the onAfter script to call SNC.CMDBTransformUtil or the CMDB API endpoint rather than relying on direct table mapping.

💡

Tip — Test with a Small Sample First Before running a large import, always test your Transform Map with a sample of 10-20 rows (create a small test Import Set). Verify the insert/update/ignored counts are what you expect, check that coalesce is matching the right records, and review any error rows. A bug in a Transform Map running against 50,000 rows creates a much larger cleanup problem than one caught on 20 rows.

Exam Quick Reference

Common Exam Traps — Transform Maps

Transform Maps run AFTER staging — they are the logic engine that moves data from staging to target
Coalesce fields define duplicate detection — without them, every run inserts new records
Multiple coalesce fields use AND logic — all must match for an update
Good coalesce fields: unique, stable, always present. Bad: name, description, free-text fields
Script hook order: onStart → (per row: onBefore → fieldmaps → onAfter) → onComplete
ignore = true in onBefore skips the current row without error
onForeignInsert fires when a reference lookup fails — use it to create missing reference records
For CMDB data, direct Transform Map inserts to CI tables bypass IRE — use Service Graph Connectors instead

Exam Checkpoint

Practice Questions

4 questions · Select an answer to see the explanation immediately.

Transform Maps Quiz 1 / 4

A Transform Map runs daily, but every execution inserts new records instead of updating existing ones. What is the most likely cause?

💡 Explanation

B is correct. Coalesce fields define the duplicate detection logic. Without a coalesce field, the Transform Map cannot determine if a record already exists, so it inserts every row as new. The fix is to configure a coalesce field with a unique, stable identifier. A would cause errors, not duplicate inserts. C and D are unrelated to this behavior.