ServiceNow ADP Integration Guide

Architecture Overview

Implementation Steps

// Test script to verify spoke installation and connectivity
var worker = new sn_hr_integrations.ADP();
worker.setConnection('ADP_Workforce_Now_Prod');
try {
    var response = worker.getWorker('test-associate-id');
    gs.info('ADP Connection successful: ' + response.getBody());
} catch (e) {
    gs.error('ADP Connection failed: ' + e.message);
}

// Transform script for ADP to ServiceNow user mapping
(function transformADPWorker(source, target) {
    // Map basic user information
    target.first_name = source.u_adp_data.person.legalName.givenName || '';
    target.last_name = source.u_adp_data.person.legalName.familyName1 || '';
    target.email = source.u_adp_data.person.personalCommunication.emails[0].emailUri || '';
    target.employee_number = source.u_adp_data.associateOID || '';
    
    // Handle work assignment data
    if (source.u_adp_data.workAssignment && source.u_adp_data.workAssignment.length > 0) {
        var workAssign = source.u_adp_data.workAssignment[0];
        target.title = workAssign.positionTitle || '';
        target.department = workAssign.organizationalUnits[0].nameCode.shortName || '';
    }
})(source, target);

(function process(request, response) {
    var requestBody = request.body.data;
    var signature = request.getHeader('X-ADP-Signature');
    
    // Verify webhook signature
    var expectedSig = gs.generateHMAC('HmacSHA256', requestBody, gs.getProperty('adp.webhook.secret'));
    if (signature !== expectedSig) {
        response.setStatus(401);
        return;
    }
    
    var eventData = JSON.parse(requestBody);
    var eventType = eventData.eventNameCode.codeValue;
    
    switch(eventType) {
        case 'worker.hire':
            triggerNewHireProvisioning(eventData.data.transform.worker);
            break;
        case 'worker.terminate':
            triggerTerminationWorkflow(eventData.data.transform.worker);
            break;
        default:
            gs.log('Unhandled ADP event type: ' + eventType);
    }
    
    response.setStatus(200);
})(request, response);

// Workflow script to trigger onboarding based on ADP hire event
(function triggerNewHireProvisioning(workerData) {
    var gr = new GlideRecord('sn_hr_core_case');
    gr.initialize();
    gr.subject = 'New Hire Onboarding: ' + workerData.person.legalName.formattedName;
    gr.opened_by = gs.getUserID();
    gr.u_employee_id = workerData.associateOID;
    gr.u_hire_date = workerData.workAssignment[0].actualStartDate;
    gr.u_department = workerData.workAssignment[0].organizationalUnits[0].nameCode.shortName;
    gr.state = 'new';
    
    var caseId = gr.insert();
    
    // Trigger equipment provisioning workflow
    var wf = new Workflow();
    wf.startFlow('hr_new_hire_provisioning', caseId, {
        'employee_type': workerData.workAssignment[0].assignmentStatus.statusCode.codeValue,
        'start_date': workerData.workAssignment[0].actualStartDate
    });
})(workerData);

// Monitoring script for ADP integration health check
var monitor = new GlideRecord('sys_flow_history');
monitor.addQuery('flow_name', 'CONTAINS', 'ADP');
monitor.addQuery('state', 'failed');
monitor.addQuery('sys_created_on', '>=', gs.daysAgoStart(1));
monitor.query();

if (monitor.getRowCount() > 0) {
    var alertGr = new GlideRecord('sys_alert');
    alertGr.initialize();
    alertGr.message = 'ADP Integration failures detected: ' + monitor.getRowCount() + ' flows failed in last 24 hours';
    alertGr.type = 'error';
    alertGr.source_table = 'sys_flow_history';
    alertGr.insert();
}

Common Use Cases

Troubleshooting

Pro Tips

• →Implement incremental synchronization by storing ADP's lastModifiedTimestamp values in ServiceNow custom fields and using them as filter parameters in subsequent API calls to reduce processing time and API consumption. This approach dramatically improves sync performance for large employee populations and helps stay within ADP's rate limits while ensuring no updates are missed.
• →Create custom Business Rules on the sys_user table to automatically trigger Integration Hub flows when specific employee data changes occur in ServiceNow, enabling bidirectional synchronization for approved use cases like emergency contact updates or address changes. Use the 'when' condition to filter for human-initiated changes versus automated integration updates to prevent infinite loops.
• →Leverage ServiceNow's Data Lookup Definitions to create real-time ADP data validation for HR Service Delivery forms, allowing HR representatives to verify employee information against ADP without full synchronization delays. Configure lookup tables for common validation scenarios like manager verification, cost center validation, and employment status confirmation that can be called from catalog items and HR cases.
• →Implement comprehensive error handling in your Integration Hub flows using Try-Catch-Finally patterns with custom error logging to ServiceNow tables, enabling detailed troubleshooting and automated retry mechanisms for transient failures. Create dashboard views of integration errors with drill-down capabilities to specific failed employee records and their associated ADP payloads for efficient issue resolution.
• →Use ServiceNow's Flow Variables and data pills strategically to pass complex ADP JSON structures between flow steps without repeated API calls, improving performance and reducing the risk of data inconsistency during multi-step processing. Store frequently accessed ADP lookup data like organizational units and job codes in ServiceNow reference tables for fast local lookups during employee provisioning workflows.
• →Configure Connection Alias health monitoring using scheduled Integration Hub flows that perform lightweight ADP API calls and update ServiceNow health status indicators, enabling proactive identification of authentication issues before they impact production employee processes. Set up automated notifications to integration administrators when connection health degrades or authentication tokens approach expiration.

Known Limitations

• —ADP Workforce Now API enforces strict rate limits of 1000 requests per hour per application, which can be restrictive for large organizations requiring frequent synchronization of extensive employee populations. The Integration Hub spoke includes throttling mechanisms, but initial data migrations or comprehensive synchronization may require careful batch planning and extended processing windows to avoid hitting these limits.
• —The ADP API provides read-only access to employee data for most integration scenarios, preventing bidirectional synchronization of employee-initiated changes from ServiceNow back to ADP without additional custom development. Organizations requiring write-back capabilities for employee self-service updates must implement separate approval workflows that create ADP update requests rather than direct API modifications.
• —Complex organizational structures with matrix reporting relationships or multiple concurrent work assignments may not translate seamlessly to ServiceNow's simpler user-manager hierarchy model. The integration requires custom transformation logic to handle scenarios like dual reporting relationships, temporary assignments, and complex cost center allocations that don't have direct ServiceNow equivalents.
• —ADP webhook delivery reliability depends on network connectivity and endpoint availability, with no built-in queuing mechanism for failed webhook attempts beyond ADP's standard retry policy. Organizations must implement custom webhook replay capabilities or supplement real-time webhooks with periodic batch synchronization to ensure no employee lifecycle events are missed during system outages.
• —The integration requires ongoing maintenance for ADP API version updates and ServiceNow platform upgrades, as both systems evolve their data models and authentication mechanisms independently. Integration Hub spoke updates may lag behind ADP API changes, requiring custom REST message implementations for accessing newer ADP features or data fields not yet supported by the official spoke.

Frequently Asked Questions