Robust Script Error Handling Pattern for…

intermediateTested on Xanadu

The Robust Script Error Handling Pattern provides a standardized approach to gracefully managing exceptions and errors in ServiceNow server-side scripts. This pattern wraps potentially problematic code sections in try-catch blocks while implementing structured logging that captures detailed error information for debugging without exposing sensitive technical details to end users.

This pattern solves the common problem of scripts failing silently or displaying cryptic error messages that confuse users and make troubleshooting difficult. By implementing consistent error handling, you can ensure that system administrators receive detailed diagnostic information in the system logs while users see helpful, actionable error messages. The pattern also prevents sensitive information like database queries, API keys, or internal system details from being exposed in user-facing error messages.

The pattern works by establishing error boundaries around risky operations, capturing both expected and unexpected exceptions, logging structured error data with appropriate severity levels, and returning sanitized responses to the calling context. This approach maintains system stability while providing the visibility needed for effective monitoring and debugging.

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 in Business Rules, Script Includes, Scheduled Jobs, and other server-side scripts that perform operations which could fail due to external dependencies, data validation issues, or unexpected system states. It's particularly valuable when building integrations with external systems, processing user input, or performing complex data transformations where failures need to be handled gracefully.

Avoid When

Avoid overusing this pattern for simple operations that are unlikely to fail or where the overhead of try-catch blocks would impact performance significantly. Don't use it as a substitute for proper input validation or to mask underlying system design issues that should be addressed at their root cause.

Implementation

Server-side

var ErrorHandler = Class.create();
ErrorHandler.prototype = {
    initialize: function() {
        this.correlationId = gs.generateGUID();
    },

    executeWithErrorHandling: function(operation, context) {
        context = context || {};
        var result = {
            success: false,
            message: '',
            data: null,
            correlationId: this.correlationId
        };

        try {
            // Log operation start for audit trail
            gs.info('Starting operation: {0} [ID: {1}]', [context.operationName || 'Unknown', this.correlationId]);
            
            // Execute the risky operation
            result.data = operation.call(this, context);
            result.success = true;
            result.message = context.successMessage || 'Operation completed successfully';
            
            gs.info('Operation completed successfully: {0} [ID: {1}]', [context.operationName || 'Unknown', this.correlationId]);
            
        } catch (error) {
            // Log detailed error information for administrators
            var errorDetails = {
                correlationId: this.correlationId,
                operation: context.operationName || 'Unknown',
                errorMessage: error.message,
                errorStack: error.stack,
                userId: gs.getUserID(),
                userName: gs.getUserName(),
                timestamp: new GlideDateTime().getDisplayValue(),
                context: JSON.stringify(context)
            };
            
            gs.error('Script execution failed [ID: {0}]: {1}', [this.correlationId, JSON.stringify(errorDetails)]);
            
            // Return user-friendly message without technical details
            result.success = false;
            result.message = this._getUserFriendlyMessage(error, context);
            result.data = null;
            
            // Optionally send notification to administrators for critical errors
            if (context.notifyOnError) {
                this._notifyAdministrators(errorDetails, context);
            }
        }
        
        return result;
    },
    
    _getUserFriendlyMessage: function(error, context) {
        // Map technical errors to user-friendly messages
        var errorMessage = error.message.toLowerCase();
        
        if (errorMessage.indexOf('access denied') > -1 || errorMessage.indexOf('security') > -1) {
            return 'You do not have permission to perform this action. Please contact your administrator.';
        } else if (errorMessage.indexOf('network') > -1 || errorMessage.indexOf('timeout') > -1) {
            return 'A network error occurred. Please try again in a few moments.';
        } else if (errorMessage.indexOf('invalid') > -1) {
            return 'The provided information is not valid. Please check your input and try again.';
        } else {
            return context.genericErrorMessage || 'An unexpected error occurred. Please contact support if the issue persists. Reference ID: ' + this.correlationId;
        }
    },
    
    _notifyAdministrators: function(errorDetails, context) {
        try {
            var event = new GlideRecord('sysevent');
            event.name = 'script.error.notification';
            event.parm1 = errorDetails.correlationId;
            event.parm2 = errorDetails.operation;
            event.instance = JSON.stringify(errorDetails);
            event.insert();
        } catch (notificationError) {
            gs.error('Failed to send error notification: ' + notificationError.message);
        }
    },

    type: 'ErrorHandler'
};

// Example usage in a Business Rule or Script Include
function processUserRequest(requestData) {
    var errorHandler = new ErrorHandler();
    
    return errorHandler.executeWithErrorHandling(function(context) {
        // Potentially risky operation
        var gr = new GlideRecord('incident');
        if (!gr.get(requestData.incidentId)) {
            throw new Error('Invalid incident ID provided');
        }
        
        // Update incident with validation
        if (!requestData.shortDescription || requestData.shortDescription.length < 10) {
            throw new Error('Short description must be at least 10 characters');
        }
        
        gr.short_description = requestData.shortDescription;
        gr.description = requestData.description;
        var result = gr.update();
        
        return { incidentNumber: gr.number, sysId: result };
        
    }, {
        operationName: 'Update Incident',
        successMessage: 'Incident updated successfully',
        notifyOnError: true,
        genericErrorMessage: 'Unable to update the incident at this time'
    });
}

Client-side

// Client-side script for calling server-side operations with error handling
function callServerOperation(requestData, callback) {
    var ga = new GlideAjax('ErrorHandlerDemo');
    ga.addParam('sysparm_name', 'processUserRequest');
    ga.addParam('sysparm_request_data', JSON.stringify(requestData));
    
    ga.getXMLAnswer(function(response) {
        try {
            var result = JSON.parse(response);
            
            if (result.success) {
                // Handle successful operation
                if (callback && callback.onSuccess) {
                    callback.onSuccess(result.data, result.message);
                }
                
                // Show success message to user
                g_form.addInfoMessage(result.message);
                
            } else {
                // Handle error with user-friendly message
                if (callback && callback.onError) {
                    callback.onError(result.message, result.correlationId);
                }
                
                // Show error message without technical details
                g_form.addErrorMessage(result.message);
            }
            
        } catch (parseError) {
            // Handle JSON parsing errors
            var fallbackMessage = 'An unexpected error occurred. Please refresh the page and try again.';
            g_form.addErrorMessage(fallbackMessage);
            
            if (callback && callback.onError) {
                callback.onError(fallbackMessage, null);
            }
        }
    });
}

The code demonstrates a reusable ErrorHandler class that wraps risky operations in try-catch blocks while providing structured logging and user-friendly error messages. Key features include correlation IDs for tracking errors across logs, contextual error mapping that translates technical errors into helpful user messages, and optional administrator notifications for critical failures. The pattern separates concerns by logging detailed technical information for debugging while returning sanitized messages that don't expose sensitive system details to end users.

Alternatives

Simple Try-Catch with Basic Logging

Use for straightforward scripts where you need basic error handling without the overhead of a full error handling framework. Trade-off is less structured error information and no correlation tracking, but simpler to implement for one-off scripts.

Global Exception Handler with Custom Properties

Implement a system-wide error handler using System Properties for configuration and global Script Includes for consistent behavior. Better for large implementations but requires more initial setup and coordination across development teams.

Promise-Based Error Handling Pattern

Use JavaScript Promises with .catch() methods for handling asynchronous operations and chaining error handling. More modern approach but requires understanding of Promise patterns and may not be suitable for all ServiceNow contexts where traditional callback patterns are expected.

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