Building Extensions #10: Creating widgets with the JS SDK bundle in Zoho Desk - Data Storage 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 Request APIs, what they're used for in extensions, and how to use them in your Zoho Desk extensions. In this post, we'll examine the next set of APIs in the JS SDK bundle—Data Storage APIs—and show you how to use them in the Zoho platform (Sigma) to build the Zoho Desk extensions.

Data Storage APIs

You may find that you require an extension that has data storage and retrieval capabilities. Zoho Desk allows you to store extension-related data in a database so that it can be retrieved and used when required. This can be data from a third-party application, or any other data related to the extension's functionality that needs to be preserved for future use. With the Data Storage APIs, you'll have access to a data store where the extensions can set (store) and get (retrieve) data using the Data Storage APIs. A key-value pair is used in managing the details about the data that's stored and retrieved, and is explained in detail in this post. When the data is no longer required, it can even be removed using the delete API.

The following SDK methods provide database management functionalities in your extensions.

Get data

The get API retrieves data from the extension's connected database. The request includes two parameters: key and queriableValue. The API request must include at least one of them.

key - Helps to identify what is being called by the API.
queriableValue - Specifies a common lookup group which will be useful for lookup from the database.

Here is a sample code snippet of the get data function:

ZOHODESK.get("database", { "key": "3", "queriableValue": "test" })

.then(function (response) {

//response returns the value, based on the key specified

})

.catch(function (err) {

// Error handling

})

Set data

The set data API asynchronously sets data in the extension's connected database. The request includes three parameters: key, value, and queriableValue. The API request must include all three parameters. Each parameter is subject to further conditions:

The value passed by key can have a maximum length of 50 characters. The only special characters allowed are commas (,), underscores (_), and colons (:). The value of this parameter cannot be NULL.
The data passed by value must be a JSON object whose size cannot exceed 1 KB. Empty JSON objects can be passed, too.
The value passed by queriableValue can have a maximum length of 50 characters. The only special characters allowed are commas (,), underscores (_), and colons (:). The value of this parameter can be NULL.

Here is a sample code snippet of the set data function:

ZOHODESK.set("database", { "key": "3", "value": { "test": "testid" }, "queriableValue": "test" })

.then(function (response) {

// response returns the value saved

})

.catch(function (err) {

// Error handling

})

Delete data

The delete data API completely removes the selected data from the connected database. The key parameter must be included in the API request.

Here is a sample code snippet of the delete data function:

ZOHODESK.delete("database", { "key": "3" })

.then(function (response) {

// response returns the status of deletion

})

.catch(function (err) {

// Error handling

})

Scenario: Let's say you're building an extension that involves creating events in Zoho Calendar from within Zoho Desk—i.e., the user creates Calendar events without switching from Zoho Desk to Zoho Calendar. In this case, the events created can be fetched from Zoho Calendar and are categorized and listed in the extension, such as completed event, upcoming event, or any other events, according to requirements. The Data Storage APIs can be used to get those events' data, store them in the extension database, and list those events in the extension's widget.

To implement this scenario, you must establish a connection between Zoho Desk and Zoho Calendar with the required scope. This will allow you to make requests between these services by invoking their APIs. Please check the Connectors post to learn more about creating connections. Once the connection is established and the configurations are completed in the plugin-manifest.json file, you can proceed with executing your extension functionalities.

The code below demonstrates how an event is created in Zoho Calendar using the Request API and the events are listed in Zoho Desk using the set method.

Use ZOHODESK.request to invoke Zoho Desk's "Create Events" API.
Here, we are pushing the event data into Zoho Calendar.
Construct the request object for ZOHODESK.request.
{
"url": "https://calendar.zoho.com/api/v1/calendars/calId/events",
"type": "POST",
"headers": {},
"postBody": {},
"connectionLinkName": "calendarEvent",
"data": {
"eventdata": {
"dateandtime": {
"timezone": "Asia/Kolkata",
"start": "20220225T130000+0530",
"end": "20220225T133000+0530"
},
"title": "Today's morning meeting"
}
}
}
Extract the required values from the response of the request.
Use ZOHODESK.set to invoke Zoho Desk's "set record" API.
ZOHODESK.set("database", {
"key": userId,
"value": {
"eventId": eventData.id
},
"queriableValue": "eventIds"
})

In this code, we're doing the following:

Creating events in Zoho Calendar by making a call to the Calendar events API, post method. The Request API SDK of Zoho Desk is used to invoke the Zoho Calendar API. The events are created with event date, event start time, and end time, with the time zone defined.
As mentioned, we need to list those events in our extension for our quick reference, so the required event information is fetched from the Request API's response.
Finally, we're storing the event information in our extension database using the set method. Here, we have defined key as userId, value as eventData.id, and queriableValue as eventIds. So all the events (eventData.id) created by the user (userId) will be stored within the database (eventIds).

Now that we have the event information in our extension database, we can use the get Data Storage API, define the key and queriableValue to retrieve the event information, process them, and display the events in your customized widget in the extension.

We hope that this example code has given you a clear picture of when and how to use the Data Storage APIs in building extensions for Zoho Desk.

Stay tuned for our next post where we will discuss another SDK method.