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 refer to the article Endpoint Type Configuration Guide - ManageEngine ServiceDesk Plus. 

In case you have questions related to setting up the integration, send an email 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 ServiceDesk Plus. In this guide, we cover the following steps required for bi-directional communication between ONEiO and ServiceDesk Plus.

1. Obtaining the Refresh Token through Zoho OAuth app 
2. Create a Webhook

Sending messages from ONEiO to ServiceDesk Plus

Obtaining the Refresh Token through the Zoho OAuth app 

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.

Create 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 details 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.