Introduction
This document shows an example of what needs to be done in Zendesk to make it integration-ready with the endpoint in your ONEiO. Note also, that the number of fields used in integrations might vary.
Note that to be able to use any integration features in Zendesk, you need to have at least a Support Team subscription level. The essential subscription plan does not include the needed features.
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 gives an overview of the required steps to integrate ONEiO and Zendesk. In this guide, we cover the following steps required for bi-directional communication between ONEiO and Zendesk.
- From ONEiO to Zendesk - Creating an Integration user and token in Zendesk
- From Zendesk to ONEiO - Creating a webhook in Zendesk
- From Zendesk to ONEiO - Creating triggers for updates and comments in Zendesk
Sending messages from ONEiO to Zendesk
ONEiO accesses Zendesk by using the Zendesk REST API.
Create an Integration user and token in Zendesk
Add integration user to Zendesk. This user is needed to create and update the entities that are integrated. Zendesk API uses API tokens instead of the password of the user.
To create a token navigate to Admin Center → APPs and Integrations → Zendesk API. Remember to name your token so you recognise it in the future.
After creating the integration user and token, fill in the same information in the ONEiO UI in the Zendesk User and Token fields, adding the prefix /token at the end of your Zendesk username, as shown in the image below.
At this point please also check the Name, Zendesk root URL, Timezone fields and verify your endpoint-specific values.
Sending messages from Zendesk to ONEiO
Zendesk accesses ONEiO with form-encoded HTTP requests. The needed parts are HTTP Webhook and a Trigger. The following chapter explains how to configure the needed functions to trigger calling the web services when inserting and/or updating incidents in Zendesk.
Create Webhook
Go to Admin Center→ Apps and integrations → Webhooks → Actions → Create webhook
In Select a way to connect select Trigger or automation, and go to the next step.
Fill the next fields as the example below:
- 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 credentials from the ONEiO UI's endpoint configuration. Create a new password by clicking on Generate new password
Back to Zendesk webhook configuration, click on Create Webhook, and, Finish setup.
Create trigger(s)
To be able to send out updates and comments properly, you need two triggers; one that handles only new comments (Trigger 2 - New comments) and one that handles all the rest (Trigger 1 - Ticket updates).
You can modify the outbound payload as you like as long as you keep the "ticket" as the base container and keep "id" as one of the attributes. You can find the list of possible placeholders from Zendesk Documentation
To create a trigger, go to Object and rules → Business rules → Triggers → Add trigger
Add the trigger 1 - Ticket updates.
- Trigger name: ONEiO Integration
- Select a Category
- Add at least the following condition:
- Ticket update via - is not - Web service (API)
- (add more conditions according to your use-case)
- Add this action:
- Notify active webhook→ ONEiO Integration
- 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}}",
"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.
- Trigger name: ONEiO Integration - new comment
- Select a Category
- Add at least the following condition:
- Ticket update via - is not - Web service (API)
- Comment is present (public or private)
- (add more conditions according to your use-case)
- Perform these actions:
- Notifications: Notify active webhook→ ONEiO Integration
- JSON body:
{
"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 %}
]
}
}
}
Comments
Please sign in to leave a comment.