GlideDateTime.setDisplayValue()

gdt.setDisplayValue(value)→ void

intermediateTested on Xanadu

What It Does

The setDisplayValue() method parses a date/time string using the current user's display format and timezone settings, then converts it to UTC for internal storage. The method expects the input string to match the user's configured date format (found in System Properties > Localization or user preferences).

ServiceNow performs timezone conversion by first interpreting the string as a local time in the user's timezone, then calculating the equivalent UTC time. The platform uses the user's session timezone (from their user record) or the system default timezone if no user context exists. This conversion happens immediately when the method executes.

The method returns void and modifies the GlideDateTime object in place. If the input string cannot be parsed (invalid format, malformed date, or null/undefined), the method silently fails without throwing an error, leaving the existing GlideDateTime value unchanged. There's no return value indicating success or failure.

Edge cases include handling of daylight saving time transitions and ambiguous times. When setting a time that occurs twice during a fall-back transition, ServiceNow assumes the first occurrence. For spring-forward gaps, the platform adjusts to the next valid time. These behaviors align with Java's timezone handling since ServiceNow runs on the JVM.

This method complements setValue() (which expects UTC strings) and setValueUTC() (which bypasses timezone conversion entirely). Use getDisplayValue() to retrieve the value in display format after setting it.

When to Use This

Use setDisplayValue() when accepting date/time input from users through forms, Service Portal widgets, or any interface where users enter dates in their local format. This includes processing CSV imports where dates are in user-readable format, handling REST API inputs that contain localized timestamps, or setting due dates based on user-provided schedules.

Choose setValue() instead when working with system-generated timestamps or API responses that already contain UTC values. Use setValueUTC() for programmatic date calculations where you're certain the input is already in UTC format. Avoid using setDisplayValue() in scheduled jobs or background processes where user context may be unavailable, as timezone conversion becomes unpredictable.

Return Value

The method returns void and provides no indication of success or failure. The GlideDateTime object is modified in place, with the internal UTC value updated if parsing succeeds. When parsing fails due to invalid input, the object retains its previous value without any error notification.

To verify successful parsing, compare the GlideDateTime's value before and after calling the method, or validate the input string format beforehand. The isValid() method can confirm whether the resulting GlideDateTime contains a valid date after the operation completes.

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, ACLs, or audit entries are triggered since this only modifies a script variable, not database records
Nothing is written to the database until the GlideDateTime is assigned to a record field and the record is saved
Performance is fast as it only involves string parsing and timezone calculation without database operations
User session context is required for accurate timezone conversion; behavior may be inconsistent in background processes
Date format parsing depends on system properties and user preferences, making results user-specific
Failed parsing is silent with no error logging, making debugging difficult when incorrect formats are used
Behavior is identical across Business Rules, Script Includes, and other server-side contexts as long as user session exists

Parameters

Name	Type	Required	Description
value	string	Yes	A date/time string in display format (user's timezone and format preferences). Accepts formats like 'MM-dd-yyyy HH:mm:ss' or 'yyyy-MM-dd HH:mm:ss' depending on user settings. Invalid formats are silently ignored, leaving the GlideDateTime unchanged.

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

Setting due date from user form inputbasic

// Business Rule on incident table
// Sets due date based on user-entered priority
var incident = current;
var userEnteredDate = '03-15-2024 14:30:00'; // From form input

// Create GlideDateTime and set from display value
var dueDate = new GlideDateTime();
dueDate.setDisplayValue(userEnteredDate);

// Verify parsing succeeded by checking if valid
if (dueDate.isValid()) {
    incident.due_date = dueDate;
    gs.info('Due date set to: ' + dueDate.getDisplayValue());
} else {
    gs.warn('Failed to parse date: ' + userEnteredDate);
    // Fallback to default 24 hours from now
    dueDate.addDaysUTC(1);
    incident.due_date = dueDate;
}

This demonstrates the primary use case: accepting user date input and validating successful parsing. The validation check prevents silently corrupt data.

Processing CSV import with localized datesintermediate

// Script Include for data import processing
processImportRow: function(csvRow) {
    var startDateStr = csvRow.scheduled_start; // '12/25/2024 09:00:00'
    var endDateStr = csvRow.scheduled_end;     // '12/25/2024 17:00:00'
    
    // Create change request with user-format dates
    var change = new GlideRecord('change_request');
    change.initialize();
    
    // Convert display format dates to UTC for storage
    var startDate = new GlideDateTime();
    var endDate = new GlideDateTime();
    
    startDate.setDisplayValue(startDateStr);
    endDate.setDisplayValue(endDateStr);
    
    // Validate both dates parsed correctly
    if (startDate.isValid() && endDate.isValid()) {
        change.start_date = startDate;
        change.end_date = endDate;
        change.insert();
        return true;
    }
    return false;
}

Shows handling multiple date fields from external data where dates are in user-readable format rather than ISO or UTC strings.

The timezone conversion gotchaadvanced

// Wrong: Assuming input is UTC when using setDisplayValue()
var gdt = new GlideDateTime();
gdt.setDisplayValue('2024-03-10 02:30:00'); // During DST transition!
// This gets converted FROM user timezone TO UTC
// If user is in EST, this becomes '2024-03-10 07:30:00' UTC

// Right: Use setValue() for UTC strings
var gdtCorrect = new GlideDateTime();
gdtCorrect.setValue('2024-03-10 07:30:00'); // Already UTC
// This stays '2024-03-10 07:30:00' UTC

// Compare the difference
gs.info('Display method result: ' + gdt.getValue());
gs.info('Direct setValue result: ' + gdtCorrect.getValue());

// Right: Use setDisplayValue() only for user input
var userInput = '03/10/2024 2:30 AM'; // User's local format
var gdtUser = new GlideDateTime();
gdtUser.setDisplayValue(userInput); // Correct usage

This shows the classic mistake of using setDisplayValue() with UTC strings, causing double timezone conversion. Always match the method to your input format.

Gotchas

Silent failure on invalid input means bad dates go unnoticed unless you explicitly validate with isValid() after calling the method.

During daylight saving transitions, ambiguous times are resolved to the first occurrence, which may not match user expectations.

The method requires user session context for timezone conversion, making it unreliable in scheduled jobs or background processes.

Different users with different timezone settings will get different UTC results from the same display value string.

Using setDisplayValue() with UTC-formatted strings causes double conversion, storing incorrect times in the database.

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