GlideDateTime.getValue() — ServiceNow API

gdt.getValue()→ string

beginnerTested on Xanadu

What It Does

The getValue() method extracts the internal string representation from a GlideDateTime object. ServiceNow stores all datetime values in the database as strings using the ISO-like format yyyy-MM-dd HH:mm:ss, always in UTC timezone. This method returns exactly that internal representation without any timezone conversion or formatting.

When ServiceNow processes this method, it directly accesses the underlying string value stored in the GlideDateTime object's internal state. The platform performs no timezone calculations, no user preference lookups, and no locale-specific formatting. The returned string represents the exact moment in time as stored in UTC, which is how ServiceNow maintains consistency across all timezones.

The method returns null if the GlideDateTime object contains no valid date value, such as when constructed without parameters or when set to an invalid date. It returns an empty string if the GlideDateTime was explicitly set to an empty value using setValue(''). For partially invalid dates, behavior depends on how the GlideDateTime was constructed—some invalid inputs get normalized to valid dates, others result in null.

Edge cases include leap seconds (ignored by ServiceNow), daylight saving transitions (irrelevant since output is UTC), and dates before 1970 or after 2038 on older instances. The method handles future dates correctly but very distant past dates may have platform-specific limitations depending on the underlying Java implementation.

This method complements getDisplayValue() which formats dates for user display, and getNumericValue() which returns milliseconds since epoch. While toString() also returns the internal string, getValue() is the canonical method when you explicitly need the database storage format.

When to Use This

Use getValue() when you need the exact database format for string comparisons, database queries, or integration with external systems that expect UTC timestamps. This is essential for REST API responses, data exports, or when building encoded queries that include datetime comparisons. The method is also crucial when storing datetime values in non-datetime fields or when debugging timezone-related issues.

Avoid using this method when displaying dates to users—use getDisplayValue() instead to respect user timezone and formatting preferences. Don't use getValue() for mathematical date operations—use getNumericValue() to get milliseconds for calculations. The common mistake is using this for user-facing output, which shows UTC times that confuse users expecting their local timezone.

Return Value

Returns a string in the exact format yyyy-MM-dd HH:mm:ss where yyyy is the four-digit year, MM is the two-digit month (01-12), dd is the two-digit day (01-31), HH is the two-digit hour in 24-hour format (00-23), mm is the two-digit minute (00-59), and ss is the two-digit second (00-59). The time is always in UTC regardless of any timezone settings. No timezone indicators like 'Z' or '+00:00' are included in the string.

On failure or invalid dates, the method returns null (not an empty string). Always check for null before using the return value in string operations or concatenations. The safest pattern is var value = gdt.getValue() || ''; to handle null returns gracefully.

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 notifications fire—this is a read-only operation that accesses existing object data
Nothing is written to the database—the method only reads the internal string value from memory
Very fast performance as it's a simple string accessor with no timezone calculations or formatting overhead
Behavior is identical across all script contexts—before/after Business Rules, Script Includes, Scheduled Jobs
No caching mechanisms involved—each call returns the current internal string value of the object
System timezone, user timezone preferences, and locale settings have no effect on the returned string
Safe to call multiple times on the same object—no side effects or state changes occur

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 — extracting database formatbasic

// Get current time and extract internal format
var now = new GlideDateTime();
var internalFormat = now.getValue();
gs.info('Current time in database format: ' + internalFormat);
// Output: Current time in database format: 2024-03-15 14:30:22

// Compare with display format
var displayFormat = now.getDisplayValue();
gs.info('Same time for users: ' + displayFormat);
// Output: Same time for users: 2024-03-15 07:30:22 (if user is in MST)

// Reading from a record field
var inc = new GlideRecord('incident');
if (inc.get('some-sys-id')) {
    var createdValue = inc.sys_created_on.getValue();
    gs.info('Incident created at: ' + createdValue);
    // Always shows UTC time as stored in database
}

Shows the difference between internal storage format and user display format. The getValue() method always returns UTC time while getDisplayValue() respects user timezone settings.

Intermediate — building encoded queries with datetimeintermediate

// Find incidents created in the last hour using string comparison
var oneHourAgo = new GlideDateTime();
oneHourAgo.addSeconds(-3600);
var thresholdValue = oneHourAgo.getValue();

// Build encoded query using the internal format
var gr = new GlideRecord('incident');
gr.addQuery('sys_created_on', '>=', thresholdValue);
gr.addQuery('state', 'IN', '1,2,3'); // New, In Progress, On Hold
gr.query();

var recentCount = 0;
while (gr.next()) {
    recentCount++;
    // Process recent incidents
    var createdAt = gr.sys_created_on.getValue();
    gs.info('Found incident ' + gr.number + ' created at ' + createdAt);
}

gs.info('Found ' + recentCount + ' recent incidents');

Demonstrates using getValue() to build encoded queries with datetime comparisons. The internal format ensures proper string-based datetime comparisons in the database.

Advanced — handling null values safelyadvanced

// Safe pattern for handling potentially null datetime values
function processTaskDates(taskGR) {
    var createdValue = taskGR.sys_created_on.getValue();
    var updatedValue = taskGR.sys_updated_on.getValue();
    var dueDateValue = taskGR.due_date.getValue(); // May be null
    
    // Safe null handling for required fields (should never be null)
    var created = createdValue || '1970-01-01 00:00:00';
    var updated = updatedValue || created;
    
    // Explicit null check for optional fields
    var dueDate = dueDateValue ? dueDateValue : null;
    
    return {
        created: created,
        updated: updated,
        due: dueDate,
        hasDueDate: dueDate !== null
    };
}

// Usage with proper error handling
var task = new GlideRecord('sc_req_item');
if (task.get('some-sys-id')) {
    var dates = processTaskDates(task);
    gs.info('Task dates: ' + JSON.stringify(dates));
}

Shows defensive programming patterns for handling null returns from getValue(). System fields like sys_created_on should never be null, but user fields like due_date often are.

Gotchas

The method returns null (not empty string) for invalid or uninitialized GlideDateTime objects, which can break string concatenation if not handled properly.

The returned string is always in UTC timezone regardless of user preferences or system timezone settings, which confuses developers expecting local time.

String comparisons work correctly for datetime values only because the yyyy-MM-dd HH:mm:ss format sorts chronologically, but this breaks if you modify the format.

Calling getValue() on a GlideDateTime created from a user's local time input still returns UTC, because ServiceNow converts to UTC during object construction.

The format includes seconds but not milliseconds, so rapid successive operations may appear to have identical timestamps when they actually differ by milliseconds.

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