ServiceNow REST API Integration Guide

Architecture Overview

Implementation Steps

var rm = new RESTMessageV2('External System Integration', 'POST User');
rm.setStringParameterNoEscape('user_id', current.sys_id);
rm.setRequestBody(JSON.stringify({name: current.name, email: current.email}));
try {
    var response = rm.execute();
    var statusCode = response.getStatusCode();
    if (statusCode == 200 || statusCode == 201) {
        gs.log('User created successfully: ' + response.getBody());
    } else {
        gs.error('API call failed with status ' + statusCode + ': ' + response.getErrorMessage());
    }
} catch (ex) {
    gs.error('REST call exception: ' + ex.getMessage());
}

(function process(request, response) {
    try {
        var requestBody = JSON.parse(request.body.dataString);
        var gr = new GlideRecord('incident');
        gr.short_description = requestBody.title;
        gr.description = requestBody.description;
        gr.caller_id = requestBody.user_id;
        var sysId = gr.insert();
        
        response.setStatus(201);
        response.setBody({success: true, sys_id: sysId, number: gr.number});
    } catch (ex) {
        response.setStatus(400);
        response.setBody({success: false, error: ex.getMessage()});
    }
})(request, response);

function callAPIWithRetry(restMessage, maxRetries) {
    for (var attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            var response = restMessage.execute();
            var statusCode = response.getStatusCode();
            if (statusCode >= 200 && statusCode < 300) {
                return response;
            } else if (statusCode == 429 || statusCode >= 500) {
                if (attempt < maxRetries) {
                    gs.sleep(Math.pow(2, attempt) * 1000); // Exponential backoff
                    continue;
                }
            }
            throw new Error('API call failed with status: ' + statusCode);
        } catch (ex) {
            if (attempt == maxRetries) throw ex;
            gs.sleep(Math.pow(2, attempt) * 1000);
        }
    }
}

function syncPaginatedData(lastSyncTime) {
    var page = 1;
    var hasMoreData = true;
    
    while (hasMoreData) {
        var rm = new RESTMessageV2('External System Integration', 'GET Records');
        rm.setStringParameterNoEscape('page', page.toString());
        rm.setStringParameterNoEscape('limit', '100');
        rm.setStringParameterNoEscape('modified_since', lastSyncTime);
        
        var response = rm.execute();
        var data = JSON.parse(response.getBody());
        
        // Process records
        data.records.forEach(function(record) {
            // Update ServiceNow records
        });
        
        hasMoreData = data.has_more;
        page++;
    }
}

// Health check scheduled job
var healthCheck = new RESTMessageV2('External System Integration', 'GET Health');
try {
    var response = healthCheck.execute();
    var statusCode = response.getStatusCode();
    var responseTime = response.getResponseTime();
    
    // Log metrics
    var gr = new GlideRecord('u_integration_metrics');
    gr.integration_name = 'External System';
    gr.status_code = statusCode;
    gr.response_time = responseTime;
    gr.timestamp = new GlideDateTime();
    gr.insert();
    
    if (statusCode != 200 || responseTime > 5000) {
        gs.eventQueue('integration.health.failure', null, 'External System', 'Status: ' + statusCode + ', Time: ' + responseTime);
    }
} catch (ex) {
    gs.eventQueue('integration.health.error', null, 'External System', ex.getMessage());
}

Common Use Cases

Troubleshooting

Pro Tips

• →Implement correlation IDs in all REST API calls by adding custom headers like X-Correlation-ID with unique values (sys_id or generated GUIDs) to enable end-to-end request tracing across ServiceNow and external systems. This dramatically improves troubleshooting capabilities when issues span multiple systems and allows you to correlate ServiceNow logs with external system logs for comprehensive debugging.
• →Use ServiceNow's Transform Maps with REST integrations by creating Import Set tables that match your API response structure, then leverage the robust Transform Map functionality for complex data transformations, field mappings, and coalescing logic. This approach separates data extraction from data transformation, making your integrations more maintainable and allowing business users to modify field mappings without code changes.
• →Leverage ServiceNow's Event system for asynchronous REST API processing by triggering events from synchronous operations (like Business Rules) and handling the actual API calls in separate Script Actions. This pattern prevents user interface delays, allows for retry logic and error handling without affecting user experience, and enables batch processing of multiple API calls for better performance and rate limit management.
• →Implement circuit breaker patterns in high-volume REST integrations by tracking API failure rates and temporarily disabling API calls when error thresholds are exceeded. Store circuit breaker state in System Properties or custom tables, automatically re-enable after cool-down periods, and use this pattern to prevent cascading failures when external systems experience outages.
• →Create reusable Script Includes for common REST operations like authentication token management, response parsing, and error handling to maintain consistency across multiple integrations. Implement utility functions for common patterns like pagination handling, rate limit detection, and response caching to reduce code duplication and improve maintainability across your REST integration portfolio.
• →Monitor REST integration performance using ServiceNow's Performance Analytics by creating custom metrics that track API response times, success rates, and throughput volumes over time. Set up automated alerting based on performance degradation trends and use these metrics to optimize integration timing, identify capacity planning needs, and demonstrate integration reliability to business stakeholders.

Known Limitations

• —ServiceNow imposes a default limit of 100 concurrent outbound HTTP requests per instance, which can create bottlenecks for high-volume integrations or when multiple integrations compete for connection resources. This limit affects batch processing scenarios and may require implementing queuing mechanisms or request throttling to prevent connection pool exhaustion during peak usage periods.
• —REST Message timeout values have a maximum configuration limit of 300 seconds (5 minutes), which may be insufficient for extremely long-running API operations like large data exports or complex analytical queries. For operations requiring longer processing times, you must implement asynchronous patterns with status polling or use webhook callbacks for completion notification.
• —ServiceNow's JavaScript engine does not support modern ES6+ features in server-side scripts, limiting developers to ES5 syntax and requiring workarounds for advanced JavaScript patterns like async/await, arrow functions, or destructuring. This can make complex JSON manipulation and promise-based API patterns more verbose and harder to maintain compared to modern JavaScript environments.
• —Scripted REST APIs in ServiceNow have limited built-in support for advanced HTTP features like file uploads with multipart/form-data, WebSocket connections, or streaming responses, requiring custom implementations or alternative approaches for these use cases. Large file handling through REST APIs may also encounter memory limitations during processing.
• —ServiceNow's Connection and Credential system does not support some advanced authentication flows like PKCE (Proof Key for Code Exchange) for OAuth 2.0 or mutual TLS authentication, potentially requiring custom authentication implementations using Script Includes or MID Server capabilities. Complex authentication scenarios may need workarounds that reduce the security benefits of the built-in credential management system.

Frequently Asked Questions