GlideRecord.setDisplayValue()

setDisplayValue(fieldName, value)→ void

intermediateTested on Xanadu

What It Does

The setDisplayValue method allows you to set a field's value using its human-readable display representation rather than the internal database value. This is particularly powerful for reference fields, where you might know the name of a user or configuration item but not their sys_id.

When you call setDisplayValue, ServiceNow doesn't immediately resolve the display value. Instead, it stores the display value temporarily and performs the resolution when you call insert() or update(). The platform searches the referenced table's display field for an exact match and uses the corresponding sys_id.

The method returns void and provides no immediate feedback about whether the display value will successfully resolve. If ServiceNow cannot find a matching record when you save, the field will be set to empty/null rather than throwing an error. This silent failure behavior requires defensive coding practices.

For non-reference fields, setDisplayValue often behaves identically to setValue, but there are exceptions. Choice fields will accept display labels, and date/time fields can accept formatted strings. The key difference from setValue is that this method always treats the input as user-facing data rather than raw database values.

Unlike getDisplayValue which reads display values, or getValue which reads raw values, this method specifically handles the complexity of translating human-readable input into database-appropriate values. It's the programmatic equivalent of what happens when a user types into a reference field in the ServiceNow UI.

When to Use This

Use setDisplayValue when you're working with data imports, integrations, or user inputs where you have display names but not sys_ids. This commonly occurs when processing CSV files, web service calls, or forms where users select items by name. It's also essential when creating records based on external system data that uses readable identifiers rather than ServiceNow's internal IDs.

Avoid this method when you already have the sys_id – use setValue instead for better performance and reliability. Don't use setDisplayValue in tight loops or when processing large datasets, as the display value resolution adds overhead. Also avoid it when the display values might not be unique, as ServiceNow will pick the first match it finds, which may not be the intended record.

⚠️

Never rely on setDisplayValue for critical data integrity. Always verify the field was set correctly after saving, as resolution failures are silent.

Return Value

This method returns void – it provides no return value and no immediate indication of success or failure. The display value is stored internally and will be resolved during the next database operation. This means you cannot determine if the display value is valid until after calling insert() or update().

Since there's no return value to check, you should verify successful field population by reading the field value after saving the record. Use getValue() to check if the field contains a sys_id, or getDisplayValue() to confirm the display value was resolved correctly.

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.

Platform Behavior & Side Effects

Display value resolution occurs during database save operations, not when the method is called, adding latency to insert/update operations
Business Rules, ACLs, and other server-side logic see the resolved sys_id value, not the original display value you passed in
Failed display value resolution results in empty/null field values with no error thrown, potentially causing silent data quality issues
Resolution queries against referenced tables respect ACLs, so users' read permissions affect which display values can be successfully resolved
Multiple records with identical display values will resolve to the first match found, making the behavior non-deterministic in some cases
Performance impact increases with table size since resolution requires querying the referenced table's display field
Audit records capture the final sys_id value after resolution, not the original display value that was set

Parameters

Name	Type	Required	Description
fieldName	string	Yes	The name of the field to set. Must be a valid field on the table. Works with any field type but most useful for reference fields.
value	string	Yes	The display value to set. For reference fields, this should match the display field of the referenced table. ServiceNow will resolve this to the appropriate sys_id on save.

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

Code Examples

Basic usage — Setting assignee by namebasic

// Create incident and assign to user by display name
var inc = new GlideRecord('incident');
inc.newRecord();
inc.short_description = 'Network connectivity issue';
inc.impact = '2';
inc.urgency = '2';

// Set assignee using display name instead of sys_id
inc.setDisplayValue('assigned_to', 'John Smith');

// Display value resolves during insert
var sysId = inc.insert();

// Verify the assignment worked
if (inc.assigned_to.nil()) {
    gs.log('Warning: Could not resolve user "John Smith"');
} else {
    gs.log('Assigned to: ' + inc.assigned_to.getDisplayValue());
}

Sets the assigned_to field using a user's display name rather than their sys_id. Always check if the field is populated after saving to catch resolution failures.

Intermediate — Bulk assignment with validationintermediate

// Assign multiple incidents to users from an external system
var assignments = [
    {number: 'INC0010001', assignee: 'Sarah Johnson'},
    {number: 'INC0010002', assignee: 'Mike Davis'},
    {number: 'INC0010003', assignee: 'Invalid User'}
];

var failedAssignments = [];

for (var i = 0; i < assignments.length; i++) {
    var inc = new GlideRecord('incident');
    if (inc.get('number', assignments[i].number)) {
        inc.setDisplayValue('assigned_to', assignments[i].assignee);
        inc.update();
        
        // Validate assignment succeeded
        if (inc.assigned_to.nil()) {
            failedAssignments.push(assignments[i]);
        }
    }
}

gs.log('Failed to resolve ' + failedAssignments.length + ' assignments');

Shows how to handle bulk operations with display values and validate that each resolution succeeded. Critical for data integrity in integration scenarios.

The classic mistake — Not checking resolutionadvanced

// WRONG - No validation of display value resolution
var task = new GlideRecord('sc_task');
task.newRecord();
task.short_description = 'Provision laptop';
task.setDisplayValue('assigned_to', userInput); // userInput might be invalid
task.insert();
// Task created but potentially unassigned!

// RIGHT - Always validate critical field assignments
var task2 = new GlideRecord('sc_task');
task2.newRecord();
task2.short_description = 'Provision laptop';
task2.setDisplayValue('assigned_to', userInput);
task2.insert();

if (task2.assigned_to.nil()) {
    // Fall back to default assignee or throw error
    task2.setDisplayValue('assigned_to', 'Service Desk');
    task2.update();
}

The first example shows the dangerous pattern of trusting display value resolution without verification. The second example shows proper defensive coding with fallback logic.

Gotchas

Display value resolution happens during save operations, not when setDisplayValue is called, so validation must occur after insert() or update().

Failed display value resolution silently sets the field to empty/null rather than throwing an error, potentially creating data quality issues.

When multiple records have identical display values, ServiceNow uses the first match found, which may not be the intended record.

ACL permissions affect display value resolution – users must have read access to the referenced table for resolution to work.

Performance degrades with large reference tables since each resolution requires a database query against the target table's display field.

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