How to configure ManageEngine ServiceDesk Plus for integration with ONEiO

Introduction

This document is meant to guide you through the steps necessary to configure your cloud instance of SDP ready for successful integration with ONEiO. For endpoint configuration instructions please consult this article. In case of any questions or if you are using the on-premise version please drop us a message at support@oneio.cloud.

To integrate SDP with ONEiO we'll need to cover points: getting a refresh token through a Zoho OAuth app and configuring a webhook. 

Obtaining the Refresh Token

To communicate with SDP Cloud API we'll need to get access through a bearer token. To get the token please follow the instructions published by ManageEngine here. Once complete you should now have at hand the values for Client Id, Client Secret, and Code. To receive the refresh token we need to perform the following request (cURL):

curl --location --globoff --request POST 'https://accounts.zoho.eu/oauth/v2/token?code={{code}}&grant_type=authorization_code&client_id={{clientI_id}}&client_secret={{client_secret}}&redirect_uri=https%3A%2F%2FNOTNEEDED'

Or if you prefer through a tool like Postman where we need to execute a GET request: 

https://accounts.zoho.eu/oauth/v2/token?code={{code}}&grant_type=authorization_code&client_id={{client_id}}&client_secret={{client_secret}}&redirect_uri=https://NOTNEEDED

As you may have probably guessed, we need to use the earlier obtained values instead of placeholders for {{code}}, {{client_id}}, and {{client_secret}}. 

If successful, Zoho would return the refresh token in the response message body:

{
"access_token": "<access token>",
"refresh_token": "<refresh token>",
"api_domain": "https://www.zohoapis.eu",
"token_type": "Bearer",
"expires_in": 3600
}

The value of a refresh token we'll need to save for further configuration of the endpoint in ONEiO.

Creating a Webhook

To receive information from SDP the most suitable and easy way is to create a webhook. Let's create one by searching for "webhook" in the "Setup" module or through Setup>Automation>Custom Actions>Webhooks:

• Let's give it some name and description that makes the most sense to you. 
• The URL would depend on which environment you are going to use at ONEiO. Either https://rest-receiver.service-flow.com/api for production or https://rest-receiver-test.service-flow.com/api for QA.
• This webhook applies to "Requests"
• The method would be POST.
• We'll need one parameter "auth_token" configured. The value will come from the endpoint in the ONEiO App "Inbound Authentication" section in the edit mode. 
• As to the message body, it must be "JSON": 

{
"id":"${id}"
}

It will be enough to send only the "id" of the request since ONEiO will look up the rest of the detail automatically. 

Once done it would be handy to test the webhook right away using the data of the existing requests. Simply follow the instructions of the "Save and Test" wizard. If successful ONEiO will return the HTTP status 202 and you will see the request in ONEiO. 

Note: It would be recommended to complete the step with the token before testing the webhook since ONEiO will need to authenticate against SDP Cloud API when looking up request data.