Building Extensions #11: Creating widgets with the JS SDK bundle in Zoho Desk - Event API

This series aims to equip developers with all they need to build extensions for Zoho Desk in Zoho Sigma and publish them in Zoho Marketplace.

In our previous post, we discussed Data Storage APIs, their use in extensions, and how to use them in your Zoho Desk extensions. This post will briefly explain the next set of APIs in the JS SDK bundle, Event APIs, and show when and how to use them within Zoho Desk extensions.

Event APIs

The extension you're intending to build may require you to perform an action upon the occurrence of a particular event in your Desk portal. In order to trigger that action in Zoho Desk, your extension needs to listen to those event occurrences. The Zoho Desk platform provides Event APIs, which is an SDK method that helps you incorporate custom functionalities in your extension when certain events occur in your Zoho Desk portal. The events can be both ticket- and call-related.

Ticket events: You can configure extensions to receive information when an event, such as adding a comment to a ticket or opening a different ticket, occurs on the ticket detail page.
Call events: You can configure extensions to receive information when a call-related event occurs in your help desk portal.

There are multiple events available both in ticket events and call events. Whenever a particular event occurs, the parameter (Event API) for that event is used to broadcast information from Zoho Desk. The information from that event can then be processed in your extension using other APIs based on your business needs. Every event can be invoked from multiple locations in Zoho Desk; the details of the locations supported by every event and the parameter to be passed to invoke the events are listed here.

Scenario: Let's say you're using Zoho Desk to handle your technical support queries and Zoho Projects to manage your internal tasks. Here, we'll explain a simple use case where an extension could create a task in Zoho Projects automatically whenever the ticket classification of a ticket is changed in Zoho Desk. In this instance, we'll say you classify a ticket as 'problem' in Zoho Desk and get a task created for that ticket in Zoho Projects automatically. Let's see how the Events API can be used to achieve this simple use case in your extension.

When an agent triggers an event change in Zoho Desk, the Event API broadcasts the information about the event's occurrence from that ticket and can be fetched for further processing. To create a task in Zoho Projects, you can use Request API to invoke the Create Task API of the Zoho Projects. If you need additional information from the ticket while creating a task, you can use the Data API to get those details.

Below are the steps involved to implement this use case:

Create a connection in Zoho Sigma with required scopes
Create a task in Zoho Projects using the required JS SDK methods

Events API: Listen to the event
Data API: Fetch required ticket details for creating a task in Projects
Request API: Invoke Create Task API in Projects

Creating a connection

To build this extension, you must establish a connection between Zoho Desk and Zoho Projects with the required scopes. This will allow you to facilitate communication between these two services by invoking their APIs. Please check the Connectors post to learn more about creating connections. Once the connection is established, perform the following in the plugin-manifest.json file and save the file.

Paste the JSON code copied from Sigma in zohoAuthorization
Provide the Zoho Projects base URL (https://projectsapi.zoho.com) in whiteListedDomains

The plugin-manifest file with the connection and whitelisted domain details:

{

"locale": ["en"],

"service": "DESK",

"storage": false,

"type": "personal",

"whiteListedDomains": ["https://projectsapi.zoho.com"],

"modules": {

"widgets": [

{

"location": "desk.ticket.detail.rightpanel",

"url": "/app/widget.html",

"name": "Desk Extension",

"logo": "/app/img/logo.png",

"icon": "/app/img/icon.png"

}

]

"cspDomains": {

"connect-src": []

"zohoAuthorisation": {

"type": "connectors",

"connectionLinkName": "deskproject",

"connectionName": "DeskProject",

"serviceName": "zlabs_integration",

"userAccess": true,

"isUserDefinedService": false,

"sharedBy": "696258884",

"scope": [

"Desk.tickets.ALL",

"ZohoProjects.projects.ALL",

"ZohoProjects.tasklists.ALL",

"ZohoProjects.tasks.ALL",

"ZohoProjects.events.ALL",

"Desk.basic.ALL",

"ZohoProjects.tags.ALL",

"ZohoProjects.status.ALL",

"ZohoProjects.portals.ALL"

]

"connectors": [],

"config": [],

"moduleSupport": false

}

Creating a task in Zoho Projects

Below are the code snippets of different APIs that are used in this extension. The Event API will get triggered whenever the ticket classification is changed by the agent. You need to fetch the response from the broadcasted message and check the value of the ticket classification. According to our use case, we need to create a task if the classification is "problem," so the Request API is called for the same.

App.instance.on("ticket_classification.changed", function (data) {

classif = data["ticket.classification"];

if (classif == "Problem") {

ZOHODESK.request({url: "https://projectsapi.zoho.com/restapi/portal/" + xxx + "/projects/" + yyy + "/tasks/?name=" + encodeURI(ticketSub) + "&description=" + encodeURI(x) + "&priority=" + ticketPriority,

headers: {

"Content-type": "application/json",

type: "POST",

data: {},

connectionLinkName: "deskproject",

postBody: {},

contentType: "application/json",

})

.then(function (response) {

var resultparse = JSON.parse(response);

var resultparse2 = JSON.parse(resultparse.response).statusMessage;

var aaa = JSON.stringify(resultparse2);

})

.catch(function (err) {

console.log(err);

});

}

});

All the required ticket details, including the ticket ID, subject of the ticket, ticket description, and the priority status of the ticket are fetched using the Data APIs and passed to the Zoho Projects API. This information will be filled in within the task that is being created.

ZOHODESK.get(["ticket.id", "ticket.subject", "ticket.description", "ticket.priority"])

.then(function (res) {

var result = res.data;

var a = JSON.stringify(result);

console.log(a);

ticketID = result["ticket.id"];

ticketSub = result["ticket.subject"];

ticketDesc = result["ticket.description"];

ticketPriority = result["ticket.priority"];

x = ticketDesc.replace(/<[^>]+>/g, "");

ticketNumber = result["ticket.number"];

})

.catch(function (err) {});

In this example (full code given below), we have given you a clear picture on when and how to use the Event APIs in building extensions for Zoho Desk. Though other APIs are used too, the core of this extension is triggering an action on the occurrence of an event, which is done by the Event API.

While invoking the Zoho Projects API, you would have noticed that the Create Task API takes two important parameters, namely PortalID and ProjectID. These are specific to users; they are needed to decide for which project the task should be created. You may wonder how this should be handled in your extension development. We have config params to help you in such scenarios.

We'll discuss the usage of config params in our following post. Stay tuned !