How to configure Zendesk for integration with ONEiO

Introduction

This article provides an example of how to prepare Zendesk for integration with a ONEiO endpoint. The exact configuration and number of fields required may vary depending on your integration use case.

For any questions related to setting up the integration, please send 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 describes the steps required to configure bidirectional communication between ONEiO and Zendesk.

1. From ONEiO to Zendesk - Create an Integration user and OAuth 2.0 client in Zendesk
   1. Note about Zendesk API Tokens
2. From Zendesk to ONEiO - Creating a webhook in Zendesk
3. From Zendesk to ONEiO - Creating triggers for updates and comments in Zendesk

Sending messages from ONEiO to Zendesk

ONEiO communicates with Zendesk using the Zendesk REST API.

 

Create an integration user and OAuth 2.0 credentials in Zendesk

Create an integration user and OAuth 2.0 client

Create a dedicated integration user in Zendesk. ONEiO uses this user when creating and updating integrated entities in Zendesk. The user is also required when setting up the OAuth 2.0 credentials.

To create the OAuth 2.0 client:

• Sign in to Zendesk using the integration user.
• Go to Admin Center → Apps and integrations → APIs → OAuth clients.
• Click Add OAuth client.

Fill in the required fields and select Confidential as the Client kind. After clicking Save, copy and store the secret securely, as it is shown only once.

Configure OAuth 2.0 authentication in ONEiO

After creating the integration user and OAuth 2.0 client, configure the Zendesk endpoint in ONEiO to use OAuth 2.0 authentication.

Enter:

• Client ID: The OAuth identifier from Zendesk
• Client Secret: The secret generated when you created the OAuth client

Save the endpoint configuration.

At this point, also verify the endpoint-specific values for the following fields:

• Name
• Zendesk root URL
• Timezone

Sending messages from Zendesk to ONEiO

Zendesk sends data to ONEiO using HTTP webhook requests with a JSON payload. Two Zendesk components are required: A webhook and Triggers that determine when the webhook is called.

The following sections explain how to configure Zendesk to notify ONEiO when tickets are created or updated.

Create Webhook

In Zendesk, go to: Admin Center → Apps and integrations → Webhooks → Actions → Create webhook

Under Select a way to connect, select Trigger or automation, and continue to the next step.

Configure the following fields:

• Name: ONEiO Integration
• Endpoint URL: 
  • For QA: https://rest-receiver-test.service-flow.com/api
  • For Production: https://rest-receiver.service-flow.com/api
• Request Method: POST
• Request Format: JSON

• Authentication: Basic. You can retrieve the authentication credentials from the ONEiO endpoint configuration. If required, generate a new password by clicking Generate new password in the ONEiO UI.

Back to Zendesk webhook configuration, click on Create Webhook, and, Finish setup.

Create trigger(s)

To send ticket updates and comments correctly, create two triggers:

• Trigger 1 – Ticket updates: Handles ticket updates other than new comments
• Trigger 2 – New comments: Handles updates containing a new public or private comment

You can customize the outbound JSON payload according to your integration requirements. However, keep ticket as the root object and include id as one of its attributes. YFor a list of available placeholders, see the Zendesk Documentation 

To create a trigger, go to: Admin Center → Objects and rules → Business rules → Triggers → Add trigger

Add the trigger 1 - Ticket updates.

Configure the trigger as follows.

• Trigger name: ONEiO Integration
• Select a Category
• Add at least the following condition:
  • Ticket update via - is not - Web service (API)
• Add any additional conditions required for your use case.
• Add the following action:
  • Notify active webhook→ ONEiO Integration
• Use the following JSON body:

{
 "ticket": {
 "id": "{{ticket.id}}",
 "external_id": "{{ticket.external_id}}",
 "title": "{{ticket.title}}",
 "description": "{{ticket.description}}",
 "requester_email": "{{ticket.requester.email}}",
 "assignee_name": "{{ticket.assignee.name}}",
 "priority": "{{ticket.priority}}",
 "created_at_with_timestamp": "{{ticket.created_at_with_timestamp}}",
 "latest_comment" : {
 "id" : "{{ticket.latest_comment.id}}",
 "value" : "{{ticket.latest_comment.value}}",
 "author_id": "{{ticket.latest_comment.author.id}}",
 "attachments" : [
 {% for attachment in ticket.latest_comment.attachments %}
 {
 "filename" : "{{attachment.filename}}",
 "url" : "{{attachment.url}}"
 }
 {% if forloop.last == false %}
 ,
 {% endif %}
 {% endfor %}
 ]
 },
 "sf_attachments" : [
 {% for attachment in ticket.latest_comment.attachments %}
 {
 "filename" : "{{attachment.filename}}",
 "url" : "{{attachment.url}}"
 }
 {% if forloop.last == false %}
 ,
 {% endif %}
 {% endfor %}
 ]
 }
}

 

 

Add the trigger 2 - New comments.

Configure a second trigger for new comments.

• Trigger name: ONEiO Integration - new comment
• Select a Category
• Add at least the following conditions:
  • Ticket update via - is not - Web service (API)
  • Comment is present (public or private)
• Add any additional conditions required for your use case.
• Add the following action:
  • Notifications: Notify active webhook→ ONEiO Integration 
• Add the required JSON body for the new-comment payload.

{
 "ticket": {
 "id": "{{ticket.id}}",
 "external_id": "{{ticket.external_id}}",
 "title": "{{ticket.title}}",
 "description": "{{ticket.description}}",
 "requester_name": "{{ticket.requester.name}}",
 "requester_email": "{{ticket.requester.email}}",
 "assignee_name": "{{ticket.assignee.name}}",
 "status": "{{ticket.status}}",
 "priority": "{{ticket.priority}}",
 "created_at_with_timestamp": "{{ticket.created_at_with_timestamp}}",
 "latest_comment" : {
 "id" : "{{ticket.latest_comment.id}}",
 "value" : "{{ticket.latest_comment.value}}",
 "attachments" : [
 {% for attachment in ticket.latest_comment.attachments %}
 {
 "filename" : "{{attachment.filename}}",
 "url" : "{{attachment.url}}"
 }
 {% if forloop.last == false %}
 ,
 {% endif %}
 {% endfor %}
 ]
 }
}
}