The Unsung APIs of ServiceNow #2 - GlideDateTime

[SumanthDosapati]

📆 The Unsung APIs of ServiceNow — Ep. 2: GlideDateTime

Time is everything—especially in ServiceNow, where SLAs, scheduled jobs, date comparisons, and audits depend on accurate date-time handling.

Yet many developers still struggle with clunky string parsing, timezone mismatches, or unnecessary logic to manipulate dates. Enter the powerful, yet often underused GlideDateTime API—a server-side date powerhouse built for the platform.

Let’s take a closer look at why this API deserves more attention.

---

🎯 What is GlideDateTime?

GlideDateTime is ServiceNow’s server-side class designed to represent date and time values. Unlike JavaScript’s native Date, this API is platform-aware, timezone-smart, and fully compatible with GlideRecord and system fields like created, sys_updated_on, etc.

---

🧪 Real-World Use Cases

✅ 1. Get Current Date-Time

var gdt = new GlideDateTime();
gs.info(gdt.getDisplayValue()); // e.g. "2025-07-21 13:52:00"

Useful for tracking timestamps in logs or custom fields.

---

✅ 2. Add or Subtract Time

var now = new GlideDateTime();
now.addDaysUTC(5);
gs.info(now.getDisplayValue()); // Date 5 days from now (UTC)​

Also supports:

• addMonthsUTC(x)

• addSeconds(x)

• subtract(startDateTime)

---

✅ 3. Compare Two Dates

var date1 = new GlideDateTime('2025-07-21 09:00:00');
var date2 = new GlideDateTime('2025-07-22 09:00:00');

if (date1.before(date2)) {
  gs.info('date1 is earlier than date2');
}

Also available: .after(), .equals()

---

✅ 4. Convert Between Formats

var gdt = new GlideDateTime('2025-07-21 12:00:00');
gs.info(gdt.getValue()); // Returns date in system format (yyyy-MM-dd HH:mm:ss)
gs.info(gdt.getDisplayValue()); // Returns date in user's preferred format

Ideal for scripts involving UI or user preferences.

---

🧠 Other Handy Methods

Method	Description
getLocalDate()	Returns only the date portion
getTime()	Returns only the time portion
getDate().getDayOfWeek()	Returns day of the week (1–7)
subtract(date)	Returns duration difference between two dates
getDaysDifference()	Get difference in days from another datetime

---

🤖 Bonus Tip: Compare Against SLA Threshold

You can use GlideDateTime to check if an update violates SLA thresholds:

var due = current.due_date;
var now = new GlideDateTime();

if (now.after(due)) {
  gs.info('This task is overdue!');
}

---

💡 Why This API Deserves the Spotlight

The GlideDateTime API is incredibly versatile, yet many devs rely on string manipulation or clumsy Date() usage. With built-in timezone support, readable syntax, and system compatibility—it’s built to solve real platform problems.

It doesn’t just work—it works smart.

---

📝 Final Thoughts

Whenever you're handling due dates, logging actions, or automating time-based logic, don’t fight the platform. Use what it gives you. GlideDateTime helps you write readable, accurate, and scalable date/time logic that won't break across regions or updates.

---

🚀 Up Next in the Series
In the next episode of "The Unsung APIs of ServiceNow", I’ll unpack the CatalogSearch class and show you how it complements CatalogSearch for intelligent search experiences.

If you’ve got an overlooked API that deserves a shoutout, drop a comment—I'd love to include it in the series and mention you as a contributor.

Until then, happy building!
— Sumanth Dosapati