What It Does
The getMonthValue() method extracts the month component from a GlideDateTime object and returns it as an integer between 1 and 12. The method uses 1-based indexing, meaning January returns 1, February returns 2, and so forth through December which returns 12.
Internally, ServiceNow converts the GlideDateTime to UTC before extracting the month value, regardless of the user's timezone preferences or the timezone set on the GlideDateTime instance. This ensures consistent behavior across different user sessions and prevents timezone-related discrepancies in date calculations.
The method always returns a valid integer for properly initialized GlideDateTime objects. For null or invalid GlideDateTime instances, the method will throw a JavaScript error rather than returning null or undefined, making error handling important when working with potentially uninitialized date objects.
Edge cases include dates near month boundaries where timezone conversion might shift the date to a different month in UTC. For example, a datetime of '2024-01-01 02:00:00' in Pacific Standard Time becomes '2024-01-01 10:00:00' in UTC, staying in January, but '2023-12-31 20:00:00' PST becomes '2024-01-01 04:00:00' UTC, changing from December (12) to January (1).
This method works alongside other GlideDateTime extraction methods like getYearUTC(), getDayOfMonthUTC(), and getDayOfWeekUTC(). Unlike getMonthLocalTime() which considers the user's timezone, getMonthValue() provides consistent UTC-based results.
When to Use This
Use getMonthValue() when building date filters for GlideRecord queries, creating monthly reports, or performing date-based calculations where you need consistent, timezone-independent month values. This is particularly valuable in Business Rules and Script Includes that process records from users in different timezones, ensuring uniform date handling across the platform.
Avoid this method when you need to respect user timezone preferences for display purposes or when working with user-facing date operations. In those cases, use getMonthLocalTime() instead. Also avoid using this method in Before Business Rules on insert operations, as the GlideDateTime may not be fully initialized yet.
Never concatenate the return value directly into GlideRecord encoded queries without zero-padding single digits, as this can cause unexpected query results when comparing against database date strings.
Return Value
Returns a JavaScript number (integer) between 1 and 12 inclusive. The value represents the month in UTC timezone: 1 for January, 2 for February, through 12 for December. The return value is always a primitive number, never a string or object, making it safe for direct numeric comparisons and arithmetic operations.
On failure scenarios like null GlideDateTime objects or corrupted date data, the method throws a JavaScript runtime error rather than returning a safe fallback value. Always validate GlideDateTime objects before calling this method, or wrap calls in try-catch blocks when working with potentially invalid date data from user input or external integrations.
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, notifications, or audit records are triggered - this is a pure read operation
- No database writes occur - the method only reads and processes the existing GlideDateTime value
- Performance is very fast - executes in-memory with no database queries or external service calls
- Results are not cached - each call performs the UTC conversion and extraction fresh
- Behaves identically in Before/After Business Rules, Script Includes, and Scheduled Jobs
- Thread-safe and can be called concurrently from multiple script contexts without side effects
- Does not respect user session timezone settings - always returns UTC-based month value
