How to configure ServiceNow for integration with ONEiO

Introduction

This document shows an example of what needs to be done in ServiceNow to make it integration-ready with the endpoint in your ONEiO. Note also, that the number of fields used in integrations might vary. 

In case you have questions related to setting up the integration, send a mail to support@oneio.cloud.

You can sign up for a free trial of ONEiO from the following link: ONEiO Free Trial

Overview

This article gives an overview of the required steps to integrate ONEiO and ServiceNow. In this guide, we cover the following steps required for bi-directional communication between ONEiO and ServiceNow.

1. Create Integration user in ServiceNow
2. Dynamic Update Set 
3. REST Message
4. Business Rules

Sending messages from ONEiO to ServiceNow

ONEiO accesses ServiceNow through the REST API

 

Create Integration user in ServiceNow

Add integration user to ServiceNow. This user is used to send updates and creates to ServiceNow through the Table API interface. The credentials have to match those configured to the ServiceNow adapter configuration in ONEiO.

Go to:

Organization   Users   New

Add user

• username "oneio" (you can choose a different name also, but remember to change it to used business rule conditions)
• Check "web service access only"
• Right-click on the gray header area (User - New record), and select "Save"

 

 

Roles   Edit

Add roles: itil

• The user must also have access to the tables integrated, in this example incident and sys_attachment

Press "Set password", "Generate", and copy it to the clipboard. Save the password, and close the prompt window. Finally press on "Update", located in the upper right-hand corner.

After the user is created, fill in the same information in the ONEiO UI in the ServiceNow User & Password fields.

At this point please also check the Name, ServiceNow root URL, and Timezone fields and verify your endpoint-specific values.

 

In ONEiO you have two options for authentication: Basic and OAuth 2.0.

For Basic authentication, you only need ServiceNow user and password.

For OAuth 2.0 authorization, you need ServiceNow user, password, Client ID, and Client Secret.

 

How to get Client ID and Client Secret (skip if you are using Basic authentication)

In ServiceNow, navigate to System OAuth --> Application Registry and click on "New"

Select option Create an OAuth API endpoint for external clients

Here you can create your OAuth 2.0 credentials

The Client ID will be automatically generated. For the Client Secret, you can choose to add it yourself or to leave it empty; in this second case, it will be automatically generated after the OAuth 2.0 record is saved. 

Now go back to ONEiO, add the Client ID and the Client Secret to the fields below, and save your endpoint:

 

Attachment handling

Sending attachments to ServiceNow

ONEiO sends attachments to ServiceNow through ServiceNow's Attachment API. For this operation, the outbound message to ServiceNow needs to include the attribute sys_id, with the target entity's sys_id as the value.

 

Sending messages from ServiceNow to ONEiO

ServiceNow communicates with ONEiO through the REST message as part of the REST API. This REST message is pre-configured as part of the Dynamic Integration Set ONEiO provides.

Retrieve Update Set

ONEiO provides a pre-configured update set, that includes everything needed for ServiceNow to communicate with ONEiO. You can download the update set from the button below.

DOWNLOAD

The update set contains:

• 1 REST message
• 1 Business Rule for the incident table
• 2 Business Rules for sending out attachments.

After committing the update set you have to add the outbound credentials to the REST message. These credentials can be retrieved from the ONEiO UI. 

For importing the update set, start by importing the XML on:

System Update Sets   Retrieved Update Sets   Import Update Set from XML

 

Upload the update set retrieved previously from the ServiceNow Developer site.

 

Open ONEiO Integration Components

Preview and Commit the Update Set

REST Message

For communication from ServiceNow towards ONEiO we use a REST message with ONEiO specific target, HTTP Method & Content-Type. Authentication has to be set on a per endpoint bases.

You can find the REST message settings on:

System Web Services   Outbound   REST Message   ONEiO

The REST message includes the ONEiO receiver address in the endpoint section. Depending on your ONEiO environment these have to be adjusted.

Next up we have to adjust the prefilled Basic Auth Profile.

The Username and Password are available from your ServiceNow endpoint UI in ONEiO. The Username is always visible, but you have to enter Edit mode the access the Generate new password button.

Now that the Authentication is set up, let's test that everything works correctly. For that, we have added a secondary REST message in our Update Set. This REST message is not being populated dynamically with ticket information but has a hardcoded payload just for testing purposes.

It is pre-configured to inherit the Authentication type from the parent, so you don't have to configure that part.

Choose the Test link on the left side of the screen.

This will send a test payload towards ONEiO and on success return an HTTP 202 and Response ID.

This message will also be visible in the ONEiO Message View.

Business Rules

Before creating an Incident, let's check the Business Rules included in our Update Set. 

Three Business Rules are included:

• ONEiO Incident integration Post for sending from the incident table
• ONEiO Attachment after Correlation ID handles attachment sending on incident creation
• ONEiO send attachment for sending attachments as an update

Handling encrypted attachments

If your instance has field encryption and encryption module access defined by roles the integration user needs to have such a role to be able to forward encrypted attachments to the target system. Either create a role for this specific function and give it access to the encryption module, or give the ITIL role such access. Otherwise ONEiO will receive a 404 - Not Found error from ServiceNow when it attempts to download the attachment.

Creating an Incident

Now that the ServiceNow integration is set up we can create our first incident. 

Incident   Create new

Fill in the required fields such as Caller and Short Description and any other information required for your test scenario. Observe the Assignment group in our example, it is used as a trigger condition in our Business Rule.

The Incident should show up in the ONEiO Message View.

Congratulations, you have successfully integrated your ServiceNow into ONEiO.

Duplicating the business rules for new processes

If any other processes in ServiceNow should be integrated, cloning and/or extending these rules is all that's needed.

Inside the ONEiO Incident integration Post business rule (You will find it under Under System Definition -> Business Rules) 

• Right click on the top grey menu bar
• Select Insert and Stay to clone the current rule

Return to the Business Rules list view (You will find it under Under System Definition -> Business Rules), you can now see two ONEiO Incident integration Post rules.

Open the newly created copy and adjust the Name and Table to match your needed process. In our case, we are creating a Problem process.

Now we are able to send tickets from the Problem table to ONEiO.

In case your process requires Attachments to be sent as part of your tickets, clone the ONEiO Attachment after Correlation ID business rule and adjust the table from Incident to your required process.