setValue

What It Is

The setValue() method is the fundamental GlideRecord operation for setting field values at the database layer, working exclusively with internal representations rather than human-readable display values. While setDisplayValue() accepts what users see ("John Smith" for a reference field), setValue() demands what the database stores (the sys_id "a1b2c3d4e5f6789012345678901234567"). This distinction becomes critical when automating data operations where performance matters and lookup overhead cannot be tolerated.

Architecturally, setValue() operates exclusively on the server side within the ServiceNow application server's Java runtime, never in browser JavaScript. This method is available in business rules, script includes, scheduled jobs, workflow scripts, and transform maps—anywhere server-side GlideRecord objects exist. The method modifies the in-memory representation of a database record without triggering immediate database writes; the actual database update occurs when insert() or update() is called, allowing multiple field modifications to be batched into a single database transaction.

Under the hood, ServiceNow processes setValue() calls through its field type validation system, applying data type coercion and constraint checking before storing the value in the GlideRecord's internal field map. Reference fields receive additional validation to ensure the provided sys_id exists in the target table, while choice fields verify the value exists in the field's choice list. The platform also handles data type conversion—passing a JavaScript string "123" to an integer field automatically converts it to numeric 123, but passing invalid data like "abc" to an integer field will either throw an error or default to null depending on the field configuration.

Without setValue(), any server-side automation becomes impossible—you cannot populate reference fields with known sys_ids, cannot bulk update records efficiently, and cannot perform data imports or integrations where external systems provide internal identifiers rather than display names. Try building a data transformation from an external HR system that provides employee IDs, and you'll immediately understand why setDisplayValue()'s lookup overhead makes it unsuitable for processing thousands of records. The method is also essential for setting fields to empty values—setValue('assigned_to', '') clears a reference field, while passing null or undefined produces different behaviors depending on field type and configuration.

Developers use setValue() daily in business rules for automated field population, workflow activities for state transitions, and scheduled jobs for bulk data operations. System administrators leverage it in data cleanup scripts and one-time fixes where precision matters more than user-friendly interfaces. Enterprise architects rely on it for integration patterns where external systems must efficiently update ServiceNow records without the performance penalty of display value lookups. The method appears in virtually every server-side script that modifies data, from simple field updates to complex multi-table operations spanning multiple applications.

The method's relationship to getValue() forms the core read-write pair for field manipulation—what you retrieve with getValue() can be directly passed to setValue() on another record. Its complement setDisplayValue() offers user-friendly field setting at the cost of database lookups, making the choice between them a fundamental performance decision. The method also interacts closely with the audit system—fields modified through setValue() generate audit trail entries if auditing is enabled for the field, while the autoSysFields flag controls whether system fields like sys_updated_by get automatically populated during the update process.

How It Works Under the Hood

When setValue() executes, ServiceNow's field processing engine first validates the target field exists in the table's schema, then applies field-type specific validation and transformation logic before storing the value in the GlideRecord's internal HashMap structure. For reference fields, the platform performs an existence check against the target table to ensure the provided sys_id references a valid record, failing fast if the reference is invalid rather than allowing dangling references. Choice fields trigger validation against the field's configured choice list, while date/time fields parse and normalize the input according to the user's timezone and the system's internal UTC storage format.

The method operates within ServiceNow's transaction boundary system, meaning multiple setValue() calls on the same GlideRecord accumulate changes in memory without triggering database writes until update() or insert() commits the transaction. During this accumulation phase, the platform tracks which fields have been modified to optimize the eventual SQL UPDATE statement, including only changed fields rather than rewriting the entire record. This change tracking also drives business rule execution—before/after business rules receive the old and new values, while the changes() method can detect which specific fields were modified during the transaction.

Behind the scenes, field-level security and access controls evaluate during the setValue() call when security is enforced on the GlideRecord, potentially blocking the operation if the current user lacks write access to the target field. The platform's data dictionary drives much of this processing, with field attributes like max_length, mandatory status, and custom validation scripts all executing as part of the value assignment process. For calculated fields and dependent choice lists, setValue() may trigger cascade updates to related fields, though these calculations typically defer until the actual database write occurs to avoid redundant processing.

The Processing Lifecycle

1. Field validation occurs first—ServiceNow checks that the target field exists in the table schema and the GlideRecord has been properly initialized with a valid table name.
2. Access control evaluation runs if security enforcement is enabled, checking field-level ACLs and potentially throwing security exceptions for unauthorized write attempts.
3. Data type validation and coercion executes based on the field's dictionary definition—strings get trimmed to max_length, numbers get parsed and validated for range constraints, dates get normalized to UTC.
4. Reference field validation performs existence checks against target tables when a sys_id is provided, ensuring referential integrity at the application layer.
5. Value storage in the GlideRecord's internal field map occurs, with change tracking flags set to mark the field as modified for eventual SQL generation.
6. Dependent field calculations may queue for processing, though most cascade updates defer until the database commit to avoid redundant computation during bulk operations.

The Core Pattern

function onChange(control, oldValue, newValue, isLoading, isTemplate) {
    // Client-side validation before sending to server
    if (newValue == '1') { // High priority selected
        // Gather context data for server processing
        var assignmentGroup = g_form.getValue('assignment_group');
        var category = g_form.getValue('category');
        
        // Call server-side script include for complex logic
        var ga = new GlideAjax('IncidentAssignmentUtil');
        ga.addParam('sysparm_name', 'getEscalationManager');
        ga.addParam('sysparm_assignment_group', assignmentGroup);
        ga.addParam('sysparm_category', category);
        
        ga.getXMLAnswer(function(answer) {
            if (answer) {
                // Set the escalation manager using internal sys_id
                g_form.setValue('u_escalation_manager', answer);
            }
        });
    }
}

var IncidentAssignmentUtil = Class.create();
IncidentAssignmentUtil.prototype = Object.extendsObject(AbstractAjaxProcessor, {
    
    getEscalationManager: function() {
        var assignmentGroup = this.getParameter('sysparm_assignment_group');
        var category = this.getParameter('sysparm_category');
        
        // Query for the appropriate escalation manager
        var grManager = new GlideRecord('sys_user');
        grManager.addQuery('u_department', assignmentGroup);
        grManager.addQuery('u_specialization', 'CONTAINS', category);
        grManager.addQuery('active', true);
        grManager.orderBy('u_escalation_priority'); // Custom field for priority
        grManager.query();
        
        if (grManager.next()) {
            // Return the sys_id for setValue() on client
            return grManager.getValue('sys_id');
        }
        return '';
    }
});

Real-World Scenarios

Bulk Assignment During Major Incidents

During a major outage, hundreds of related incidents need immediate assignment to the war room team without individual lookup overhead. The operations team uses a scheduled job to bulk-assign incidents based on configuration items affected by the primary incident.

// Pre-determine assignment targets to avoid repeated lookups
var warRoomManagerId = '9b2f1c4e1b5634501c9c6e5bbc4bcb12';
var warRoomGroupId = 'a3d2e5f6c78945612d8f9a0bdc3de23f';
var majorIncidentState = '2'; // In Progress

// Query all unassigned incidents from last 2 hours
var gr = new GlideRecord('incident');
gr.addQuery('opened_at', '>', gs.hoursAgo(2));
gr.addQuery('assignment_group', '');
gr.addQuery('priority', '1'); // Critical priority only
gr.query();

gs.info('Processing ' + gr.getRowCount() + ' incidents for bulk assignment');

while (gr.next()) {
    // Use setValue for performance - no display name lookups
    gr.setValue('assigned_to', warRoomManagerId);
    gr.setValue('assignment_group', warRoomGroupId);
    gr.setValue('state', majorIncidentState);
    gr.setValue('work_notes', 'Auto-assigned during major incident response');
    gr.update();
}

Using hard-coded sys_ids eliminates database lookups that would occur with setDisplayValue(), making this pattern essential for time-sensitive bulk operations. Watch for business rules that might cascade from these assignments—disable unnecessary workflows during emergency processing to avoid performance bottlenecks. The autoSysFields(false) option can prevent system field updates if you need to preserve original timestamps.

Service Catalog Fulfillment Automation

When laptop requests get approved, a business rule must create corresponding task records and populate them with requestor information and delivery details. The business rule executes on the sc_req_item table after approval workflow completion.

(function executeRule(current, previous) {
    // Only process laptop requests that just got approved
    if (current.cat_item.name != 'Standard Laptop' || current.state != '3') {
        return;
    }
    
    // Extract requestor and location data
    var requestorId = current.request.requested_for.toString();
    var deliveryLocation = current.variables.u_delivery_location.toString();
    var urgency = current.request.urgency.toString();
    
    // Create fulfillment task with pre-populated assignments
    var task = new GlideRecord('sc_task');
    task.initialize();
    task.setValue('request_item', current.sys_id); // Link back to request
    task.setValue('assigned_to', requestorId); // Assign to requestor for coordination
    task.setValue('assignment_group', 'b4c5d6e7f89012345678901234567890'); // IT Hardware team
    task.setValue('short_description', 'Deliver laptop to ' + current.request.requested_for.name);
    task.setValue('description', 'Laptop model: ' + current.variables.u_laptop_model + '\nDelivery location: ' + deliveryLocation);
    task.insert();
    
    gs.info('Created fulfillment task ' + task.number + ' for request ' + current.number);
})(current, previous);

The toString() calls ensure reference field values get converted to sys_id strings rather than GlideElementReference objects. This pattern is crucial for service catalog automation where multiple systems interact and reference integrity must be maintained. Be careful with variable access—catalog variables require the .variables.field_name syntax and may need additional toString() conversion for reference variables.

Data Import with Reference Field Resolution

An HR system integration provides employee records with department codes that must be resolved to ServiceNow department sys_ids before creating user records. A transform map script handles this conversion during the import process to maintain referential integrity.

// Build department lookup cache to avoid repeated queries
if (typeof departmentCache == 'undefined') {
    departmentCache = {};
    var deptGr = new GlideRecord('cmn_department');
    deptGr.addQuery('active', true);
    deptGr.query();
    while (deptGr.next()) {
        departmentCache[deptGr.getValue('dept_code')] = deptGr.getValue('sys_id');
    }
    gs.info('Loaded ' + Object.keys(departmentCache).length + ' departments into cache');
}

// Resolve department code from import source
var hrDeptCode = source.u_hr_department_code;
var deptSysId = departmentCache[hrDeptCode];

if (deptSysId) {
    // Set department reference using resolved sys_id
    target.setValue('department', deptSysId);
} else {
    // Log missing department but continue processing
    gs.warn('Department code ' + hrDeptCode + ' not found for employee ' + source.u_employee_id);
    target.setValue('department', ''); // Clear field rather than fail
}

Caching the department lookup prevents thousands of individual queries during bulk imports, making setValue() with pre-resolved sys_ids the only viable approach for large datasets. Transform maps execute in a global scope where variables persist across rows, enabling this caching pattern. Handle missing references gracefully—setting empty strings rather than invalid sys_ids prevents import failures while maintaining data quality logs for later cleanup. Consider using ignore_on_error flags on transform maps when reference resolution might fail for some records.

The Classic Mistake

// Business Rule on incident table
(function executeRule(current, previous) {
    // WRONG: Using display value instead of sys_id
    var userName = 'John Smith';
    current.setValue('assigned_to', userName);
    
    // WRONG: Using dotwalked display value
    var groupName = 'IT Support';
    current.setValue('assignment_group', groupName);
    
    // This silently fails - field remains empty
    current.update();
    
    gs.info('Assignment completed for: ' + current.number);
    // Log shows success but database field is NULL
})(current, previous);

This fails because reference fields store sys_id values, not display names. ServiceNow doesn't throw an error—it just silently ignores the invalid value and leaves the field empty. The browser console shows no errors, but if you check the database or use gs.log() to output the field value after the operation, you'll see it's null or unchanged. ServiceNow's internal validation simply rejects the non-GUID value without notification. This is especially insidious because your script appears to run successfully, but the critical business logic fails silently.

// Business Rule on incident table
(function executeRule(current, previous) {
    // CORRECT: Query for sys_id first
    var userGR = new GlideRecord('sys_user');
    userGR.addQuery('name', 'John Smith');
    userGR.query();
    if (userGR.next()) {
        current.setValue('assigned_to', userGR.sys_id);
    }
    
    // CORRECT: Get group sys_id
    var groupGR = new GlideRecord('sys_user_group');
    groupGR.addQuery('name', 'IT Support');
    groupGR.query();
    if (groupGR.next()) {
        current.setValue('assignment_group', groupGR.sys_id);
        current.update();
    }
})(current, previous);

Performance Rules

1. Never call setValue() inside loops processing over 100 records without batching. Each call triggers field validation and audit logging, causing transaction timeouts after 30 seconds and sys admin alerts about long-running scripts.
2. Avoid setValue() on calculated fields like sys_mod_count or sys_updated_on. The platform recalculates these values on save, creating unnecessary processing overhead that can double update operation time.
3. Don't use setValue() on encrypted fields in client scripts. Each call forces a round-trip to the server for encryption, causing 2-3 second delays per field and browser timeout warnings on slow connections.
4. Batch multiple setValue() calls before calling update() or insert(). Making 5+ separate database calls instead of one batch operation triggers connection pool exhaustion during peak usage.
5. Never use setValue() on Journal fields (comments, work notes) in high-frequency operations. Each call creates a separate sys_journal_field record, causing journal table bloat and 10x slower queries on large datasets.
6. Avoid setValue() in Scheduled Jobs processing over 1000 records per run. Use GlideMultipleUpdate instead to prevent job queue backlog and missed schedule executions.
7. Don't call setValue() on reference fields that trigger cascade operations (like parent on cmdb_ci) in synchronous integrations. Each change can trigger relationship recalculation across hundreds of related records, causing API timeout failures.
8. Wrap setValue() calls in setWorkflow(false) when updating over 50 records in data cleanup scripts. Otherwise, each record change triggers all active workflows, causing exponential processing delays and workflow context table growth.

Side Effects & Platform Behavior

• Triggers all Before Business Rules on the target field, even if the new value matches the existing value. This can cause duplicate processing in validation rules and unexpected field modifications.
• Creates an entry in the sys_audit table for every field change, regardless of whether auditing appears enabled in the dictionary. This can fill audit storage on high-volume tables like sys_email or sys_log.
• Automatically increments the sys_mod_count field and updates sys_updated_on timestamp, even when called within the same transaction. This breaks change detection logic that relies on modification count.
• Bypasses Field Access Control (ACL) when called server-side, but honors ACLs in client scripts. This means the same code can produce different results depending on execution context, especially with elevated or restricted users.
• Activates Notification rules configured for field changes, including watchers and subscription-based alerts. Mass updates can flood email queues and trigger email server throttling or blacklisting.
• Forces execution of any active Workflows with conditions matching the modified field, creating new workflow context records in wf_context table that persist until workflow completion.
• Breaks if called on a GlideRecord that hasn't been queried first. The platform throws an 'Invalid table' error that only appears in server logs, not client-side console, making it difficult to debug.
• Causes parent table Business Rules to fire when used on extended tables (like incident extending task), potentially executing the same logic twice with different field contexts.
• Updates the session's glide_user_session record with the last modified table and record sys_id, affecting user activity tracking and session timeout calculations.
• Silently ignores attempts to set read-only fields like sys_created_on or fields with 'Read only' attribute enabled, providing no error feedback but writing a warning to syslog table.

Debugging When It Breaks

The most common failure symptom is silent field updates—your script runs without errors, but the target field remains unchanged or shows unexpected values. Users report that automated assignments, status changes, or field calculations aren't working, but no error messages appear in the interface. Developers often see this when using display values instead of sys_ids for reference fields, or when ACLs block the operation client-side but not server-side.

For server-side issues, check System Logs > All and filter by your script name or transaction ID. Look for 'Invalid field' warnings, 'Access denied' messages, or Business Rule execution errors. For client-side problems, open browser Developer Tools (F12) and check the Console and Network tabs. Failed setValue() operations often show as 200 OK responses with empty or unchanged field values in the JSON payload. Enable Session Debug (elevate to admin, set glide.script.debug.log.enabled=true) to see detailed field-level operation logs.

Common error patterns include 'ReferenceError: Invalid sys_id format' in logs when passing non-GUID values to reference fields, 'SecurityException: Field access denied' for ACL violations, and 'IllegalStateException: No current record' when calling setValue() before querying the GlideRecord. Use the Script Debugger (System Definition > Script Debugger) to set breakpoints and inspect field values before and after setValue() calls.

• Verify the GlideRecord is valid: gr.isValid() should return true
• Check field existence: gr.isValidField('field_name') confirms the field exists
• Test the value format: For reference fields, use GlideStringUtil.isEligibleSysID() to validate sys_id format
• Confirm ACL permissions: Run gr.canWrite() or test with an admin account
• Log before and after values: gs.log(gr.field + ' changed from ' + gr.field.getOldValue())

Quick Reference

• Reference fields require sys_id values only—use setDisplayValue() if you have display names
• Always query the GlideRecord first: setValue() fails on uninitialized records
• Batch multiple setValue() calls before update() for better performance
• Server-side calls bypass ACLs, client-side calls honor them—test in both contexts
• Use setWorkflow(false) before setValue() in mass data operations to prevent workflow cascade
• Date fields accept ISO format strings: '2023-12-25 15:30:00' or GlideDateTime objects
• Choice field values are case-sensitive and must match dictionary options exactly
• Boolean fields accept true/false, 'true'/'false', or '1'/'0' string values interchangeably
• Encrypted fields require special handling—use setDisplayValue() for plain text input
• Check gs.nil(value) before setting—null values clear the field completely