Integration Hub Spokes and How to Build Them

[Joe Wilmoth]

Integrate ServiceNow with modern systems quickly 

Traditionally, integrations are complex and expensive to maintain. Integration Hub reduces complexity, allowing you to integrate ServiceNow with API-based systems faster. Advantages of using Integration Hub over scripted API approaches and iPaaS vendors include:  

• Faster time to value – on average 3X faster than using a general purpose iPaaS 
• Remove integration complexity with out of the box spokes and flow templates built into Flow Designer, Virtual Agent Designer, and App Engine Studio 
• Reduce integration costs – low code environment reduces reliance on high-cost, specialized integration engineers and integration COEs, and enables more types of ServiceNow developers – e.g., low code admins, IT generalists, and no-code process analysts – to integrate ServiceNow workflows with other systems 
• Build advanced, custom integrations for differentiated use cases in Action Designer 

Capabilities that scale with your business 

Integration Hub is packaged by solutions and flow templates, spokes, and custom integration capabilities. Let’s focus on the approach: 

• Flow templates – pre-built templates for common integration patterns with guided setup to rapidly add automation to apps in App Engine Studio – available in the ServiceNow Store 
• Out-of-the-Box Spokes 

• Integrate data and automate thousands of actions in critical business systems with readymade spokes – application specific sets of actions and subflows - in the ServiceNow store. 

• Custom Spokes 

• Create powerful custom integrations for any use case. 

ServiceNow’s Out-of-the-Box spokes contain actions and sub-flows aligned with the most 

common API functions for the third-party system. These Spokes are developed, maintained, and 

certified for new releases by ServiceNow, significantly reducing integration complexity and total 

most of ownership. Public facing Packaging information can be found here: 

Integration Hub Overview document on Legal Schedules 

Spokes 

A spoke is a logical grouping of related actions, subflows, and supporting application files to enable communication with a specific application or system. For example, the Slack Spoke includes actions to post messages, incidents, problems, change details, and more, to a Slack channel. 

A spoke is essentially a scoped application, the same as when you use our legacy features to build an integration. The difference is that, the spoke contains actions, sub-flows and flow templates – along with any supporting application files. Whereas using our legacy integration capabilties (Outbound REST, Scripted REST, RESTMessagev2, etc.) has far more complexity, no built-in functionality to track usage, and multiple points of engagement with no easy way to create multiple workflow opportunities for the same integration. A spoke can be accessed directly from Flow Designer to be used in multiple workflows. A flow may contain actions or subflows from multiple spokes depending on use-case. 

There are currently 180+ Integration Hub spokes available. 

What if a ServiceNow spoke doesn’t contain the functionality needed? 

When an existing spoke doesn’t contain actions or sub-flows that align with the API functions needed for the integration, you can use the spoke as a guideline to extend, design and build a custom spoke, clone existing actions to add additonal functionality or create new actions within the scope of the existing spoke. 

Note: A MID Server is required to communicate with or move data between a ServiceNow instance and external applications, data sources, and services in your network behind a firewall. 

ServiceNow does not allow direct customization of Out-of-the-Box spoke actions – we offer the spokes to address core API functionality for the third-party system and if the spoke does not offer that functionality, you can reference the actions and sub-flows to build a custom spoke and/or clone or develop new spoke actions within the scope of the spoke.  

You can create a custom spoke to pair with an existing spoke or if a spoke for your system doesn’t exist – create a standalone custom spoke. ServiceNow recommends creating a new Update Set within the scope of the spoke you are utilizing and cloning or creating new actions  – this allows for rapid development and simple maintenance by allowing the reuse of connections and you can find it alongside other actions in the same spoke when browsing the action picker in Flow Designer. When extending or cloning baseline functionality from a spoke – create a new process to review and test changes made with new versions of the spoke you are extending or cloning from. This will ensure you always have the most recent feature releases in your custom spokes and actions. 

Note: When creating or cloning actions within the scope of an existing spoke, you may want to name the new action something that reflects the new behaviour to alleviate any confusion when selecting an action in the Flow Designer action picker. 

Integration Hub spokes make integrations reusable by multiple workflows in an enterprise, because you can access spoke actions and sub-flows from Flow Designer in the Action menu. Using Flow Designer to run integrations also alleviates the need to develop business rules and other scripts that fire on insert/update to the database, and replacing scripts with flows makes upgrades easier. 

Check out the REST in IntegrationHub training to dive into extending, building and understanding custom spokes and actions with Integration Hub. 

Spoke Generator 

Customers and Developers are always looking for effective ways to create new Spokes that connect the Now Platform to external systems. Traditionally, they’ve had to rely on creating scripted approaches to quickly create new integrations, without using Integration Hub capabilities like Action Designer. 

Spoke Generator takes out the manual steps, reducing risk and enabling you to generate Spokes with advanced features without generating code – greatly reducing the implementation time and offering Spokes at a lower cost. 

Spoke Generator offers a guided experience for building Spokes – using OpenAPI 2.0 and OpenAPI 3.0 specifications to quickly build integrations with external applications and systems that support OpenAPI. 

What is OpenAPI? 

• The OpenAPI specification defines the structure and syntax for an API in a way that is not dependent on the programming language the API has been created with. 
• You can use OpenAPI specification to generate client code – like you see when building Spokes with Spoke Generator on the ServiceNow Platform. 
• The OpenAPI specification is typically written in YAML or JOSN format. 

In summary, OpenAPI specification is an open standard for describing your APIs, that enables transfer of knowledge from API provider to API consumer. 

Connection Attributes 

Define connection-specific variables that you can use in Integration Hub integration steps when building Spokes. When using an integration step, you must establish a connection with an external system. It is a ServiceNow Best Practice to use a Connection and Credential alias 

instead of defining the connection inline. An alias enables you to update the connection details once without having to reconfigure the connection for each action. 

MID Server Connection Aliases 

Action designers can set MID Server selection attributes using a connection record associated with an alias and associate the alias with an integration step. When the flow runs, the system uses the attributes to determine which MID Server runs the step. 

Design integration steps using the following guidelines: 

• Avoid shifting the execution environment between the instance and the MID Server multiple times. Where possible, group similar action steps. For example, group core steps that perform record operations and integration steps that run on the MID Server. 
• When creating a spoke that uses an integration step, include a Connection and Credential alias record with the appropriate connection type. Before anyone can use the Spoke, a user with the connection_admin role must associate the alias record to a connection record that supports the connection type. If defining the connection inline, use inputs to enable the process analyst to define the conection information when adding the action to a flow in Flow Designer. 
• The MID Server does NOT have access to all the values in a GlideRecord object, it only has access to the sys_id reference. Inputs of type ‘Reference’ do not work on a MID Server. Instead, create action inputs that contain the necessary GlideRecord values. 

Transactions 

An Integration Hub Transaction is defined as any outbound call originating from Integration Hub, FlowDesigner, Remote Tables and/or Orchestration. This includes any operation, action, orchestration from Integration Hub, Remote Tables or Orchestration resulting in an outbound call.  

Note: Legacy web services features such as RESTMessageV2 do not consume Integration Hub transactions outside of Flow Designer. 

Custom Spoke Development Standards & Best Practices 

Application Scoping 

• Create only one Scoped Application for a Spoke – the spoke should be responsible for doing a specific integration. 

Connection and Credential Alias 

• Alias should be created in the scope of the Spoke. 
• The name of the alias should be the name of the spoke. Do NOT include “spoke”. 

Inbound Webhook Authentication / Callbacks 

• Webhooks 
  • Webhooks are implemented as Scripted REST API protected by an authentication mechanism – basic or token based. 

• Polling 
  • Using a scheduled flow, check remote system for updates. This is useful when you do not have access to setup a callback from the third-party system. 

• Email 
  • Inbound Email Trigger/Flow 
    • Most remote systems support sending email when an event occurs. 
    • Inbound email flow can either: receive the lookup ID of the object of interest, then do an outbound call to fetch the details or parse the email for data of interest. 

• Example: 
  • Create a Webhook in ServiceNow using Scripted REST API. 
  • Protect the API with an Authentication Mechanism. 
  • Register the Webhook as a listener in the targeted system. 
  • Invoke a Flow when the listener is fired. 

Creating Actions 

• Actions should be created in the spokes that are relevant. Do not duplicate the same action in multiple spokes. 
• By default, set scope access to “Accessible from all scopes” in actions. 
• Actions should have a category. 
• Actions must be published. 
• Every Action MUST have a unique name in its scope. 

Naming Actions 

• Action name should be “human readable”. 
• Words in action names should be separated by a space, every word should begin with an uppercase character. 
• Use “Look Up” as the prefix if the purpose of the action is to search for objects. 
• Use “Get” as the prefix if the purpose of the action is to get details of an object. 

Categorizing Actions 

• Each Action should ideally be associated with a Category unless there are only 1-2 Actions in a spoke. 
• It’s OK to keep an Action under the default Category if it doesn’t belong to any Category. 

Designing Steps 

• Pre-processing and error handling should be done in separate Script Includes which need to be called from Action Designer script steps. 
• Code repetition should be carefully eliminated. 
• Error handling step must validate all the outputs of REST steps for NULL values before using them in further processing. 
• Provide a default error message which will be used as a fall back. 
• Remove NULL inputs from request body – please remove inputs which are not defined from the request body. 

REST Steps 

• Use binary type and multipart type of REST step to transfer attachments to third-party system. 
• Use the Version variable declared in Connection Attributes. 
• Only have a single integration call in an Action.

*Note: Resource Path in the REST Step is encoded. 

JDBC Steps 

• The JDBC step in a regular action has a ~5MB limit on the amount of data it can process. This can be used for simple CRUD actions or single-record lookups but should NOT be used for large datasets. 

To handle larger datasets, use the Data Stream action, which also supports the JDBC step. This can handle millions of records/gigabytes of data. 

When consuming these actions, for large datasets, Import Sets should be used, and Integration Hub Import provides an easy and simple user interface to use. Data Sources have an Integration Hub Data Stream source option that lets you choose an Integration Hub data stream as the source of data for the import set. 

While you can consume data stream actions in flow, this is not recommended for very large datasets. 

Performance of JDBC Data Stream via MID Server was enhanced significantly in the San Diego release. Providing a ~20% performance increase on how quickly result sets are shipped from the MID Server back to the instance. 

Error Handling 

• Decouple platform error messages from API error messages. 
• Make error messages understandable to the Process Analyst. 
• Error messages should be short and self-explanatory. 
• Incorporate all error messages that the API returns in the Action description. 

Script Includes 

• Should NOT be client callable. 
• If Script Includes need public access or cross-scope functionality, please use Scripted REST API and call Script Includes from it. 
• Create separate Script Includes for utilities and Error handling. 

Action Steps 

• A typical Action generally has these steps: 

• Inputs 

• Specify the inputs needed for your action. 

• Input Pre-Processing and Validation 

• Use this to validate inputs (Does it contain spaces or non-valid characters?). 

• Steps relating to the Action objective 
• Error/Response handling 

• Use this for handling the response from the previous steps. 

• Outputs 

• Use this to specify the final outputs of the action. 

• After you have finished making an Action, go to properties and make it Read-Only. 
• Save and Publish the Action. 

To learn additional information about Flow Designer Best Practices: https://sn.works/CoE/BPFlow