What We’ve Got Here Is Failure to Communicate – Part 1

Good Practices for Designing Integrations in ServiceNow

Captain: You can have the easy way, Luke… Or you can have it the hard way… It’s all up to you. – Cool Hand Luke

If you work in a ServiceNow environment in 2023, it’s more than likely you’ve got it integrated with other systems. Given ServiceNow’s place in the market, it’s unlikely that an instance is running in an environment small enough or segregated enough to not need to be integrated with other systems. At the very least, you’re likely getting your core data from somewhere outside of ServiceNow, and hopefully not through a manual import. (Who wants to keep up with that effort?) You may be using a “good old” LDAP integration, or you may be using middleware, or an Integration Hub pre-built solution. Regardless of the solution, I’m going to use the rest of this article to talk about good practices for how integrations should be designed in ServiceNow so that your applications, and indeed the platform as a whole, are protected from possible integration chaff, and so they can be easily extended by non-coders when the need arises. I’ll primarily cover custom Web Service integrations, with the intention that if you understand how to design these kinds of integrations the knowledge translates well to all integrations.

In Part 1 of this article, I’ll delve into Inbound and Outbound design considerations, and in Part 2, I’ll cover considerations for a true eBonding type integration as well as other general tips I’ve learned through the years building integrations.

A quick bit of “curriculum vitae” to establish my bona-fides: I’ve been doing ServiceNow integrations since 2011; I was one of the early ServiceNow Professional Services consultants to delve into integration work. I developed one of the first AT&T eBonding integrations and gave the code and configuration to ServiceNow development to leverage as a packaged offering. I also built the ServiceNow side of the Workday to ServiceNow connector for Workday (the company). I’ve focused primarily on SOAP (early on) and REST based Web Service integrations. I also helped build the first iteration of the Perspectium DataSync tool.

Baseline Knowledge

This article assumes the reader has a baseline knowledge of how to do integrations, both in general and in ServiceNow. It also assumes you have knowledge of the various ways that ServiceNow does, or can do, integrations “out of the box”.

The examples in this article are based on Diagram 1. The example is a bi-directional application to application integration and includes the following:

• The REST protocol with JSON payloads
• A Web Service Import Set to stage the inbound data
• An integration with a Task-based application in ServiceNow
• A field mapping table to manage inbound and outbound data updates

Inbound: Default to Using a Staging Table

You should always default to staging the inbound data in Web Service Import Sets (WSIS). These are nothing more than Import Set tables with a slightly extended API. (I’ve honestly never needed anything more than the standard API calls when using these tables.) Here are the reasons these tables should be the place to integrate into ServiceNow:

• Staging the data insulates your application tables from data issues with inbound integrations. This allows you to build both data and logic safeguards into your integration. External systems can use the WSIS Table APIs to inject data into ServiceNow, where it waits to be transformed into application or core-specific data. Transform logic can ensure that bad or malformed data doesn’t make its way into your SN processes, preventing potential SN instance issues.
• Staged data in WSIS can be transformed like any import set. This means SN administrators who may not be familiar with Web Services or integration design in general can still configure transform maps and transform logic. Many of the future changes to the integration can be handled by anyone who can maintain transform maps.
• Staged data can be used for troubleshooting integration issues: If there’s an issue with the integration after the inbound request has reached ServiceNow, the import set record serves as an auditable trace of the raw data received. Often issues can be solved by a review of this data, e.g “Hey we agreed you’d send the data in format YYYY-MM-DD and you sent MM-DD-YY.” Clever developers will set up ways to store raw JSON payloads and integration messages (errors etc) in the Import Set record.

Things to note with this approach:

• For most situations, you’ll need to ensure the integrating system receives the unique identifier of the record created by the transform, not the import set record. Recent versions of ServiceNow’s Import Set API appear to do this inherently in the JSON response.
• The import set will need to be set up not to use the default ServiceNow system delete property of 7 days if you want to be able to trace issues older than this.

ServiceNow documentation can show you how to achieve both of these.

For folks reading this who have become skeptical because Integration Hub doesn’t take this approach, I learned this approach from ServiceNow employee #1 (those who know, know). My standard tact is to believe those who created the platform over “johnny come latelies”.

Outbound: Create Extensible Field Mappers Instead of Writing Code

While WSIS are standard ServiceNow functionality, this recommendation is my good practice, and one I’ve espoused for all platform development. The goal is to build solutions that write code once, and build configurations that are extendable for future changes – ones that can be managed by non-coders. Think of it like a custom Transform Map for your integration. In the diagram above, this is the “X Request Map” at the middle bottom. In its simplest form, the table contains the following:

1. The table and field of the application in ServiceNow
2. The table and field of the integrating system
3. The nature of the integration: Inbound, Outbound or Bidirectional
4. An active flag

For #1, you can use the Table Name and Field Name dictionary field types. (The latter is dependent on the former; e.g. choose the Field from the Table selected) (Dictionary types).

Numbers 1 and 2 tell the integration the tables and fields from both systems map to each other. Conceptually, exactly like a Transform map, although one of the table\field combinations in this case is from the external, integrating system. Number 3 is a choice drop-down with options for Inbound, Outbound, and Bi-directional. Finally, an Active flag (Number 4) tells the integration is this a mapping that is currently used.

In Diagram 1, the bottom right side of the image shows how and where this is used. In many integrations I’ve seen, the creation of an outbound request from ServiceNow is done with pure code: the payload is built out via code, and changing the payload requires changed code. My suggested approach is to use Business Rules to trigger the request – when an update to an integrated record occurs, trigger the initiation of an outbound request. I use a Script Include function to build the request, so that it can be called from multiple places. Most importantly, I use the mapping table to determine what fields should be sent, and the field names to get the values from the ServiceNow record. The process flow is:

1. The integrated ServiceNow record is updated
2. A Business Rule running on that record’s table determines if the update needs to trigger the outbound integration
3. The Business Rule code calls a Script Include function, passing it the current GlideRecord
4. The Script Include function queries the mapping table, filtering on active, type=outbound, table is the current table
5. The Script Include function loops through the result, pulling the values for the external system fields and the GlideRecord field values, building an outbound name:value pair payload
6. The Script Include function triggers an outbound REST message and attaches the payload
7. The Script Include function processes the response as desired

---

Important Note: Wherever possible, the Business Rules should be run async. There is more on this in part 2.

---

If this is built correctly, the major benefit is that future updates to the integration can be completed with updates to the Mapping table, rather than with code. A true low-code, no-code solution!

More to come in Part 2.