What is a Transform Map?
A Transform Map is used to map data from an import set table to a target table in ServiceNow. It defines how data should be transformed and inserted/updated in the destination table.
Transform Map Scripts
Script | Execution | Purpose | Example |
onStart | Once (beginning) | Initialize variables | var recordCount = 0; |
onBefore | Per record (before mapping) | Pre-process, skip records | if (source.u_status == 'inactive') ignore = true; |
onAfter | Per record (after mapping) | Post-process target | target.assigned_to = gs.getUserID(); |
onComplete | Once (end) | Finalize, notify | gs.info('Total: ' + recordCount); |
Order of Execution
┌─────────────────────────────────────────────────────────────┐
│ STEP 1: onStart Script (Runs Once)
│ • Initialize variables, set up preconditions
└─────────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────┐
│ FOR EACH IMPORT SET ROW (Loop)
└───────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 2: Find Target Record
│ • Evaluate all coalesce field maps/scripts
│ • Determine if UPDATE or INSERT
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 3: onBefore Script
│ • Validate/manipulate data before transformation
│ • Can set ignore = true to skip record
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 4: Transform All Field Mappings
│ • Process direct field-to-field mappings
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 5: Run Script (Field Maps)
│ • Execute custom scripts where "Run Script" is checked
│ • Complex transformations via answer variable
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 6: onAfter Script
│ • Access target record after transformation
│ • Update related records, send notifications
│ • Data already transformed and inserted
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────┐
│ INSERT / UPDATE
│ Target Record
└─────────────────┘
↓
┌───────────────────────────────────────┐
│ REPEAT STEPS 2-6 FOR NEXT ROW
└───────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 7: onComplete Script (Runs Once)
│ • All rows processed
│ • Send final notifications, log statistics
└─────────────────────────────────────────────────────────────┘
Script Variables
Variable | Available In | Purpose |
source | onBefore, onAfter, Field Maps | Current import set record |
target | onAfter, Field Maps | Current target table record |
ignore | onBefore | Set to true to skip record |
answer | Field Map Scripts | Value to set in target field |
action | onBefore, onAfter | Action being performed (insert/update) |
Coalesce Fields
Type | Behavior | Use Case |
No Coalesce | Always INSERT | Always create new records |
Single Coalesce | Match on 1 field | Unique identifier (email, employee_id) |
Multiple Coalesce | Match on multiple fields (AND) | Combination creates uniqueness (first_name + last_name + dept) |
Run Script (Field Mapping)
Enables custom JavaScript for field transformation. The answer variable sets the target field value.
Example:
// Transform full name to first name
var fullName = source.u_full_name.toString();
answer = fullName.split(' ')[0];
Field Map Configuration
Field | Purpose | Common Values/Usage |
Choice Action | Handle invalid choice values | create, ignore, reject |
Referenced Value | Field to match in reference table | name, email, number, user_name |
Source Script | Custom transformation code | answer = source.u_name.toString().toUpperCase(); |
Use Source Script | Enable/disable script | Checked = execute script |
Coalesce Case Sensitive | Case-sensitive matching | Unchecked = "JOHN" = "john" |
Coalesce Empty Fields | Include empty values in match | Usually unchecked |
Complete Example
Scenario: Import users with department lookup
// onStart
var importCounter = 0;
// onBefore
if (source.u_active != 'true') {
ignore = true;
}
// Field Map: Department (Run Script checked)
var deptCode = source.u_dept_code.toString();
var dept = new GlideRecord('cmn_department');
if (dept.get('code', deptCode)) {
answer = dept.sys_id;
}
// onAfter
target.u_import_date = gs.nowDateTime();
// onComplete
gs.info('Imported: ' + importCounter + ' users');
Best Practices
- Use onBefore to filter/skip records early
- Use onAfter for validations and related updates
- Set appropriate coalesce fields to prevent duplicates
- Use Run Scripts for complex transformations
- Test with small datasets first
- Handle errors with try-catch blocks
- Log important information for auditing
