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 email@example.com.
You can sign up for a free trial of ONEiO from the following link: ONEiO Free Trial
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.
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.
Organization Users New
- 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"
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:
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.
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
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.
- QA: https://rest-receiver-test.service-flow.com/api
- Production: https://rest-receiver.service-flow.com/api
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.
Please save the ServiceNow endpoint in ONEiO after generating a new password
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.
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
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
- 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 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.
If you want to know more about the ServiceNow endpoint in ONEiO, please read this article.