Transform maps define how data flows from staging tables into your target ServiceNow tables after import. You'll configure field mappings, coalesce settings for record matching, and any custom transformation logic needed to clean or manipulate data during the import process.
What transform maps replace
Before transform maps, importing data meant writing custom scripts to parse files and manually insert records into ServiceNow tables. IT teams spent hours writing one-off migration code, and business users had no clean way to regularly import data from external systems. Data imports were brittle, hard to troubleshoot, and required developer intervention every time. Transform maps let you define reusable mapping logic that handles the heavy lifting — field mapping, data transformation, and record matching — without custom code for each import.
How transform maps work
A transform map sits between a staging table (where raw import data lands) and your target table (like incident or user). You define which staging fields map to which target fields, set coalesce conditions to match existing records instead of creating duplicates, and write transformation scripts when the data needs cleaning or calculation. The map processes each staging row individually, running your script with access to both source and target record data. Start with auto-mapping for obvious field matches, then add coalesce fields for your key identifiers (like email for users, number for incidents), and finally add transformation logic for complex data manipulation.
Making transform maps production-ready
Basic transform maps get data flowing, but production-quality maps handle edge cases and performance. Add robust error handling in your transformation scripts to catch bad data without killing the entire import. Use multiple coalesce fields to improve record matching accuracy — email and employee_id for users, for example. Set up field maps for audit fields like updated_by so you can track what came from imports versus manual changes. For high-volume imports, optimize your transformation scripts by avoiding GlideRecord queries inside loops and caching lookup data.
Before you start
- •import_transformer role or admin role
- •Staging table with data ready for transformation
Sourdough: ServiceNow Monitoring and Analytics
A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.
Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.
Step by step
Create the transform map record
Navigate to System Import Sets > Administration > Transform Maps and click New. Enter a descriptive Name that includes both source and target (like 'HR User Import to sys_user'). Set the Source table to your staging table and Target table to the ServiceNow table you're importing into. Leave Run business rules unchecked initially — you can enable this later once the basic mapping works.
Use a naming convention that includes the data source so you can easily identify maps later.
Configure auto-mapping
Click Auto Map Matching Fields to automatically create field maps where staging and target field names match exactly. ServiceNow will create field map records for obvious matches like 'email' to 'email' or 'first_name' to 'first_name'. Review the created field maps in the Field Maps related list and delete any that mapped incorrectly — auto-mapping sometimes creates unwanted maps for system fields.
Set up coalesce fields
In the Coalesce section, check Use coalesce and add the fields that uniquely identify records in your target table. For user imports, typically use email or employee_id. For CI imports, use name or serial_number. Add multiple coalesce fields for better matching accuracy — if email is blank, ServiceNow will try the next field. This prevents creating duplicate records when importing updates to existing data.
Always test coalesce logic with a small data set first — incorrect coalesce fields can overwrite wrong records.
Add manual field mappings
In the Field Maps related list, click New to create mappings for fields that didn't auto-map. Set the Source field to the staging table column and Target field to the ServiceNow field. For reference fields, you can map directly if the staging data contains sys_ids, or use Choice action of 'create' to create new reference records on the fly. For fields that need no transformation, leave the Use source script checkbox unchecked.
Configure transformation scripts
For field maps that need data manipulation, check Use source script and write JavaScript in the Source script field. The 'source' variable gives you access to staging table fields (like source.u_employee_id), and you return the transformed value. Common transformations include date format conversion, string concatenation, or lookup logic. Keep scripts simple and add error handling for malformed data.
Set the run order
Back on the main transform map record, set the Order field to control when this map runs relative to others. Use 100 as your starting number so you can insert maps before or after later. If this map depends on reference data from another import (like importing incidents that reference users), make sure the user import map has a lower order number.
Test the transformation
Save the transform map and navigate to your staging table with import data. Select one or more staging records and run Transform Now from the context menu. Check the target table to verify records were created or updated correctly. Review any transform log entries for errors. Fix any mapping issues and retest before running the full transformation.
Best practices
Always set coalesce fields even for initial data loads — you'll likely need to import updates later and want to avoid duplicates.
Don't use GlideRecord queries inside transformation scripts for high-volume imports — cache lookup data in a single query before processing rows.
Test transformation scripts with malformed data like null values, extra spaces, and invalid dates — staging data is often dirty.
Keep the 'Run business rules' checkbox unchecked during initial testing — business rules can slow down large imports and create unexpected side effects.
Use descriptive field map names when creating manual mappings — 'Employee ID to User ID' is clearer than 'Field Map 1' six months later.
Test Your Knowledge
Quick 3-question quiz — see how your ServiceNow skills stack up.
A list view on a table with millions of records is slow. Best fix?
Select an answer to continue