Script Include Utility Library Pattern…

intermediateTested on Xanadu

The Script Include Utility Library Pattern creates centralized, reusable server-side JavaScript libraries that can be consumed across multiple ServiceNow applications, scopes, and contexts. This pattern encapsulates common business logic, data access patterns, and utility functions into well-structured Script Includes that promote code reuse and maintainability.

This pattern solves the problem of code duplication across Business Rules, Scheduled Jobs, REST APIs, and other server-side scripts by providing a single source of truth for shared functionality. It also addresses performance concerns through built-in caching mechanisms and provides consistent error handling and logging across your ServiceNow implementation.

The pattern works by defining Script Includes with either singleton or instantiable class structures, implementing caching layers for expensive operations, and designing APIs that are consumable across different application scopes while maintaining proper encapsulation and testability.

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

Use This When

Use this pattern when you have business logic or data access code that needs to be shared across multiple scripts, applications, or scopes. It's ideal for complex calculations, external system integrations, data transformation utilities, or any functionality that would otherwise be duplicated in multiple places.

Avoid When

Avoid this pattern for simple, one-off operations that are specific to a single Business Rule or script. Don't use it when the overhead of creating a separate Script Include outweighs the benefits, or when the functionality is tightly coupled to a specific table or process that won't be reused elsewhere.

Implementation

Server-side

// Script Include Name: UserUtilityLib
// Type: Classless (for singleton pattern)
// Accessible from: All application scopes
// Active: true

var UserUtilityLib = Class.create();
UserUtilityLib.prototype = {
    initialize: function() {
        this._cache = {};
        this._cacheExpiry = 5 * 60 * 1000; // 5 minutes in milliseconds
    },

    // Get user's full profile with caching
    getUserProfile: function(userId) {
        var cacheKey = 'user_profile_' + userId;
        var cached = this._getFromCache(cacheKey);
        
        if (cached) {
            gs.debug('UserUtilityLib: Returning cached profile for user ' + userId);
            return cached;
        }

        var userGr = new GlideRecord('sys_user');
        if (!userGr.get(userId)) {
            gs.warn('UserUtilityLib: User not found: ' + userId);
            return null;
        }

        var profile = {
            sys_id: userGr.getUniqueValue(),
            name: userGr.getDisplayValue('name'),
            email: userGr.getDisplayValue('email'),
            department: userGr.getDisplayValue('department'),
            manager: userGr.getDisplayValue('manager'),
            roles: this._getUserRoles(userId),
            groups: this._getUserGroups(userId)
        };

        this._setCache(cacheKey, profile);
        return profile;
    },

    // Check if user has specific role with caching
    hasRole: function(userId, roleName) {
        var profile = this.getUserProfile(userId);
        if (!profile || !profile.roles) return false;
        
        return profile.roles.some(function(role) {
            return role.name === roleName;
        });
    },

    // Batch user lookup for performance
    getUserProfiles: function(userIds) {
        var self = this;
        var results = {};
        var uncachedIds = [];

        // Check cache first
        userIds.forEach(function(userId) {
            var cached = self._getFromCache('user_profile_' + userId);
            if (cached) {
                results[userId] = cached;
            } else {
                uncachedIds.push(userId);
            }
        });

        // Batch fetch uncached users
        if (uncachedIds.length > 0) {
            var userGr = new GlideRecord('sys_user');
            userGr.addQuery('sys_id', 'IN', uncachedIds.join(','));
            userGr.query();

            while (userGr.next()) {
                var userId = userGr.getUniqueValue();
                var profile = {
                    sys_id: userId,
                    name: userGr.getDisplayValue('name'),
                    email: userGr.getDisplayValue('email'),
                    department: userGr.getDisplayValue('department'),
                    manager: userGr.getDisplayValue('manager'),
                    roles: self._getUserRoles(userId),
                    groups: self._getUserGroups(userId)
                };
                
                results[userId] = profile;
                self._setCache('user_profile_' + userId, profile);
            }
        }

        return results;
    },

    // Clear cache for specific user or all users
    clearCache: function(userId) {
        if (userId) {
            delete this._cache['user_profile_' + userId];
            gs.info('UserUtilityLib: Cleared cache for user ' + userId);
        } else {
            this._cache = {};
            gs.info('UserUtilityLib: Cleared all cache');
        }
    },

    // Private method to get user roles
    _getUserRoles: function(userId) {
        var roles = [];
        var roleGr = new GlideRecord('sys_user_has_role');
        roleGr.addQuery('user', userId);
        roleGr.addQuery('state', 'active');
        roleGr.query();

        while (roleGr.next()) {
            roles.push({
                sys_id: roleGr.role.getUniqueValue(),
                name: roleGr.role.getDisplayValue()
            });
        }
        return roles;
    },

    // Private method to get user groups
    _getUserGroups: function(userId) {
        var groups = [];
        var groupGr = new GlideRecord('sys_user_grmember');
        groupGr.addQuery('user', userId);
        groupGr.query();

        while (groupGr.next()) {
            groups.push({
                sys_id: groupGr.group.getUniqueValue(),
                name: groupGr.group.getDisplayValue()
            });
        }
        return groups;
    },

    // Cache management methods
    _getFromCache: function(key) {
        var cached = this._cache[key];
        if (!cached) return null;
        
        if (new Date().getTime() - cached.timestamp > this._cacheExpiry) {
            delete this._cache[key];
            return null;
        }
        
        return cached.data;
    },

    _setCache: function(key, data) {
        this._cache[key] = {
            data: data,
            timestamp: new Date().getTime()
        };
    },

    type: 'UserUtilityLib'
};

// Usage examples:
// var userUtil = new UserUtilityLib();
// var profile = userUtil.getUserProfile(gs.getUserID());
// var hasItilRole = userUtil.hasRole(gs.getUserID(), 'itil');
// var profiles = userUtil.getUserProfiles(['user1', 'user2', 'user3']);

// Singleton pattern alternative (add to same Script Include):
UserUtilityLib.getInstance = function() {
    if (!UserUtilityLib._instance) {
        UserUtilityLib._instance = new UserUtilityLib();
    }
    return UserUtilityLib._instance;
};

This example demonstrates both instantiable and singleton patterns with comprehensive caching, batch operations for performance, and proper error handling. The library includes cache expiration logic, private helper methods for data access, and provides multiple consumption patterns including batch operations to minimize database queries when processing multiple users.

Alternatives

Global Business Rules with Script Actions

Simpler to implement for basic shared functions but lacks proper encapsulation, caching capabilities, and testability. Use when you need simple utility functions that don't require complex state management.

REST APIs with Scripted REST Resources

Better for cross-instance or external consumption but adds HTTP overhead for internal usage. Choose this when your utility needs to be consumed by external systems or when you need strict API versioning.

Global Scoped Application with Export APIs

Provides better dependency management and version control but requires more setup and governance overhead. Use for complex utility libraries that need formal release management and cross-scope distribution.

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