Spoke

What It Is

A Spoke is a pre-packaged collection of IntegrationHub actions that provides standardized connectivity to a specific third-party system like Jira, Slack, Microsoft Teams, or AWS. Each Spoke contains purpose-built actions that handle the complexity of API authentication, request formatting, response parsing, and error handling for that system's REST APIs. Rather than building custom REST integrations from scratch, Spokes give you drag-and-drop actions in Flow Designer that abstract away the technical implementation details while exposing only the business-relevant parameters you need to configure.

Architecturally, Spokes live within the IntegrationHub application scope as installable applications from the ServiceNow Store. Each Spoke creates its own scoped application containing action definitions, connection configurations, and supporting scripts that execute within the Flow Designer runtime environment. The actions themselves are stored in the sys_hub_action_type_definition table, while connection credentials are managed through the Connection & Credential framework, ensuring secure credential storage and reusability across multiple flows.

The underlying execution model relies on the IntegrationHub Engine, which processes Spoke actions as discrete units within flow executions. Each action inherits from the base sn_ihub.IntegrationHubAction class and implements specific methods for input validation, API interaction, and output formatting. The engine handles retry logic, timeout management, and logging automatically, while maintaining execution context and variable passing between flow steps. Connection pooling and rate limiting are managed at the platform level, ensuring that multiple concurrent flows don't overwhelm external systems.

You cannot function without Spokes when your organization requires reliable, maintainable integrations with popular third-party systems at scale. While you could build custom REST messages and scripted integrations, Spokes provide enterprise-grade error handling, automatic retry mechanisms, and built-in logging that would take months to develop and test properly. They become essential when you need to maintain dozens of integration points across multiple teams, as they provide consistent patterns, reduce technical debt, and ensure that API changes from vendors are handled through centralized updates rather than scattered custom code modifications.

Platform owners install and manage Spoke applications from the ServiceNow Store, handling version updates and connection configuration templates. ServiceNow administrators configure the connection credentials, set up credential stores, and manage access controls for who can use which Spokes in their flows. Developers and citizen developers consume the Spoke actions within Flow Designer, configuring business logic and data mapping without needing to understand the underlying API implementations. This separation of concerns ensures that technical complexity is centralized while business users can focus on process automation.

Recent ServiceNow releases have significantly expanded the Spoke ecosystem, with Vancouver introducing enhanced connection management and credential aliasing for multi-tenant scenarios. Xanadu added improved error handling patterns and better support for OAuth 2.0 flows with automatic token refresh. The Utah release introduced Spoke action versioning, allowing you to pin flows to specific action versions while testing newer versions in development environments, preventing production breaks when Spoke updates change behavior or input requirements.

Where to Find and Configure It

Install Spokes from System Applications > All Available Applications > All where you'll find ServiceNow Store applications including official Spokes like Jira, Slack, and Microsoft Teams. After installation, manage the Spoke application itself through System Applications > My Company Applications to handle updates, deactivation, or configuration review.

Configure Spoke connections at Connections & Credentials > Connections where you'll create new connection records that reference the appropriate credential records for authentication. Access the available Spoke actions through Process Automation > Flow Designer by adding an Action step and searching for your installed Spoke name. View the underlying action definitions and their input/output schemas at Process Automation > IntegrationHub > Action Definitions for troubleshooting and advanced configuration needs.

Monitor Spoke execution and troubleshoot issues through Process Automation > Flow Designer > Executions where individual action steps show input/output data and error details. Check connection health and credential validity at Connections & Credentials > Connection Health which provides connection testing and authentication status. For scoped applications, Spoke actions are only visible within Flow Designer when your current application scope matches or has access to the Spoke's application scope.

How It Works Step by Step

When a Flow Designer execution reaches a Spoke action, the IntegrationHub Engine first validates all input parameters against the action's defined schema, checking data types, required fields, and any custom validation rules. The engine then retrieves the associated connection record and resolves credential information, handling OAuth token refresh or basic authentication as needed. If credential resolution fails or the connection is marked unhealthy, the action fails immediately with a detailed error message.

Once authentication is confirmed, the action's custom implementation code executes within a sandboxed environment, constructing the appropriate HTTP request with headers, body, and query parameters specific to the target system's API requirements. The platform handles SSL certificate validation, proxy configuration, and timeout management automatically. Response data is parsed and transformed according to the action's output schema, with successful results mapped to output variables and errors captured for retry logic or flow exception handling.

The execution context maintains state throughout this process, logging detailed information about request/response cycles, timing data, and any transformation steps. If the action succeeds, output variables are populated and made available to subsequent flow steps. If it fails, the engine determines whether to retry based on the error type and action configuration, with exponential backoff for rate limiting scenarios and immediate failure for authentication or configuration errors.

The Execution Order

1. Flow Designer passes execution control to the IntegrationHub Engine when reaching a Spoke action step
2. Engine validates input parameters against the action's schema definition, checking data types and required fields
3. Connection record is retrieved and credential information is resolved, including OAuth token refresh if needed
4. Action's custom implementation code executes, constructing HTTP request with proper headers and authentication
5. HTTP request is sent through ServiceNow's proxy infrastructure with SSL verification and timeout handling
6. Response is received and parsed, with data transformation applied according to output schema definitions
7. Success results populate output variables for subsequent flow steps, while errors trigger retry logic or flow exception handling
8. Execution control returns to Flow Designer with populated output variables or error context for flow continuation

// Typical pattern within a custom Spoke action implementation
(function execute(inputs, outputs) {
    var request = new sn_ws.RESTMessageV2();
    request.setEndpoint(inputs.connection.endpoint + '/api/issues');
    request.setHttpMethod('POST');
    request.setRequestHeader('Content-Type', 'application/json');
    request.setRequestHeader('Authorization', 'Bearer ' + inputs.connection.token);
    
    var requestBody = {
        summary: inputs.summary,
        description: inputs.description,
        project: { key: inputs.project_key },
        issuetype: { name: inputs.issue_type }
    };
    request.setRequestBody(JSON.stringify(requestBody));
    
    var response = request.execute();
    if (response.getStatusCode() == 201) {
        var responseBody = JSON.parse(response.getBody());
        outputs.issue_key = responseBody.key;
        outputs.issue_url = responseBody.self;
        outputs.success = true;
    } else {
        outputs.success = false;
        outputs.error_message = 'Failed to create issue: ' + response.getErrorMessage();
    }
})(inputs, outputs);

Real-World Scenarios

Automated Jira Ticket Creation from ServiceNow Incidents

Your development team uses Jira for backlog management but incidents are logged in ServiceNow, requiring manual ticket creation that delays response times. You need automated Jira issue creation when high-priority incidents are assigned to the development team, maintaining bi-directional linking for status updates.

Install the Jira Spoke from the ServiceNow Store and create a connection using a Jira service account with project creation permissions. Configure a Flow Designer flow triggered by incident updates where priority equals 1 - Critical and assignment_group contains 'Development'. Add the Create Issue action, mapping ServiceNow incident fields to Jira issue fields, then use the Update Record action to populate the incident's work_notes with the created Jira issue key and URL.

Watch for Jira project permission changes that can break the integration silently, as the Spoke will return generic authentication errors rather than specific permission failures. Test field mapping thoroughly since Jira custom fields vary by project and the Spoke doesn't validate field availability at design time. Set up proper error handling to prevent flow failures when Jira is unavailable, using flow logic to retry after delays or create manual tasks for follow-up.

Slack Channel Notifications for Major Incident Response

Your incident response team needs immediate Slack notifications when P1 incidents are created, including dynamic channel routing based on affected services and rich message formatting with incident details. Email notifications are too slow and lack the collaborative context needed for rapid response coordination.

// In Flow Designer, create a Script step before the Slack action
var message = {
    text: 'P1 Incident Alert: ' + fd_data.trigger.incident.short_description,
    blocks: [
        {
            type: 'header',
            text: {
                type: 'plain_text',
                text: 'P1 Incident: ' + fd_data.trigger.incident.number
            }
        },
        {
            type: 'section',
            fields: [
                { type: 'mrkdwn', text: '*Priority:* ' + fd_data.trigger.incident.priority.getDisplayValue() },
                { type: 'mrkdwn', text: '*Assigned Group:* ' + fd_data.trigger.incident.assignment_group.getDisplayValue() },
                { type: 'mrkdwn', text: '*Affected Service:* ' + fd_data.trigger.incident.business_service.getDisplayValue() },
                { type: 'mrkdwn', text: '*Reporter:* ' + fd_data.trigger.incident.caller_id.getDisplayValue() }
            ]
        },
        {
            type: 'actions',
            elements: [{
                type: 'button',
                text: { type: 'plain_text', text: 'Open Incident' },
                url: 'https://yourinstance.service-now.com/incident.do?sys_id=' + fd_data.trigger.incident.sys_id
            }]
        }
    ]
};
fd_data.slack_payload = JSON.stringify(message);

Monitor Slack API rate limits carefully as the platform enforces strict message frequency limits that can cause action failures during incident storms. Validate channel names dynamically since Slack channels can be archived or renamed without ServiceNow awareness, causing silent delivery failures. Consider using Slack's incoming webhook URLs for simpler authentication if you don't need advanced features like user lookups or channel management, as they're more resilient to Slack workspace changes.

Microsoft Teams Integration for Change Approval Workflows

Your change approval process requires CAB members to review change requests within Teams channels where they're already collaborating, rather than forcing them to log into ServiceNow for every approval decision. You need interactive approval cards that update automatically and maintain audit trails back to the change record.

Install the Microsoft Teams Spoke and configure OAuth 2.0 authentication with proper Microsoft Graph API permissions for channel posting and adaptive card creation. Create a flow triggered when change requests move to Pending Approval state, using the Post Adaptive Card to Channel action with JSON payload containing change details and approval buttons. Configure a second flow triggered by the card response webhook to update the change record approval state and post confirmation messages back to the Teams channel.

Microsoft Graph API permissions can be revoked or modified by Office 365 administrators without notice, breaking integration silently until users report missing notifications. Teams channel membership changes frequently, so implement fallback logic to post to default channels when target channels become inaccessible. Test adaptive card JSON schemas thoroughly in the Teams developer portal before deployment, as malformed cards fail silently and appear as blank messages to users.

The Classic Mistake

// Multiple flows all using the same 'Jira Production' connection
// Flow 1: User Onboarding - creates 500 tickets/hour
// Flow 2: Incident Sync - processes 200 incidents/hour  
// Flow 3: Change Approval - handles 100 changes/hour
// Flow 4: Asset Discovery - bulk updates 1000 assets/hour

// Each flow configured with:
var connection = 'Jira Production Connection';
var auth = 'jira_service_account';

// All flows trigger simultaneously during business hours
// Connection limit: 10 concurrent requests
// Actual load: 1800 requests/hour = 30+ concurrent
// Result: Connection pool exhaustion

// Symptom: Random spoke action failures
// Error: 'Connection timeout' or 'Too many requests'
// User sees: Tickets not created, sync failures

This fails because spoke connections have finite connection pools—typically 10-50 concurrent connections depending on the target system's API limits. When multiple high-volume flows share the same connection credential, they compete for the same pool, causing timeouts and failures that appear random to users. ServiceNow doesn't queue the requests intelligently; it simply fails them when the pool is exhausted. The mistake is non-obvious because individual flows work perfectly in testing, and the failures only appear under production load when multiple flows run simultaneously.

// Separate connections by flow category and volume

// High-volume bulk operations
var bulkConnection = 'Jira Bulk Operations';
var bulkAuth = 'jira_bulk_service_account';

// Real-time user-facing flows  
var realtimeConnection = 'Jira Realtime Sync';
var realtimeAuth = 'jira_realtime_account';

// Scheduled batch processes
var batchConnection = 'Jira Scheduled Batch';
var batchAuth = 'jira_batch_account';

// Each connection configured with appropriate:
// - Connection timeout: 30s (bulk), 10s (realtime), 60s (batch)
// - Max connections: 20 (bulk), 10 (realtime), 5 (batch)
// - Different service accounts with appropriate API quotas
// - Separate credential records in Connection & Credential aliases

When to Use This vs Alternatives

Use Spokes when you need bidirectional, real-time integration with structured data operations (CRUD) on external systems within Flow Designer workflows. Spokes excel at user-initiated processes where you need to create, update, or query records in external systems as part of a ServiceNow business process, with built-in error handling and credential management.

Choose Spokes Over REST Messages When

You're building Flow Designer workflows that need pre-built authentication, error handling, and data transformation for common third-party systems like Jira, Slack, or AWS. Spokes provide declarative configuration instead of custom scripting, include automatic retry logic, and handle OAuth token refresh automatically. REST Messages require you to build all authentication, error handling, and data parsing manually in Business Rules or Script Includes, making Spokes the superior choice for standard integrations within flows.

Use REST Messages Instead When

You need server-side scripting integration (Business Rules, Script Actions, Scheduled Jobs) or highly customized API interactions that don't fit spoke action patterns. REST Messages work in all scripting contexts, support complex authentication schemes, and allow complete control over request/response handling. You also need REST Messages for custom APIs that don't have ServiceNow-provided spokes, or when you need to integrate from server-side scripts rather than Flow Designer.

Use Both Together When

You have user-initiated processes in Flow Designer using Spokes for standard operations, plus server-side automation using REST Messages for bulk operations or complex business rules. For example, use Jira Spoke in flows for ticket creation from Service Catalog requests, while using REST Messages in scheduled jobs for bulk synchronization of existing tickets. The spoke handles user-facing workflow integration while REST Messages handle backend data synchronization.

Platform Interactions & Side Effects

• Creates execution records in sys_hub_action_status table for every spoke action execution, including input/output data, execution time, and error details, which can consume significant database space in high-volume environments
• Spoke credential lookups bypass normal ACL enforcement and use the connection_admin role context, meaning spoke actions can access credentials that the triggering user couldn't normally view
• HTTP requests from spokes appear in System Log > Outbound HTTP Requests with the source identified as IntegrationHub, not the original user or flow context
• Spoke installations create entries in sys_app and sys_app_module tables and are automatically included in update sets when configuration changes are made, potentially causing unwanted spoke updates in target instances
• Flow execution failures in spoke actions don't trigger standard notification schemes but can be monitored through Event Management if you configure custom event rules for the syshub.action.failed event
• Connection pooling for spokes operates at the MID Server level for agent-based connections, meaning connection limits are per-MID Server, not per-instance, affecting load balancing strategies
• Spoke action timeouts respect both the spoke configuration timeout AND the Flow Designer execution timeout (glide.flow.max_execution_time), whichever is shorter, causing unexpected timeouts in long-running integrations
• OAuth token refresh for spoke connections happens automatically but writes to sys_auth_profile_oauth_token table using elevated privileges, which can mask authentication issues during development
• Spoke credential aliases maintain references in sys_alias table that become invalid if the underlying credential record is deleted, causing spoke actions to fail with unclear error messages
• Spoke action outputs are limited to 1MB of data and automatically truncated, which silently breaks flows that expect complete datasets from APIs returning large responses

Debugging and Troubleshooting

The most common failure symptoms include flows showing "Completed" status but spoke actions failing silently, users reporting that external system records weren't created despite successful ServiceNow workflow completion, and intermittent "Connection timeout" errors that seem random. Admins typically see generic error messages like "Action failed to execute" in Flow Designer execution details, while users experience workflows that appear to work but don't achieve the expected integration results.

For detailed diagnosis, start with System Log > All filtered by source "IntegrationHub" to see actual HTTP request/response details. Check the sys_hub_action_status table for execution records containing complete input/output data and error stack traces. Enable debug logging by setting com.snc.integration.single_step_approval.log.level=debug for comprehensive spoke execution logging.

Look for specific error patterns: "Authentication failed" indicates credential or OAuth token issues, "Connection pool exhausted" means too many concurrent requests to the same connection, and "Response truncated" signals that API responses exceed the 1MB spoke output limit. HTTP 429 errors in the system log indicate rate limiting by the target API, while HTTP 401/403 errors point to authentication or authorization problems with the configured service account.

Diagnostic Checklist:

• Verify the spoke is installed and activated in System Applications > All Available Applications > All with status "Activated"
• Test the connection credential independently using Connections & Credentials > Connections and click "Test Connection"
• Check sys_hub_action_status.state field for the specific execution—"failed" indicates spoke-level failure, "successful" with wrong results suggests data mapping issues
• Review System Log > Outbound HTTP Requests for the actual API calls, response codes, and response body content
• Validate Flow Designer variable data types match spoke action input requirements—strings vs objects vs arrays cause silent failures
• Confirm MID Server status and version compatibility if using agent-based spokes like ServiceNow or database connections
• Check target system API quotas and rate limits—many spoke failures are actually external system throttling that appears as ServiceNow errors

Quick Reference

• Spoke action outputs are automatically JSON-parsed into Flow Designer variables, but input values must be explicitly cast to strings if the target API expects string data types
• Connection aliases can reference the same credential record multiple times, but each alias maintains independent connection pooling and timeout settings
• OAuth token expiration is handled automatically by spokes, but the initial token acquisition must be done manually through the connection test interface
• Spoke installation from the App Store requires admin role but spoke configuration and use only requires flow_designer and connection_admin roles
• Spoke actions execute with elevated privileges and can bypass ACLs, making them potential security risks if connection credentials are compromised
• The maximum response size for spoke actions is 1MB—larger responses are silently truncated, not failed, which can cause data integrity issues
• Spoke execution history is retained in sys_hub_action_status for 30 days by default, controlled by the glide.hub.action_status.cleanup.age property
• Spoke updates from ServiceNow Store automatically appear in update sets and will be deployed to target instances unless explicitly excluded
• Connection pooling limits are per-credential, not per-spoke, so multiple spokes using the same credential share the same connection pool
• Failed spoke actions don't automatically retry—retry logic must be built into the Flow Designer workflow using conditional logic and loop structures