ServiceNow Transform Map Explained

What Is a Transform Map?

A transform map in ServiceNow is a configuration that converts data from a source format into ServiceNow table structures during import or integration. When you bring data from an external system—an HR application, a legacy ticketing system, a CSV file, an API—that data has its own field names, data types, and structures. ServiceNow uses a different structure. A transform map bridges that gap: it reads source data, applies rules to clean and reshape it, and loads it into the correct ServiceNow tables.

Transform maps are stored in the Import Set Transforms table (sys_import_set_transform). They are part of the data import framework alongside Import Sets (which hold raw imported data) and Table Maps (which define the target table and field mappings). When you import data, the transform map executes automatically, applying your configured transformations before the data lands in production tables.

How Transform Maps Process Data

The typical flow is: source system sends data, an import set table receives that raw data unchanged, then a transform map processes each row. The transform map can perform several operations on each row. It can map source fields to target fields—source_email becomes user_email. It can apply logic—if source_status is “archived”, set the ServiceNow status to “inactive”. It can look up related records—if the source says “department: sales”, find the sales department in ServiceNow and populate the department foreign key.

Transform maps execute row-by-row and can be set to run automatically after import or manually on demand. As the transform map processes rows, successful transformations go into the target table. Failed transformations typically go into an error table so your team can diagnose and retry them. Most organisations review import results closely for the first few imports, then automate once they trust the logic.

Key Configuration Options

When you create a transform map, you specify the import set table (source), the target table (where data goes), and field mappings. For each source field, you map it to a target field or skip it. Mappings can be simple—copy the value as-is—or complex—apply a script that transforms the value based on conditions.

Transform maps include a coalesce setting: if a source record should update an existing record rather than create a new one, the coalesce field determines the match key. For example, if you are importing employee records and want to update existing employees rather than create duplicates, coalesce on employee_id. The transform map looks for an existing record with that ID, updates it, and skips the creation.

You can also configure transform map scripts—code that runs before or after the main transformation. Pre-transformation scripts prepare data; post-transformation scripts clean up or create related records. These scripts give you power but require care: a script error can break the entire import.

Common Use Cases and Scenarios

Regular data syncs from external systems use transform maps. HR systems export employee records nightly, ServiceNow imports them, and a transform map updates ServiceNow’s employee CMDB. When you migrate from a legacy system, you export that system’s data, import it into a staging table, and use a transform map to load it into ServiceNow’s production tables. When you integrate two systems via API, the API response data might go into an import set table, then a transform map processes it into ServiceNow records.

Common Misunderstandings and Pitfalls

Transform maps are not data loading—they are data transformation. The import set table holds raw source data; the transform map is the logic that processes it. If your import set has bad data, the transform map cannot fix it. Garbage in, garbage out applies here. Always validate source data quality before or during import.

A transform map’s onBefore script can set ignore to true, which skips the current row. This is powerful but easily misused. A script that skips rows based on a condition can silently lose data if the condition is wrong. Test thoroughly and log skipped rows so you notice when data goes missing.

Performance issues with large imports often stem from inefficient transform maps. A script that queries the database for every row being transformed can make an import of one million records extremely slow. Optimise scripts to batch operations or use coalesce efficiently instead of individual lookups.

Related Concepts

Import Sets hold raw imported data. Data Import performs the mechanical task of reading source data and populating import sets. Service Now provides built-in connectors for common systems (HR, finance, directory) that automate import set population. Orchestration can schedule and automate data imports. Integration Hub can trigger imports based on external events.

Designing a recurring feed before the first row arrives

A transform map that will run every night is a contract with the feed’s owner. Before you build it, agree on the business key that identifies a record across runs, what happens when that key is missing, and whether the source sends full extracts or only changes. Those three decisions set the coalesce configuration, the rejection rules and the reconciliation you need. Making them after the first load often means rebuilding the map. The data migration and import sets guide sets out the wider pipeline this map sits in.

Ask the source owner a few specific questions. Does a deleted record disappear from the extract or arrive with a flag? Can the same key appear twice in one file? Which fields change format between regions or between exports? A transform map can handle each of these, but only if the team knows which case it is in before the schedule is switched on.

Matching the import setup to the kind of feed

Feed pattern	Typical key approach	What to check first
Full extract of a master list	Coalesce on the source system’s stable identifier	Records absent from the extract: retired on purpose, or missing by mistake?
Incremental file of changed rows only	Coalesce on the identifier, with the source timestamp kept on the target	Whether a late-arriving older file can overwrite a newer value after a reprocess
One-off migration from a legacy system	Often a composite key built from two source fields	Duplicate keys in the source, which the legacy system may have allowed
Event-style records from an API	Event or transaction identifier, not the business entity	Replays: the same event delivered twice must not create two records

Treat the grid above as a prompt for discussion, not a checklist. Its job is to force the key decision before the map is written, because a coalesce on the wrong field produces records that look correct and hang off the wrong parent. The import sets and transform map design article covers the design choices in more depth.

Reprocessing a failed run without doubling the data

Many import incidents come from a rerun. An operator sees a partial failure, runs the transform again, and discovers that rows already loaded were updated twice or that a post-transformation script created related records a second time. Use a fixed order whenever you reprocess:

1. Identify the import set run and count its rows: how many reached the target table, how many were rejected, and how many are still in error.
2. Read the error for the first rejected row only. Many later errors are the same fault repeated.
3. Correct the cause in the source file or the transform script, and record the change in the same change set so the fix is traceable.
4. Reprocess a copy of the failed rows into a test table or a staging instance first, and compare the result with the production target.
5. Run the production reprocess only once the counts reconcile: rows received, rows created, rows updated, rows skipped and rows still in error must add back to the total.

Reconciliation is a step teams often skip, and the migration reconciliation controls article covers the checks worth keeping for each run.

Scripts that skip rows and the audit trail behind them

Skipping rows is sometimes necessary, for example when a source row is a header repeated in the middle of a file. The risk is a condition wider than intended, which quietly removes valid records. Give every skip a reason code written to a log table, and include skipped rows in the reconciliation for each run. A skip count that climbs from one run to the next can signal that the source has changed, even when nothing has failed.

Keep pre- and post-transformation scripts small and named for their purpose. A script that does several unrelated things is hard to review after a schema change, and it becomes the place where one new column breaks every import at once. Splitting the logic into a clear sequence also makes it possible to test each piece against a sample file.

When a transform map is the wrong tool

A transform map suits data that arrives in batches and has to be reshaped the same way each time. It is a poor fit for a one-time correction to a limited set of records already in production. A scripted background job with a reviewed query and a recorded before-and-after state is easier to audit for that. It is also the wrong place for business decisions that change often, such as which cost center a region maps to. Hold those in reference data the business can maintain, and let the transform read from it. Any data-cleanup work that needs a wider plan is better handled as its own project.

Questions data owners ask about transform maps

Why did the same file produce different results on two days?

The source often changed without notice: a field was reordered, a code list was extended, or a date format shifted between exports. Compare the header and a sample of values against the previous file before you look at the map.

Should rejected rows be fixed by hand in the target table?

Avoid it. A hand edit either gets overwritten by the next run or conflicts with it. Correct the source or the mapping and reprocess, so the target stays a reproducible result.

How much should the team test before a schema change?

Test every map that reads the changed table, not only the one you edited. A new mandatory field on the target can break a map that never touched it, through a shared reference or a downstream script.

Who owns a mapping after the project that built it has closed?

Name an owner in the map’s description and in the feed register. Without one, the first person to notice a bad load has to work out who can approve a fix.

Next step

A feed that loads correctly once but has no reconciliation or reprocessing routine is a risk waiting for its next bad file.