Building Extensions #13: Creating widgets with the JS SDK bundle in Zoho Desk - Resources 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.

The Zoho Desk platform supports custom fields. The custom fields can be introduced using an extension. The Zoho Desk platform supports this capability through resources.json found in the plugin-manifest file and the Resources API offered in the JS SDK bundle.

In this forum post, we'll explore the Resources API in detail with an example of creating custom fields. Other resource types offered by the Zoho Desk platform include webhooks, custom permissions, and channel connectors; we'll talk about these individually in our upcoming forum posts.

Need for custom fields

There are various scenarios that may call for custom fields. Without creating an exhaustive live, here are a few scenarios in which you may need custom fields in Zoho Desk:

You might have to accommodate data from integrated third-party applications inside Zoho Desk. In such cases, you can add custom fields to help with this.
Your extension functionality may require some new fields to be available in the Zoho Desk modules. E.g., a few additional fields in your Tickets or Customers modules. In such scenarios, you would add a custom field to the desk modules.
You may want to provide agents with some additional information about the customer in the ticket's property section. You can add custom fields and pre-populate them with the relevant information.

Defining custom fields

The custom fields are to be included in Zoho Desk by defining them in the resources.json of the plugin-manifest file. Below is the structure of the resources.json with sample data filled in.

      ...
      {
          "fields": [{
              "resourceName": "field1",
              "module": "tickets",
              "displayLabel": "Counter",
              "type": "Text",

              "defaultValue" : "none",
              "maxLength": "100"
          }]
      },
      ...

Every field you create should have a unique identifier that is defined using the mandatory resourceName key. The resourceName(s) specified in resources.json should be unique across the extension and will be validated before the extension is made available on the Zoho Marketplace. The resourceName also serves as the unique identifier across all organizations that install your extension. The new custom fields will be automatically mapped to the default layout configured for a department, so there is no need to pass the layoutId key anywhere else in the extension code.

Any field you include in your extension will be added to the user's Zoho Desk portal on the very first installation of the extension, while subsequent installations map to the fields already created. The fields are deleted from the portal on the last uninstallation of the extension. You can include a maximum of 10 custom fields in an extension.

Using custom fields in extensions

The resourceName defined in the resources.json file is automatically mapped with an ID and an apiName, which can be used in the APIs related to the resource as required. You need to retrieve the ID and/or the apiName of a resource to be used in the API calls of your extension.

To retrieve this, you can use one of the following approaches:

Using merge fields in the invoke API
Using the client SDK

Using the merge fields

This method is applicable for Desk's invoke API where you need to specify the resourceName value in the following format.

{{resourceType.resourceName.id}} or {{resourceType.resourceName.apiName}}

Refer to specifying placeholders in invoke API for more information.

Note: The resourceType should be fields or webhook, based on your use case. The id returns the fieldId or webhookId, based on the value in resourceType. The apiName returns the apiName of the resource and is applicable only to fields.

Using the client SDK

In this method, you must use the Resource API to retrieve resource details.

Note: We will use the second approach in this forum post example; the first approach will be covered when we discuss Desk Invoke APIs.

Resource API

The resource details of the extension can be obtained using this API provided the resourceName key is given in the resources.json file.

Note: The response will be given against the resourceName given in the extension.

Sample Request: Get the details of the resource "field1"

      ZOHODESK.get("extension.resource", {resourceName: "field1", resourceType:       "fields"}).then(function(response){
                //response returns the value saved
      }).catch(function(err){
                //error handling
      })

Response:

      {
          "status": "success",
          "extension.resource": {
"resourceName": "field1",
"id": "4000000020060",
"resourceType": "fields",
"apiName": "cf_counter"
          }
      }

Scenario:

Let's say you plan to provide support agents with some additional information about the users in the tickets' details page. Specifically, you need to display whether the user is a new user or an existing user. If the user is an existing user, you also want to note how many tickets are associated with that user and the number of open tickets. This can be implemented by adding the required custom fields and writing a script that provides details about the user and the tickets associated with them.

Defining fields in resources.json

As per our use case, you can define two fields with the following properties:

Sl.No	Field name	Type
1	User type	Text
2	Number of open tickets	Text

Below is the resource.json file that needs to be defined. As mentioned earlier, the resourceName key for every field needs to be unique and has to be defined for every field.

{"fields": [

{

"module": "tickets",

"displayLabel": "User Type",

"type": "Text",

"defaultValue" : "none",

"resourceName": "UserType",

"maxLength": 100

{

"module": "tickets",

"displayLabel": "Number of open tickets",

"type": "Text",

"defaultValue" : "none",

"resourceName": "openStatus",

"maxLength": 100

}

]

}

Note: You'll need the API names of the resources in your implementation whenever you refer to the respective resource. The Resources API can be used to fetch the API names. The code below has been used for fetching the API names for the two fields in our use case and the same API names are used in the code. The console output is added for reference.

ZOHODESK.get("extension.resource", {resourceName: "UserType", resourceType: "fields"}).then(function(response){

console.log(response);

}).catch(function(err){

console.log(err);

})

ZOHODESK.get("extension.resource", {resourceName: "openStatus", resourceType: "fields"}).then(function(response){

console.log(response);

}).catch(function(err){

console.log(err);

})

Use case implementation

To implement our use case, we perform the following steps in extension.onload. The code snippet is added below for reference:

Get the email ID of the current ticket.
Use the Zoho Desk search API to check if there are any other tickets from the same user.
If the search API results show more tickets from the same email, check the status of those tickets.
Finally, construct the result so it is set to the custom fields and update them accordingly.

Sample code:

Please check the attachments for the sample code.

Output:

Here, you can see the text for the two custom fields were added to the ticket and were populated with the relevant values. In this manner, you can add required custom fields to Zoho Desk using extensions, based on your business needs.

Hope you found this post to be useful. Stay tuned for more posts in this space!