Rest Integration

This article is a supplement to the ServiceNow documentation. For full documentation please refer ServiceNow official website

Checkout our NEW Video Channel you can like and subscribe too!

Introduction

Rest integration in ServiceNow is a vast topic and have infinite possibilities to integrate to virtually any third-party vendor software.Here we are going to take a look at the basic steps thats generally required irrespective of the parities involved in the integration.

Endpoint

Endpoints are references that accept request from an external system.

For example: If an external app wants to create a new incident in SNOW, then it needs to call the rest endpoint in SNOW instance.

Components of a REST call

API Explorer

API explorer is an OOTB application in SNOW where we can test the rest endpoints.

restintegration14112019 (1).png

Rest methods can be

GET
POST
PUT
DELETE
PATCH

Postman

Postman is a Rest client to test restful WebService endpoints. We will make use of Postman to test the rest endpoints in our ServiceNow instance.

Difference between inbound and outbound request

Request which are incoming to ServiceNow is inbound request.

For example: Using the rest endpoint to insert a new incident Request which are outgoing with respect to service is outbound request.

For example: Calling a third party vendor api to update the status of an incident Calling monitoring tool endpoint to collect metric data

Ways to import data in to ServiceNow

Direct table
Through import set
Scripted WebServices

Secure endpoint

We can secure the endpoint by restricted access to user with rest_service role only. Then caller can pass the user name and pwd as Basic Authorization header when calling the endpoint.

restintegration14112019 (2).png restintegration14112019 (3).png

Then when calling, the caller will pass this credential as Authorization header restintegration14112019 (4).png

This Authorization is combination of username:password base64 encoded from the information below restintegration14112019 (5).png

Crud Operation

Using POST method to insert into service now instance. Prepare for Insert into Incident table

Got to API Explorer and prepare the payload and other attributes restintegration14112019 (6).png

In the right side select the table where we want to import restintegration14112019 (7).png

Keep the headers as it is restintegration14112019 (8).png

Request header we need to the basic authorization header, we will add in the postman In request body ,add the attributes we want to populate, note that the explorer automatically creates the json version below

restintegration14112019 (9).png

We can add other parameters like response fields we need to see, exclude reference link from the response. For now we will not add any.Now we need to go the bottom and copy the curl version of the script

restintegration14112019 (10).png restintegration14112019 (11).png

Note that the user here is admin:admin because by default API explorer uses the admin account to query.When we will use postman we will use the user create earlier and pass it on as authorization header.

Now go to postman and click import.Paste the code we copied earlier. restintegration14112019 (12).png

After clicking import we can the post call is available below restintegration14112019 (13).png restintegration14112019 (14).png

Now we need add the basic authorization header

Go to Authorization header tag, change the drop down to basic auth and add the user name/pwd we create earlier restintegration14112019 (15).png

Now lets trigger the endpoint, we will see the response as below restintegration14112019 (16).png We can see that a incident got created with number as INC001002 restintegration14112019 (17).png

Now lets query this incident which using get and add additional parameters based on our needs restintegration14112019 (18).png

We select the table as incident restintegration14112019 (19).png

We can add other system parameters as queries,

Sysparm_query we can add encoded query from the filter we use in the list view restintegration14112019 (20).png sysparm_exclude_reference_link we can exclude/include the referernce link (like opened by field) restintegration14112019 (21).png sysparm_limit

sysparm_fields we can mention which fields we want in the response restintegration14112019 (22).png restintegration14112019 (23).png

Lets copy the query from curl script and paste in the postman again an import We can see the parameters got added in the header as key/values restintegration14112019 (24).png restintegration14112019 (25).png

Click send to see the response restintegration14112019 (26).png Now we can see less response. Get a specific record We can also query for specific record by passing the sys_Id of the record

restintegration14112019 (27).png restintegration14112019 (28).png Lets copy the script again

restintegration14112019 (29).png restintegration14112019 (30).png

Example of a uni directional flow

Rest integration can either be inbound or out bound

Inbound restintegration14112019 (31).png

Outbound restintegration14112019 (32).png

In our scenario, as we don’t have a external system so we will use our ServiceNow system both as source and destination

Scenario

Create an incident record using direct API call via postman
Write BR that will call a rest service endpoint of staging table
the staging table will use transform map and create record in problem table.

https://docs.ServiceNow.com/bundle/newyork-application-development/page/build/applications/concept/api-rest.html

restintegration14112019 (33).png

Note: The user calling the API should have appropriate role to call the endpoint.

For example: To create a problem record, the user should have ITIL role

restintegration14112019 (34).png

So we need to give itil role to the cti user restintegration14112019 (35).png

Without this role the user will get 403 restintegration14112019 (36).png

Step 1 We need to check the problem table api endpoint (this will be the inbound request to ServiceNow) restintegration14112019 (37).png

We then test the endpoint using postman restintegration14112019 (38).png

Now we are going to use this api and create a outbound Rest Message (this will be outbound to ServiceNow) restintegration14112019 (39).png

Here we give the external end point(in our case it the same instance we are working) and also the basic auth profile. Next we need add the http method to create a problem record restintegration14112019 (40).png

restintegration14112019 (41).png

In the content, for now hard code request body, we need to update into dynamic fields later restintegration14112019 (42).png Then we test, and see if problem gets created successfully restintegration14112019 (43).png Now we have to call this outbound rest message from the business rule Lets copy the script from the related links restintegration14112019 (44).png restintegration14112019 (45).png

Now we create a new BR and the rest call code restintegration14112019 (46).png restintegration14112019 (47).png

So here we are calling the rest message and also adding the parameter “sd” which will copy the short description from the incident record to the target problem record.

We have to update the rest message also with this dynamic variable restintegration14112019 (48).png

We are all done now. Lets create an incident using the direct table API call using postman and observe if a problem record gets created restintegration14112019 (49).png Now we will check if problem record got created

restintegration14112019 (50).png restintegration14112019 (51).png

Now lets refine the response a little bit so that we can figure out from the log the problem number restintegration14112019 (52).png

*Question: How can we update an existing record using update record api?

To update the remote system we need the remote record sys_id.

So the strategy will be as below

Create a custom field as remote_client_id in incident table
while creating the remote problem record, capture the sys_id from the response and set it to remote_client_id
during the update call, use this custom field

Using import API restintegration14112019 (54).png Instead of using direct table api to insert the problem record. We can use a staging table then refine the data and then insert into the incident table

Lets see the import staging table api structure restintegration14112019 (55).png restintegration14112019 (56).png

Create a new column description restintegration14112019 (57).png Now we are going to insert into this staging table and then use transform to load it into the problem restintegration14112019 (58).png restintegration14112019 (59).png

Now lets create transform map restintegration14112019 (60).png restintegration14112019 (61).png

Now lets create the mapping restintegration14112019 (62).png restintegration14112019 (63).png

Now lets add this staging table to import set api in api explorer restintegration14112019 (64).png

Lets call the api and test if this populating the target problem table through the transform map restintegration14112019 (65).png

We click send restintegration14112019 (66).png

Now we check problem table and see the record inserted. restintegration14112019 (67).png

Now we need to update the outbound WebService rest message with the new endpoint(staging table)

We do insert and stay and create duplicate restintegration14112019 (68).png restintegration14112019 (69).png

Also we need to update the BR restintegration14112019 (70).png

Also note we need add the role from custom table to the CTI user restintegration14112019 (71).png restintegration14112019 (72).png

Let update the BR restintegration14112019 (73).png restintegration14112019 (74).png restintegration14112019 (75).png

Scripted WebService

Scripted WebServices gives full control of the payload incase of inbound request to ServiceNow. We can write custom script include and attach to a scripted WebService. In that case, when caller calls the scripted WebService with custom attributes, we can write advance logic in the script include before inserting/updating data into ServiceNow table

restintegration14112019 (76).png restintegration14112019 (77).png restintegration14112019 (78).png restintegration14112019 (79).png

Let’s open this scripted WebService in API explorer

restintegration14112019 (80).png

As a query param we pass the sysid of the user whose HR profile we want to view. We click send and get a successful response

restintegration14112019 (81).png We now create our own scripted WebService with scenario described below Scenario

create scenario

An external application sends post call to /create endpoint of the scripted endpoint in ServiceNow
Internally it calls a script include
the script include calls a glide record and insert a new incident record
the script include returns the sysid
the scripted WebService returns the sysid response

update scenario

An external application sends post call to /update with the sysid received from create scneraio.
Updates the record
returns success/failure message
All other flows same as create scenario

Create scenario

First let create the script include, the script need not to be client callable as we are going to call it from the scripted WebService which is server side restintegration14112019 (82).png