GlideRecord.getDisplayValue()

getDisplayValue(fieldName)→ string

beginnerTested on Xanadu

What It Does

The getDisplayValue() method retrieves the human-readable representation of a field's value rather than its stored database value. This is particularly crucial for reference fields, where the database stores a sys_id but users need to see meaningful text like a user's name or an incident number. For choice fields, it returns the display label ("High") instead of the stored numeric or string value ("1" or "high").

ServiceNow executes this method by performing a lookup operation. For reference fields, it queries the referenced table to retrieve the display value of the target record. For choice fields, it consults the choice list configuration to map the stored value to its label. The platform caches these lookups within the current transaction, so multiple calls to the same field don't trigger repeated database queries.

The method returns a string in all cases, but the content varies by field type. For regular text fields, it returns the same value as getValue(). For date/time fields, it returns a formatted string according to the user's locale settings. For reference fields pointing to deleted records, it returns an empty string. For fields that contain invalid choice values (values not in the current choice list), it returns the stored value itself.

Edge cases include reference fields with multiple levels of reference (dot-walking), where getDisplayValue() only resolves the immediate reference, not the chain. Journal fields return the plain text content without HTML formatting. Currency fields include the currency symbol in the display value. Boolean fields return "true" or "false" as strings, not boolean values.

This method complements getValue() by providing the presentation layer value instead of the data layer value. While toString() also returns display values, getDisplayValue() allows you to specify exactly which field you want the display value from, making it more explicit and safer for code maintenance.

When to Use This

Use getDisplayValue() when building notifications, generating reports, or creating any user-facing output where you need human-readable values. This is essential for reference fields in email templates, UI messages, or log entries that administrators will read. Choice fields particularly benefit from this method since raw choice values ("1", "2", "3") mean nothing to users compared to their labels ("Low", "Medium", "High").

Avoid this method when performing comparisons, database operations, or any logic that depends on exact values. Use getValue() instead for conditional logic or when setting field values on other records. Never use display values for queries or filters – they're presentation data, not operational data. For URL parameters or REST API calls, stick with getValue() to ensure consistent, locale-independent behavior.

The most common misuse is trying to query records using display values obtained from getDisplayValue(). This fails because queries expect stored values, not display values. Another mistake is using display values in business logic comparisons, where locale-specific formatting or translations can break the logic unexpectedly.

Return Value

The method always returns a string, even for numeric or boolean fields. The string is formatted according to the current user's locale and timezone settings for date/time fields. For reference fields, it returns the display value from the referenced record's display field (usually "name" or "number"). For choice fields, it returns the exact label text as configured in the choice list, including any special characters or spacing.

On failure or when data is missing, the method returns an empty string ("") rather than null or undefined. This occurs when the field doesn't exist, when a reference field points to a deleted record, or when a reference field is empty. The empty string behavior makes it safe to concatenate or use in string operations without null checks, but you should still validate the result if empty values would break your logic.

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

No Business Rules, Script Engines, or notifications fire – this is a read-only operation that doesn't modify data
Database queries execute for reference field lookups, but results are cached within the current transaction
Performance is generally fast for simple fields and choice lookups, but reference fields can be slower due to additional table queries
ACL (Access Control List) checks apply to referenced records – you won't get display values from records you can't read
No audit records are created since no data modification occurs
Behavior is identical across Business Rules, Script Includes, and Scheduled Jobs – no context-dependent variations
User session locale and timezone settings affect the formatting of date, time, and currency display values

Parameters

Name	Type	Required	Description
fieldName	string	Yes	The field name to get the display value from. Must be a valid field on the current table. If the field doesn't exist, returns an empty string.

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 reference and choice field display valuesbasic

// Get display values from an incident record
var inc = new GlideRecord('incident');
inc.get('INC0000001');

// Reference field - shows user's name instead of sys_id
var assigneeName = inc.getDisplayValue('assigned_to');
gs.info('Assigned to: ' + assigneeName); // "Assigned to: John Doe"

// Choice field - shows label instead of numeric value
var priorityLabel = inc.getDisplayValue('priority');
gs.info('Priority: ' + priorityLabel); // "Priority: 1 - Critical"

// Compare with stored values
var assigneeId = inc.getValue('assigned_to');
var priorityValue = inc.getValue('priority');
gs.info('Stored assignee: ' + assigneeId); // "Stored assignee: 5137153cc611227c000bbd1bd8cd2005"
gs.info('Stored priority: ' + priorityValue); // "Stored priority: 1"

This demonstrates the core difference between display values and stored values. Display values are human-readable while stored values are what the database actually contains.

Building user notifications with display valuesintermediate

// Create a notification message for incident assignment
function createAssignmentNotification(incidentId) {
    var inc = new GlideRecord('incident');
    if (!inc.get(incidentId)) {
        return 'Incident not found';
    }
    
    // Use display values for all user-facing content
    var message = 'Incident ' + inc.getDisplayValue('number') + 
                  ' has been assigned to ' + inc.getDisplayValue('assigned_to') + 
                  '.\n\nDetails:\n' +
                  'Priority: ' + inc.getDisplayValue('priority') + '\n' +
                  'State: ' + inc.getDisplayValue('state') + '\n' +
                  'Category: ' + inc.getDisplayValue('category');
    
    return message;
}

Display values make notifications readable for end users. Using stored values would show sys_ids and numeric codes that mean nothing to recipients.

The classic mistake - querying with display valuesadvanced

// WRONG - This will fail or give unexpected results
var inc1 = new GlideRecord('incident');
inc1.get('INC0000001');
var assigneeName = inc1.getDisplayValue('assigned_to'); // "John Doe"

// This query won't work - assigned_to expects a sys_id, not a name
var inc2 = new GlideRecord('incident');
inc2.addQuery('assigned_to', assigneeName); // FAILS
inc2.query();

// CORRECT - Use stored values for queries
var inc3 = new GlideRecord('incident');
inc3.get('INC0000001');
var assigneeId = inc3.getValue('assigned_to'); // sys_id

// This query works correctly
var inc4 = new GlideRecord('incident');
inc4.addQuery('assigned_to', assigneeId); // WORKS
inc4.query();

Never use display values in queries or business logic. Display values are for presentation only - queries need the actual stored values to function correctly.

Gotchas

Empty reference fields return empty strings, not null, so check for empty strings rather than null when validating reference field display values.

Date and time display values are formatted according to the current user's locale, so the same record can show different formatted dates for different users.

Reference fields pointing to records you don't have read access to return empty strings, even if the reference is valid.

Choice fields with invalid stored values (not in the current choice list) return the stored value itself rather than throwing an error.

Boolean field display values return the strings "true" or "false", not actual boolean values, which can break boolean logic if you're not careful.

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