sys_transform_map Table

Table Reference/sys_transform_map

The `sys_transform_map` table defines how data flows from import set tables to target tables during data integration. Owned by the Integration module, each record represents a complete transformation configuration that maps source columns to destination fields with optional transformation scripts.

What This Table Is

The sys_transform_map table stores the configuration for Import Set transformations, acting as the bridge between raw imported data and ServiceNow's structured tables. Each record defines how data from a specific import set table should be mapped, transformed, and inserted into a target table like incident or cmdb_ci_server. This is the master configuration that orchestrates the entire data transformation process.

Transform Maps belong to the Integration module and support ServiceNow's ETL (Extract, Transform, Load) process end-to-end. The workflow starts with importing raw data into an import set table, then applying the transformation rules defined in this table to create or update records in the target table. Each transform map contains field mapping rules (sys_transform_entry), transformation scripts, and error handling configurations.

This table doesn't extend any parent table but serves as the parent configuration for sys_transform_entry records (individual field mappings) and sys_transform_history records (execution logs). The relationship is hierarchical: one transform map has many field mappings and generates multiple execution history records over time.

In large enterprises, this table typically contains 50-500 transform map records, with each map processing thousands to millions of import records over time. Performance is generally good since transform maps themselves are just configuration metadata. However, the transformation scripts within these maps can become performance bottlenecks when processing large import sets, especially if they contain complex lookups or create multiple related records.

When You'll Script Against This Table

You'll typically script against sys_transform_map in Script Includes that manage data integration workflows, Business Rules that trigger transformations based on import set status changes, and Scheduled Scripts that run periodic data imports. Integration administrators and developers with the import_transformer role can read and modify transform maps, while the import_admin role has full control.

Most scripting occurs in Transform Scripts (onStart, onBefore, onAfter, onComplete) that are stored as fields within the transform map record itself. These scripts execute in the global scope and have access to special variables like source (import set record), target (destination record), and import_set (import set header record).

Common scripting patterns:

Programmatically trigger transform map execution using TransformUtil.transformAllMaps() or TransformUtil.runTransform()
Query transform maps to build dynamic integration dashboards showing success rates and error counts
Create or clone transform maps programmatically when building integration configuration UIs
Modify transform map settings based on data source characteristics or business rules
Implement custom error handling by querying failed transform attempts and retry logic
Build integration monitoring alerts by checking transform map execution status and timing
Export and import transform map configurations between instances for deployment automation

Table Gotchas

⚠️

Transform maps with run_business_rules=true can cause unexpected cascading effects. Business Rules on the target table will execute for every transformed record, potentially triggering notifications, workflows, or additional data changes you didn't anticipate.

⚠️

The coalesce_empty_fields setting is counter-intuitive. When true, it treats empty strings as NULL for coalescing purposes, but when false, empty strings are treated as actual values that can block updates to existing records.

The source_table field only accepts tables that start with 'u_' (import set tables). Attempting to set it to a regular table will fail silently during transformation
Transform scripts execute in a specific order: onStart → field mappings → onBefore → record insert/update → onAfter → onComplete. Modifying the target record in onAfter won't trigger another update

⚠️

Performance degrades exponentially with complex onBefore/onAfter scripts that do database lookups. Each script runs once per source record, so a script with 5 GlideRecord queries processing 10,000 import records executes 50,000 database queries.

The active field controls whether the transform map executes, but deactivated maps still appear in transform lists and can cause confusion. Always check active=true when querying for operational transforms
Cloning transform maps via GlideRecord.insert() doesn't copy the associated sys_transform_entry records. Use the Transform Map API or manually clone the field mappings

Free Newsletter

Enjoying this? Get one deep-dive per week.

Join 1,000+ ServiceNow pros — scripts, GlideRecord patterns, Flow Designer techniques, and career moves. Free.

The sys_transform_entry table stores individual field mappings for each transform map, creating a one-to-many relationship where each transform map has multiple field transformation rules. You'll frequently join these tables when building or analyzing transformation logic. The sys_import_set table tracks import execution batches and links to transform maps through the transform_map reference field.

The sys_transform_history table logs every transformation attempt, success, and failure, making it essential for monitoring and debugging integration issues. You'll also commonly query the actual import set tables (prefixed with 'u_') that serve as the data source, and the target tables (like incident, cmdb_ci, or sys_user) where the transformed data ultimately lands. This creates a data flow chain that developers must understand to troubleshoot integration problems effectively.

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Key Fields

Column	Type	Label	Notes
name	string	Name	Display name of the transform map. Must be unique within the instance and commonly follows naming patterns like 'Import User Data from LDAP'.
source_table	string	Source table	Name of the import set table (must start with 'u_'). This is the staging table where raw data lands before transformation.
target_table	string	Target table	ServiceNow table where transformed records will be created or updated. Can be any valid table name like 'incident' or 'cmdb_ci_server'.
active	boolean	Active	Controls whether this transform map executes during import processing. Inactive maps are skipped but remain visible in the UI.
run_business_rules	boolean	Run business rules	When true, Business Rules on the target table execute for each transformed record. Can significantly impact performance and cause unexpected side effects.
coalesce_empty_fields	boolean	Coalesce empty fields	Determines how empty strings are handled during coalescing. When true, empty strings are treated as NULL for matching purposes.
update_existing	boolean	Update existing records	Controls whether transformation can update existing records or only create new ones. Requires coalesce fields to be defined for updates.
on_start	script	On Start Script	JavaScript that executes once at the beginning of the transform process, before any individual records are processed.
on_before	script	On Before Script	JavaScript that executes for each source record before the target record is created/updated. Has access to 'source' and 'target' variables.
on_after	script	On After Script	JavaScript that executes for each source record after the target record is saved. Useful for creating related records or logging.
on_complete	script	On Complete Script	JavaScript that executes once after all records in the import set have been processed, regardless of success or failure.
audit_table	string	Audit table	Optional table name for storing transformation audit records. Rarely used but allows custom logging of transform activities.
description	string	Description	Free-text description of the transform map's purpose and any special handling notes. Critical for documentation in complex integrations.
script	script	Script	Legacy script field that executes during transformation. Deprecated in favor of the specific on_start, on_before, on_after event scripts.

Common Queries

Get all active transform maps

// Most basic query - find transform maps ready for execution
var gr = new GlideRecord('sys_transform_map');
gr.addQuery('active', true);
gr.query();

while (gr.next()) {
    gs.info('Active transform map: ' + gr.name + ' (' + gr.source_table + ' -> ' + gr.target_table + ')');
}

// Returns only maps that will actually execute during import processing

Find transform maps by source and target table combination

// Real-world scenario: locate transform for specific data flow
var gr = new GlideRecord('sys_transform_map');
gr.addQuery('active', true);
gr.addQuery('source_table', 'u_employee_import');
gr.addQuery('target_table', 'sys_user');
gr.query();

if (gr.next()) {
    gs.info('Found employee transform map: ' + gr.sys_id);
    gs.info('Business rules enabled: ' + gr.run_business_rules);
    gs.info('Updates existing: ' + gr.update_existing);
} else {
    gs.error('No active transform found for employee import');
}

Get transform maps that target incident table for integration monitoring

// Business scenario: audit all integrations feeding into incidents
var gr = new GlideRecord('sys_transform_map');
gr.addQuery('target_table', 'incident');
gr.addQuery('active', true);
gr.orderBy('name');
gr.query();

var incidentIntegrations = [];
while (gr.next()) {
    incidentIntegrations.push({
        name: gr.name.toString(),
        source: gr.source_table.toString(),
        hasBusinessRules: gr.run_business_rules == true
    });
}

gs.info('Found ' + incidentIntegrations.length + ' active incident integrations');

Count transform maps by target table using GlideAggregate

// Performance monitoring: identify tables with most integrations
var ga = new GlideAggregate('sys_transform_map');
ga.addQuery('active', true);
ga.groupBy('target_table');
ga.addAggregate('COUNT');
ga.query();

while (ga.next()) {
    var targetTable = ga.target_table.toString();
    var count = ga.getAggregate('COUNT');
    gs.info('Table ' + targetTable + ' has ' + count + ' active transform maps');
}

// Helps identify heavily integrated tables for capacity planning

Wrong way vs right way to check for transform map existence

// WRONG: This misses inactive maps that might be temporarily disabled
var wrong = new GlideRecord('sys_transform_map');
wrong.addQuery('active', true);
wrong.addQuery('name', 'Employee Import Transform');
if (!wrong.hasNext()) {
    // Incorrectly assumes map doesn't exist
}

// RIGHT: Check existence first, then verify active status
var right = new GlideRecord('sys_transform_map');
right.addQuery('name', 'Employee Import Transform');
right.query();
if (right.hasNext()) {
    gs.info('Transform exists, active: ' + right.active);
} else {
    gs.info('Transform map does not exist');
}

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue

sys_transform_map