GlideDateTime.getYearValue()

gdt.getYearValue()→ number

beginnerTested on Xanadu

What It Does

The getYearValue() method extracts the year portion from a GlideDateTime object and returns it as a four-digit number. The method operates on the UTC representation of the datetime, ignoring any user timezone settings or system timezone configuration. When you call this method, ServiceNow examines the internal UTC timestamp stored in the GlideDateTime object and returns only the year component.

Internally, ServiceNow maintains GlideDateTime objects as UTC timestamps. When getYearValue() executes, it parses this UTC timestamp and extracts the year without performing any timezone calculations. This ensures consistent behavior regardless of the user's timezone or the system's default timezone settings. The method directly accesses the year from the ISO 8601 representation of the stored datetime.

The method always returns a number type, never null, undefined, or a string. Even if the GlideDateTime object contains an invalid date, the method will return a number—typically 1970 for epoch-based edge cases. The return value is always a four-digit integer, so years like 2024 return 2024, not 24 or any abbreviated format.

Edge cases occur when working with very early dates (before 1970) or very late dates (after 2038 on some systems). The method handles these gracefully but may return unexpected values for dates outside the typical range. Empty or newly instantiated GlideDateTime objects typically default to the current datetime, so getYearValue() will return the current year rather than throwing an error.

This method pairs logically with getMonthValue(), getDayOfMonthValue(), and other date component extraction methods in the GlideDateTime class. All these methods operate on UTC and return numeric values, making them suitable for mathematical operations and comparisons without string parsing overhead.

When to Use This

Use getYearValue() when you need to extract just the year for mathematical calculations, business logic, or filtering operations. This method excels in scenarios like calculating fiscal years, determining age from birth dates, grouping records by year, or implementing year-based business rules. It's particularly useful when building dynamic GlideRecord queries where you need to filter by year without worrying about timezone complications.

Avoid using this method when you need timezone-aware year extraction for user-facing displays or reports where the user's local timezone matters. In those cases, use getLocalDate() combined with getValue() or format the datetime using getDisplayValue(). Don't use getYearValue() for user interface elements where timezone differences could confuse users about which day or year an event actually occurred in their local time.

Return Value

The method returns a JavaScript number representing the four-digit year in UTC. The value is always an integer between typical year ranges (like 1970 to 2099), though it can handle years outside this range. The return type is specifically a number, not a string, so you can perform direct mathematical operations without type conversion. Values like 2024, 1999, or 2030 are typical return values.

The method never returns null, undefined, or throws an exception under normal circumstances. Invalid or uninitialized GlideDateTime objects may return unexpected years like 1970 (Unix epoch) or the current year, but they still return a valid number. You can safely use the return value in arithmetic operations, comparisons, and string concatenations without null checking, though you should validate that the year makes sense for your business logic context.

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 database operations are triggered—this is a pure read operation on an existing GlideDateTime object
No Business Rules, notifications, or audit entries are created since this only extracts data
Performance is very fast—the operation is a simple integer extraction from an in-memory object
No caching mechanisms are involved since GlideDateTime objects are already in memory
Works identically in before/after Business Rules, Script Includes, and Scheduled Jobs—no behavioral differences
User session timezone settings have no impact on the returned value—always uses UTC
No ACL checks are performed since this operates on data already loaded in the session

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 year from incident creationbasic

// Get current year and filter incidents from this year
var currentYear = new GlideDateTime().getYearValue();
gs.info('Current year: ' + currentYear);

var gr = new GlideRecord('incident');
gr.addQuery('opened_at', '>=', currentYear + '-01-01 00:00:00');
gr.query();

while (gr.next()) {
    var openedDate = new GlideDateTime(gr.opened_at.getValue());
    var openedYear = openedDate.getYearValue();
    
    // Business logic based on year
    if (openedYear == currentYear) {
        gs.info('Incident ' + gr.number + ' opened in current year: ' + openedYear);
    }
}

// Year arithmetic for age calculations
var systemInstallDate = new GlideDateTime('2020-03-15 10:30:00');
var systemAge = currentYear - systemInstallDate.getYearValue();
gs.info('System is ' + systemAge + ' years old');

This example shows typical year extraction for filtering and calculations. Notice how the returned number can be used directly in arithmetic operations and string concatenation without conversion.

Intermediate — fiscal year calculation with business logicintermediate

// Calculate fiscal year (starts in July) for budget categorization
var RequestUtils = Class.create();
RequestUtils.prototype = {
    
    getFiscalYear: function(glideDateTime) {
        var calendarYear = glideDateTime.getYearValue();
        var month = glideDateTime.getMonthValue();
        
        // Fiscal year starts in July (month 7)
        if (month >= 7) {
            return calendarYear + 1;  // July 2023 = FY 2024
        } else {
            return calendarYear;      // March 2024 = FY 2024
        }
    },
    
    categorizeBudgetRequests: function() {
        var gr = new GlideRecord('sc_req_item');
        gr.addQuery('state', 'IN', '1,2');  // Requested or In Progress
        gr.query();
        
        while (gr.next()) {
            var requestDate = new GlideDateTime(gr.sys_created_on.getValue());
            var fiscalYear = this.getFiscalYear(requestDate);
            
            // Update fiscal year field for reporting
            gr.u_fiscal_year = fiscalYear.toString();
            gr.update();
        }
    }
};

This pattern shows how to use year values in business calculations where the business year differs from calendar year. The numeric return value makes the fiscal year math straightforward.

Advanced — timezone gotcha with year boundariesadvanced

// WRONG: Assuming getYearValue() respects user timezone
var userDate = new GlideDateTime('2023-12-31 23:30:00');  // UTC time
var displayYear = userDate.getYearValue();  // Always 2023 (UTC)
gs.info('User sees year: ' + displayYear);  // WRONG for users in ahead timezones

// RIGHT: Consider timezone for user-facing year display
function getDisplayYear(glideDateTime, userTimezone) {
    var localDateTime = new GlideDateTime(glideDateTime.getValue());
    
    // Convert to user's local time before extracting year
    var userGDT = new GlideDateTime();
    userGDT.setValue(glideDateTime.getValue());
    
    // For display purposes, format in user timezone
    var userDate = userGDT.getDisplayValue();  // Respects user session timezone
    var yearMatch = userDate.match(/^(\d{4})/);
    
    return yearMatch ? parseInt(yearMatch[1]) : localDateTime.getYearValue();
}

// Usage: comparing UTC year vs user's local year
var utcYear = userDate.getYearValue();  // 2023
var displayYearForUser = getDisplayYear(userDate, gs.getSession().getTimeZoneName());
gs.info('UTC year: ' + utcYear + ', User local year: ' + displayYearForUser);

This demonstrates the critical timezone gotcha—getYearValue() always uses UTC, which can show the wrong year for users in timezones ahead of UTC when dealing with dates near year boundaries.

Gotchas

The method always returns the UTC year, never the user's local timezone year, which can cause confusion around New Year boundaries.

Empty or uninitialized GlideDateTime objects may return the current year or 1970 instead of null or throwing an error.

The return value is always a number type, so comparisons with string years require explicit conversion or type coercion.

Very old dates (before 1970) or very future dates may return unexpected values depending on the underlying system limits.

The method works on the stored datetime value, so if the original datetime was incorrectly set, the year extraction will also be wrong.

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