Building Extensions #12: Creating widgets with the JS SDK bundle in Zoho Desk - Config Params

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 used Event APIs, along with the Data API and Request API, to create an extension that demonstrated how Event APIs can be used. In this post, we'll explain config params, and how we can put them to good use.

Config

The Config key is a part of the plugin-manifest file of an extension with configurable values. This key contains the installation parameters, commonly known as config parameters, which need to be configured when installing the extension. There are two types of config parameters:

userdefined (type1) - The value for the parameter should be provided by the user during installation
non-userdefined (type2) - The value for the parameter should be set dynamically from the extension, via the Set value for extension config variables API

Below is the structure of the plugin-manifest file in which the config params are to be included as highlighted.

In the Config key of the plugin-manifest file, the below fields should be filled in as described here, as per your needs:

name: It is a unique name used to fetch the field values. In extension code, it is used to replace the values. This name should be given in lowercase, and no space is allowed.
displayName: This name will be displayed as label of the field in UI.
Note: If displayName is not given, then the value of the name will be considered as display name in UI.
description: It provides additional information about the field. Also, you can provide hyperlinks, as given in the above sample code structure.
secure: True - values will be secured on the server side of the product and these values are hidden from the user; false - values will be available on the client side
type: Only "text" type is supported currently. Going forward, we support different types such as pick list, radio button, URL, Email, etc.
mandatory: Validate if the user enters values during installation
userdefined: True - input value is given by user
authType: It allows to get the params based on the user profile. Allowed values are org or personal.

org - If authType is given as org, then the fields of config params can be viewed only by the admin.
personal - If authType is given as personal, then the fields of config params can be viewed by all desk users.

Note: Generally, the auth type is addressed globally with the key 'type' in plugin-manifest file. However, if you have a requirement to restrict the visibility of config params to specific users based on their role, this auth type is used by defining the values (org/personal) for each field in config params. While using this key, we should remove the 'type' in the plugin-manifest file.

Scenario

Now let's jump into the use case we're trying to implement. When an event change is triggered in Zoho Desk, we want a task to be created in Zoho Projects in a specific project mentioned by the user. While invoking the Zoho Projects Create task API, the ProjectID and PortalID of the user are required. In our example, we configure a config param in the plugin-manifest file to obtain the ProjectID from the user, and we use a request API to get the user's PortalID.

Obtaining ProjectID

By configuring the config param as given in the below code snippet, we make it mandatory for the user to provide the required project ID in the Configuration section while installing the extension:

"config": [{"name":"ProjectID",
          "secure":false,
          "type":"text",
          "mandatory":true,
"userdefined":true}]

The value provided by the user needs to be fetched and passed to the Zoho Projects Create task API. The extensions API then needs to be used to capture the config params value.

ZOHODESK.get("extension.config").then(function(response){

configData=response["extension.config"];

for (let i = 0; i < configData.length; i++) { projectID=configData[i].value;

//console.log(projectID);

}

Obtaining PortalID

Now that we have the ProjectID, next we need to get the portal to which the project is associated. A request API can be used to get the PortalID.

(Note: In our example, we assume that the user has a single portal in Zoho Projects. If there are multiple portals it needs to be handled accordingly in your code.)

Creating task in Projects

Using the PortalID and ProjectID we've obtained, we invoke the Zoho Projects Create task API using the request API as given below:

In today's example, we've shown how to configure the config params in the plugin-manifest file, and how to get those param values and use them further in your extension using APIs. We hope you now have a clear picture on how to use config params in Zoho Desk.

Stay tuned for our next post, where we'll be discussing another SDK method!