Introduction

This document demonstrates capabilities in barometerIT allowing for real-time synchronization from ServiceNow to barometerIT.

The synchronization happens through scripts in ServiceNow that push data to the barometerIT REST API.

Concepts

The barometerIT REST API provides integration capabilities between barometerIT and other systems. There are two operations that are useful for integration from ServiceNow into barometerIT:

ServiceNow provides the following functionality that allow barometerIT operations to be called when different events are triggered:

Outbound REST web service, which can be configured to allow barometerIT operations to be called
Business Rules, or server-side scripts (written in JavaScript) that run upon certain events such as when a record is updated. These scripts can call into the Outbound REST web services.

See the next three sections for instructions and examples of how to configure these elements to pass data to barometerIT operations.

Warning: The ServiceNow Adapter currently doesn't provide a way to prevent an infinitely recursive loop where an entity changes in barometerIT, which results in a record changing in ServiceNow, which results in that entity changing in barometerIT, etc... It's currently up to the user to avoid this scenario.

ServiceNow Setup

Create Outbound REST web services

Tenant Endpoint

In the instructions below, when you see [tenant-end-point] in the URL, this is your tenant's URL. For example https://example.barometerit.com.

Creating an operation to create entities

In the ServiceNow Service Portal, navigate to System Web Services - REST Message. (The name is a little misleading. Here you are not creating REST messages actually; you are configuring outbound operations that can be used to call into barometerIT's REST services.)
Click New to create a new web service
Give it the name "barometerIT Entity Service".
Enter the endpoint: "[tenant-end-point]/api/c/entities"
Under the Authentication tab, for Authentication Type, choose "Basic".
For Basic auth profile, click on the magnifying glass.
Click New to create a new auth configuration.
Enter the name "barometerIT REST authentication".
Enter a username and password based on credentials you create as a Person record in barometerIT. This should be a Person in a Role that allows them to update the appropriate fields in barometerIT.
Click Submit to save the auth configuration.
Under the HTTP Request tab, enter two HTTP Headers:
- Name: Accept, Value: application/json;charset=UTF-8
- Name: Content-Type, Value: application/json;charset=UTF-8
Click Update.
Click on the barometerIT Entity Service web service to create HTTP methods.
Under HTTP methods, click New to create two new methods (it's ok to leave the other HTTP method fields such as Endpoint blank):
- Name: Create Entity, HTTP method: POST
- Name: Update Entity, HTTP method: PATCH

Creating an Entity in barometerIT

Creating an entity in barometerIT uses the Entity Service (Create entity). The request body for creating an entity looks like this:

{

"entityDiscriminator" : "SYS",

"systemType" : {"bn": "040M000002QT"},

"domain" : {"bn": "040M00001645"},

"name" : "New System",

"lifecycleState" : {"bn" : "040M00000MWC"}

}

The bns for the option list items can be found using the Entity Service (Read entity properties).

Creating a Business Rule (example)

In the ServiceNow Service Portal, navigate to System Definition - Business Rules.
Click New to create a new business rule.
Give the rule a name and choose a table to attach it to.
Click on the Advanced checkbox.
Under the When to run tab, choose when it should run.
Under the Advanced tab, enter a script that will call the barometerIT Update Service. See below for an example.

function executeRule(current, previous /*null when async*/) {

gs.info('making call to barometerIT create service');

var body = {

'entityDiscriminator' : 'SYS',

'systemType' : {'bn' : '040M000002QT'},

'domain' : {'bn' : '040M00001645'},

'description' : '' + current.short_description,

'name' : '' + current.name,

'lifecycleState' : {'bn' : '040M00000MWC'}

};

var barometerCreate = new sn_ws.RESTMessageV2('barometerIT Entity Service', 'Create Entity');

barometerCreate.setRequestBody(JSON.stringify(body));

var response = barometerCreate.execute();

gs.info('barometer create response: ' + response.getBody());

})(current, previous);

Notice that when the script assigns property values to the request object (changes), it concatenates them with the empty string ''. This was found to be necessary to circumvent some mysterious behavior with JSON.stringify when it executes in the ServiceNow's environment.

Updating an Entity in barometerIT

The request body for updating an entity in barometerIT looks like this:

{

"bns": [

"041800000JJL"

],

"properties": {

"field1": "value1",

"field2": "value2",

"field3": "value3"

}

The Update Entities service can update more than one entity at a time, but in the following example we will just be performing an update for one entity at a time, so there will be only one entry in the "bns" list.

The properties can be standard fields (such as System Description) or custom fields. For custom fields, use the Field ID as the property key.

Creating a Business Rule (example)

In the ServiceNow Service Portal, navigate to System Definition - Business Rules.
Click New to create a new business rule.
Give the rule a name and choose a table to attach it to.
Click on the Advanced checkbox.
Under the When to run tab, choose when it should run.
Under the Advanced tab, enter a script that will call the barometerIT Update Service. See below for an example.

/**

When any of the following fields change in ServiceNow:

short_description

u_field1

u_field2

update the corresponding fields in barometerIT:

description

field1

field2

where u_importuuid is the field in ServiceNow that contains the unique Barometer Number (BN) of the record.

*/

(function executeRule(current, previous /*null when async*/) {

gs.info('making call to barometerIT update service');

var changes = {

'bns' : [ '' + current.u_importuuid ],

'properties' : {}

};

if(current.short_description != previous.short_description) changes.properties.description = '' + current.short_description;

if(current.u_field1 != previous.u_field1) changes.properties.field1 = '' + current.u_field1;

if(current.u_field2 != previous.u_field2) changes.properties.field2 = '' + current.u_field2;

if(Object.keys(changes.properties).length > 0) {

var barometerUpdate = new sn_ws.RESTMessageV2('barometerIT Entity Service', 'Update Entity');

barometerUpdate.setRequestBody(JSON.stringify(changes));

var response = barometerUpdate.execute();

gs.info('barometer update response: ' + response.getBody());

}

})(current, previous);

Notice that when the script assigns property values to the request object (changes), it concatenates them with the empty string ''. This was found to be necessary to circumvent some mysterious behavior with JSON.stringify when it executes in the ServiceNow's environment.

Testing

As with all integrations, barometerIT requires that customer integrators first test in the STAGE environment. Every tenant has a barometerIT STAGE instance which nearly mirrors the production environment. The STAGE environment is made available for integration testing. Of course, this will likely require a "stage" instance of ServiceNow on your end. We expect most customers will have that already for exactly these kinds of cases. (We know from our own experience that ServiceNow makes these easy to obtain for development purposes.)