GlideSystem.include() — ServiceNow API

gs.include(name)→ boolean

advancedTested on Xanadu

What It Does

The gs.include() method searches for a Script Include record with the specified name and loads its script content into the current execution context. This makes any functions or variables defined in that Script Include immediately available to the calling script without requiring explicit instantiation.

Internally, ServiceNow locates the Script Include record in the sys_script_include table where the Name field matches the provided parameter. If found, the platform evaluates the script content in the current scope, effectively executing all top-level code within that Script Include. This differs from modern Script Include instantiation where you create an object instance.

The method returns true when the Script Include is successfully located and loaded, false when the Script Include name cannot be found or when a runtime error occurs during script evaluation. The platform does not throw exceptions for missing Script Includes, making error handling dependent on checking the return value.

⚠️

gs.include() only works in global scope. Scoped applications cannot use this method to load Script Includes from other scopes.

Edge cases include attempting to load Script Includes that contain syntax errors, which causes gs.include() to return false and potentially log JavaScript errors. Loading the same Script Include multiple times will re-execute all initialization code, which can cause unexpected behavior if the Script Include modifies global variables or performs side effects during load.

This method predates modern Script Include patterns and relates to gs.evaluate() in that both execute code in the current context, but gs.include() specifically targets Script Include records while gs.evaluate() executes arbitrary JavaScript strings.

When to Use This

Use gs.include() when working with legacy global Script Includes that define utility functions without using the class-based pattern. This is most common in older ServiceNow instances or when maintaining existing code that relies on function-based Script Includes rather than instantiable classes.

For modern development, use direct instantiation with new ScriptIncludeName() instead. This approach provides better performance, clearer dependencies, and works in both global and scoped applications. Avoid using gs.include() for loading Script Includes that follow the class pattern with initialize functions.

Common misuse includes attempting to use this method to conditionally load Script Includes for performance reasons, but the overhead of checking and loading at runtime often exceeds the memory savings. Another anti-pattern involves using gs.include() inside loops or frequently-called functions where the repeated loading degrades performance.

Return Value

Returns a boolean value: true when the Script Include exists and loads successfully, false when the Script Include cannot be found by name, is inactive, or encounters a JavaScript error during evaluation. The return value does not indicate whether the loaded functions work correctly, only whether the loading process completed.

Always check the return value before attempting to use functions from the loaded Script Include. Calling functions that failed to load will result in ReferenceError exceptions. Use the pattern if (gs.include('ScriptName')) { /* use functions */ } to handle loading failures 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

Executes all top-level code in the Script Include immediately upon loading, including variable declarations and function calls outside of function definitions
Queries the sys_script_include table each time called, with no caching of the lookup results or loaded code
Does not trigger Business Rules, ACLs, or notifications since it reads the Script Include record directly using system-level access
Performance degrades with repeated calls as each invocation re-reads and re-evaluates the Script Include code
JavaScript errors during Script Include evaluation are logged but do not terminate the calling script execution
Only works in server-side contexts and fails silently in client-side scripts rather than throwing an error
Respects Script Include's Active field - inactive Script Includes cannot be loaded and return false

Parameters

Name	Type	Required	Description
name	string	Yes	The name of the Script Include to load. Must match exactly the Name field of the Script Include record, case-sensitive. Cannot include file extensions or paths.

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 — loading a utility Script Includebasic

// Script Include 'DateUtils' contains utility functions
// Must check return value before using functions
if (gs.include('DateUtils')) {
    // Now DateUtils functions are available
    var formatted = formatBusinessDate(new GlideDateTime());
    gs.info('Formatted date: ' + formatted);
    
    var daysDiff = calculateBusinessDays('2024-01-01', '2024-01-15');
    gs.info('Business days: ' + daysDiff);
} else {
    gs.error('Failed to load DateUtils Script Include');
    // Fallback behavior when Script Include unavailable
    var fallbackDate = new GlideDateTime().getDisplayValue();
    gs.info('Using fallback date: ' + fallbackDate);
}

This demonstrates the essential pattern of checking the return value before using loaded functions. Without this check, calling formatBusinessDate() could throw a ReferenceError if the Script Include failed to load.

Intermediate — conditional loading based on system propertyintermediate

// Load different Script Includes based on configuration
var utilsToLoad = gs.getProperty('custom.utils.script_include', 'DefaultUtils');
var loaded = gs.include(utilsToLoad);

if (!loaded) {
    gs.warn('Primary utils failed to load: ' + utilsToLoad);
    // Fallback to default implementation
    loaded = gs.include('DefaultUtils');
}

if (loaded) {
    // Process incident with loaded utilities
    var gr = new GlideRecord('incident');
    gr.addQuery('active', true);
    gr.query();
    
    while (gr.next()) {
        // Use utility function from loaded Script Include
        var processed = processIncidentData(gr);
        gs.info('Processed incident: ' + gr.number + ' Result: ' + processed);
    }
}

This pattern allows runtime selection of different Script Include implementations based on system properties. Useful for environment-specific logic or feature flags, but modern approaches using direct instantiation are preferred.

Advanced — the classic mistake with multiple includesadvanced

// WRONG: Loading Script Include multiple times
function badProcessData(records) {
    var results = [];
    
    for (var i = 0; i < records.length; i++) {
        // This reloads and re-executes the Script Include every iteration
        gs.include('DataProcessor');
        var result = processRecord(records[i]);
        results.push(result);
    }
    return results;
}

// RIGHT: Load once and check return value
function goodProcessData(records) {
    // Load Script Include once before processing
    if (!gs.include('DataProcessor')) {
        throw new Error('DataProcessor Script Include failed to load');
    }
    
    var results = [];
    for (var i = 0; i < records.length; i++) {
        var result = processRecord(records[i]);
        results.push(result);
    }
    return results;
}

The first function demonstrates a performance killer - loading Script Includes inside loops causes repeated database queries and script evaluation. The second function loads once and processes efficiently, which is critical for batch operations.

Gotchas

Script Include names are case-sensitive and must match exactly the Name field in the sys_script_include record, not the display name or any other field.

Multiple calls to gs.include() with the same Script Include name will re-execute all initialization code, potentially causing unexpected side effects if the Script Include modifies global variables.

The method only works in global scope - scoped applications cannot use gs.include() to load Script Includes from other scopes, even if they have access permissions.

Loading a Script Include that contains JavaScript syntax errors returns false but may leave partially-executed code in memory, causing unpredictable behavior in subsequent script execution.

Script Includes loaded with gs.include() bypass normal dependency resolution, so if the loaded Script Include depends on other Script Includes, those dependencies must be manually loaded first or the functions will fail at runtime.

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