GlideDateTime API

GlideDateTime API in ServiceNow – Complete Guide for CAD Exam

Why is the GlideDateTime API Important?

The GlideDateTime API is one of the most critical server-side APIs in ServiceNow, and it plays a central role in the Certified Application Developer (CAD) exam. Almost every ServiceNow application involves working with date and time values — whether you are calculating SLA deadlines, comparing timestamps, setting due dates, or formatting date/time fields for display. The GlideDateTime API provides a robust, timezone-aware mechanism to handle all of these operations reliably. Understanding this API is essential not only for passing the exam but also for building real-world applications on the ServiceNow platform.

What is the GlideDateTime API?

The GlideDateTime API is a server-side JavaScript API available in ServiceNow that provides methods for performing date-time operations. It is used in server-side scripts such as Business Rules, Script Includes, Scheduled Jobs, and other server-side scripting contexts.

Key characteristics of GlideDateTime:

• It represents a specific point in time (both date and time components).
• It is timezone-aware — internally it stores values in UTC but can convert to the user's timezone or any specified timezone.
• It extends the capabilities of the simpler GlideDate (date only) and GlideTime (time only) APIs.
• It should not be confused with GlideDateTime on the client side — the client-side version has a much more limited set of methods.

How to Create a GlideDateTime Object

There are several ways to instantiate a GlideDateTime object:

1. Current date and time:
var gdt = new GlideDateTime();
This creates a GlideDateTime object set to the current date and time in UTC.

2. From a specific date-time string:
var gdt = new GlideDateTime('2024-06-15 14:30:00');
The string should be in the internal format: yyyy-MM-dd HH:mm:ss.

3. From another GlideDateTime object:
var gdt2 = new GlideDateTime(gdt);
This creates a copy of the existing GlideDateTime object.

Commonly Used Methods

Below are the most frequently tested and used GlideDateTime methods:

Getting Values:
• getValue() — Returns the date-time value in UTC internal format (yyyy-MM-dd HH:mm:ss).
• getDisplayValue() — Returns the date-time value in the current user's timezone and format.
• getDate() — Returns a GlideDate object representing just the date portion.
• getTime() — Returns a GlideTime object representing just the time portion.
• getNumericValue() — Returns the number of milliseconds since January 1, 1970, 00:00:00 UTC (epoch time).
• getDayOfWeek() — Returns the day of the week (1 = Monday, 7 = Sunday in most configurations).
• getMonthLocalTime() — Returns the month (1-12) in the user's local timezone.
• getYearLocalTime() — Returns the year in the user's local timezone.
• getDaysInMonthLocalTime() — Returns the number of days in the month for the local timezone.

Setting Values:
• setValue(dateTimeString) — Sets the value using an internal format string (UTC).
• setDisplayValue(dateTimeString) — Sets the value using the user's timezone and date format.
• setGlideDateTime(gdt) — Sets the value from another GlideDateTime object.

Date-Time Arithmetic:
• add(milliseconds) — Adds the specified number of milliseconds to the date-time.
• add(GlideDuration) — Adds a GlideDuration object to the date-time.
• addDaysLocalTime(days) — Adds a specified number of days in local time.
• addDaysUTC(days) — Adds a specified number of days in UTC.
• addMonthsLocalTime(months) — Adds a specified number of months in local time.
• addMonthsUTC(months) — Adds months in UTC.
• addYearsLocalTime(years) — Adds years in local time.
• addYearsUTC(years) — Adds years in UTC.
• addWeeksLocalTime(weeks) — Adds weeks in local time.
• addWeeksUTC(weeks) — Adds weeks in UTC.
• subtract(GlideDateTime) — Subtracts one GlideDateTime from another, returning a GlideDuration.

Comparison Methods:
• after(gdt) — Returns true if the current object is after the specified GlideDateTime.
• before(gdt) — Returns true if the current object is before the specified GlideDateTime.
• compareTo(gdt) — Returns 0 if equal, a positive value if greater, and a negative value if less.
• equals(gdt) — Returns true if both objects represent the same point in time.
• onOrAfter(gdt) — Returns true if the current object is on or after the specified GlideDateTime.
• onOrBefore(gdt) — Returns true if the current object is on or before the specified GlideDateTime.

Timezone Methods:
• getTZOffset() — Returns the timezone offset in milliseconds.
• getLocalDate() — Returns a GlideDate in the user's local timezone.
• getLocalTime() — Returns a GlideTime in the user's local timezone.

How GlideDateTime Works Internally

Understanding the internal mechanics is crucial for the exam:

1. Internal storage is always in UTC. When you call getValue(), you get the UTC representation. When you call getDisplayValue(), the system converts the UTC value to the logged-in user's timezone setting.

2. When reading from or writing to GlideRecord fields, date-time fields store values in UTC internally. Using setValue() on a GlideRecord date-time field expects the internal (UTC) format. Using setDisplayValue() expects the user-formatted value.

3. The difference between LocalTime and UTC methods: Methods ending in LocalTime (like addDaysLocalTime()) respect the user's timezone when performing calculations, while UTC variants operate purely in UTC. This distinction matters when crossing daylight saving time boundaries.

GlideDateTime vs. GlideDuration

It is important to understand the relationship between these two classes:

• GlideDateTime represents an absolute point in time (e.g., June 15, 2024 at 2:30 PM).
• GlideDuration represents a span of time (e.g., 5 days, 3 hours, and 20 minutes).
• When you subtract one GlideDateTime from another, the result is a GlideDuration.
• You can add a GlideDuration to a GlideDateTime to get a new GlideDateTime.

Example:
var start = new GlideDateTime('2024-06-01 08:00:00');
var end = new GlideDateTime('2024-06-05 14:30:00');
var duration = GlideDateTime.subtract(start, end);
gs.info(duration.getDisplayValue()); // Displays the duration between the two dates

Common Use Cases in Application Development

1. Setting a due date on a record:
var gdt = new GlideDateTime();
gdt.addDaysLocalTime(7);
current.due_date = gdt;

2. Comparing dates in a Business Rule:
var now = new GlideDateTime();
var dueDate = new GlideDateTime(current.due_date);
if (now.after(dueDate)) { /* overdue logic */ }

3. Calculating age or elapsed time:
var created = new GlideDateTime(current.sys_created_on);
var now = new GlideDateTime();
var elapsed = GlideDateTime.subtract(created, now);

4. Formatting for notifications or reports:
var gdt = new GlideDateTime(current.due_date);
var formatted = gdt.getDisplayValue();

Important Distinctions for the Exam

• Server-side vs. Client-side: The full GlideDateTime API is available only on the server side. On the client side, you should use g_form.getValue() to get date-time field values as strings or use GlideAjax to call server-side GlideDateTime methods.

• getValue() vs. getDisplayValue(): This is one of the most commonly tested distinctions. getValue() returns the internal UTC format. getDisplayValue() returns the value adjusted to the user's timezone and formatted per user preferences.

• GlideDateTime vs. JavaScript Date object: You should use GlideDateTime (not the native JavaScript Date object) in ServiceNow server-side scripts. GlideDateTime integrates with the platform's timezone handling and date formatting.

• Static method: GlideDateTime.subtract(): Note that subtract() is called as a static method on the GlideDateTime class, not on an instance. The syntax is GlideDateTime.subtract(start, end), which returns a GlideDuration.

Exam Tips: Answering Questions on GlideDateTime API

1. Know the difference between getValue() and getDisplayValue(): Exam questions frequently test whether you understand that getValue() returns UTC format and getDisplayValue() returns the user's local timezone format. If a question asks about displaying a date to a user, the answer is getDisplayValue(). If a question asks about internal or database values, the answer is getValue().

2. Remember that GlideDateTime is server-side only (full API): If a question mentions client-side scripting (Client Scripts, UI Policies), the full GlideDateTime API is not directly available. You would need to use GlideAjax to access it from the client.

3. Understand the subtract() static method: A common exam trap is presenting subtract() as an instance method. Remember: GlideDateTime.subtract(gdt1, gdt2) is the correct syntax, and it returns a GlideDuration, not a GlideDateTime.

4. Pay attention to LocalTime vs. UTC variants: Questions may test whether you know the difference between addDaysLocalTime() and addDaysUTC(). If the question context involves user-facing calculations or timezone-sensitive logic, LocalTime methods are typically correct.

5. Watch for constructor patterns: Know all the ways to create a GlideDateTime — with no arguments (current time), with a string argument (specific date-time), or with another GlideDateTime object (copy).

6. GlideDateTime fields on GlideRecord: When setting a date-time field on a GlideRecord, you can assign a GlideDateTime object directly to the field: current.due_date = gdt;. The platform handles the conversion.

7. Eliminate wrong answers by checking API availability: If an answer option uses a method that does not exist on GlideDateTime (e.g., a made-up method name), eliminate it. Familiarize yourself with the actual method names.

8. Read questions carefully for timezone context: Many exam questions include subtle cues about timezone requirements. Words like "user's local time," "displayed to the user," or "internal format" are key indicators of whether to use display-oriented or UTC-oriented methods.

9. Practice with code snippets: The exam often presents code and asks for the output or behavior. Practice reading GlideDateTime code and predicting results, especially involving arithmetic operations and comparisons.

10. Remember the relationship with GlideDuration: Subtracting two GlideDateTime objects yields a GlideDuration. Adding a GlideDuration to a GlideDateTime yields a new GlideDateTime. This relationship is commonly tested.

Summary

The GlideDateTime API is a foundational server-side API in ServiceNow that every application developer must master. It provides comprehensive methods for creating, manipulating, comparing, and formatting date-time values in a timezone-aware manner. For the CAD exam, focus on understanding the distinction between internal (UTC) and display (user timezone) values, the correct use of static vs. instance methods, and the relationship between GlideDateTime and GlideDuration. Practicing with real code examples will solidify your understanding and help you confidently tackle exam questions on this topic.