Integrations à la carte – An Intro Overview

Aperitif

Hi there! Welcome to my first blog post. First things first, a bit about me to give you some perspective on this content.

I’ve spent the last 5 years of my life writing, debugging, and solutioning integrations on ServiceNow. I figured it was about time I wrote about it. I came to ServiceNow from a raw computer science background of algorithms and data structures, having to learn ServiceNow from the ground up. The #1 thing I’ve appreciated during my everlasting learning process has been technical guides with good breakdowns in readable English, so that’s what I’m hoping to provide for you here. In the words of many great internet content creators, let’s jump right into it!

Appetizer

So you want to build an integration on ServiceNow? Awesome. You already must know that this is a fantastic platform if you’ve chosen to use it for your solution. But hold your horses! Before we get into the weeds on this, we should do some requirements gathering.

The first part of creating a technical integration is understanding the requirements around the integration. Some of the key questions I always find myself asking are:

  1. What is the external system we are integrating with?
  2. What kind of integration are we talking about here?
    1. Are we pushing data to them?
    2. Are they pushing data to us?
    3. Are we pulling data from them?
    4. Are they pulling data from us?
    5. Any and all combinations of these?
  3. Who is responsible for defining the payload structure?
  4. What Authorization method will be used by each system?

Main Course

Lets talk through the different kinds of Integrations and their pros/cons: (forewarning – there are a lot of iterations)

One way – Outbound Integration (option 1 & 3 from above)

Pushing from SN (ServiceNow) is wonderful because you have full control of the pushing mechanism. However, the drawback is that you are limited in what you can do based on the endpoint (other system) you are pushing to.
I like using metaphors – when I think about integrations, I think about sending really advanced packages/letters in the mail. In this example – a data push from SN to an external system – you get to build the package, but you may have strict instructions as to what contents are allowed in that package. No car batteries, grandma…

The other type of one way integration will be a pull request and, you guessed it, SN can pull from other systems (and other systems can pull from SN). Pulling from other systems will have the same drawbacks as pushing to other systems – you will be bound by their rules, but you can dictate the speed of development as long as they don’t change the API on you mid-development… but by then you will be a pro and be able to handle it no problem.

One way – Inbound Integrations (2 & 4)

In addition to pushing from ServiceNow, other systems may want to push into ServiceNow. Here, the shoe is on the other foot. You get to define the endpoint in ServiceNow, dictate the format of the data coming your way, and then write the code to process and route the data.

Lastly, for one way integrations, SN can be queried by external systems. Here, once again, you will get to define the data that is output through the endpoint.

Two way – Advanced Integrations Combinations

This is where things can get tricky – Gloves are off, and any of the above types can be combined! An example of this would be an “e-bond” to a ticketing system. This is where you sync the states and data of 2 systems – keeping them in sync no matter what happens on either end.

Authorization

Lastly, but also firstly… auth. There are many options and each option has its own nuances. Most likely, you will be implementing some form of Oauth or Oauth 2.0. For an introductory overview, I’m not going to go into much detail, but I will at least go over the most basic of basic auth types – basic auth.

Basic auth is basically (pun intended) a username and password combo that will authorize the use of the integration. It is the easiest to implement and great for fast dev.

For other types of Oauth, there is a link in the Digestif below for a more in-depth analysis of the many different kinds and how to implement them.

Dessert

Now that the basics are out of the way, it’s time for the good stuff. The delicious technical details to actually get started on an integration. At this point you, might be asking: What kind of data are we sending? That’s a good question, imaginary blog post reader. Let me answer that for you.

The most common kind of of data that you will be sending will be in a data format called JSON (JavaScript Object Notation). Basically, you build an object in javascript like:

var someObject = {
"property1" : "value1",
"property2": "value2"
};

Then you call a magical function:

JSON.stringify(someObject);

Finally, you take your data (probably much more complicated than this example), append it to your payload, and away it goes!

Or in reverse – if you are processing an incoming payload, you will look at the request body (likely in string format) and you will transform it back to JSON using the other magic function:

JSON.parse('{"property1":"value1","property2":"value2"}');

Voila! You have yourself data in JavaScript to start mutating, moving, processing, dancing with… well okay maybe not dancing with.

Now, this is not a conclusive guide or anywhere CLOSE. This is just a first bite of the first meal of integrations and how to start thinking about them from a high level. If you made it this far and are feeling like you want to know more, FANTASTIC! Also, thanks for reading! If you look below, the Digestif section will have links to official documentation and more technical readings/references to start chewing on.

Digestif

ServiceNow Scripted REST Endpoint Documentation

JSON Basics

Some ServiceNow Oauth Documentation