Try this API
Call this method on live data to see the API request and response. Need help with the API Explorer?
Request parameters
You have invalid or missing required parameter values above.
Execute
Developers
Build extensions in Qntrl!
You can develop value-added extensions for Qntrl and host it on Qntrl Marketplace.

Overview

Qntrl supports a variety of businesses. That said, every organization has a unique requirement. To enable users develop custom solutions for their business, we support user extensions. Developers can build their extensions and host them on Qntrl Marketplace.

This is a handbook to build your own extension for Qntrl.

Framework overview

Qntrl uses ZET(Zoho Extension Toolkit) framework to build extensions that let you add new features and integrations to the product.

ZET framework allows your extension to interact with the product using supported JS SDK APIs. To facilitate this interaction, you can import the framework's JS file using the following command,

Once the JS is imported, the global object QntrlSDK will be available. You can create a client object to communicate with the product using the below method.


var QntrlClient =  QntrlSDK.init();
   
 QntrlClient.then(function(app) {    
/* Use this space and build interactive app using the sdk . 
Below is an example to get the user name*/ 
        QntrlSDK.get('user.name').then(function (data) {
            //response Handling
        }).catch(function (err) {
            //error Handling
        });    
});

To set up a run time environment for building the extension, install node JS and ZET CLI (Command Line Interface), both of which help in streamlining the development process.

Internal and external hosting

You can build your extension using client-side technologies like HTML, CSS, JS, etc. These extensions are then rendered in the product using iframes. Such extensions, built using client-side technologies, can be internally hosted using Qntrl's server.

However, if you wish to opt for server-side technologies, the extension must be externally hosted on a remote server.

While mentioning widget URL in the plugin-manifest.json file, internally hosted extensions are configured with a relative URL, whereas externally hosted extensions take up an absolute URL to which the extension points.

Public and private extensions

You can choose the audience for your extensions.

Public extensions are hosted on Qntrl Marketplace for other users to install and use. A public extension must be submitted for review where the extension's functionality is tested. If the extension suits the standards of Qntrl Marketplace, it gets listed for public users to install and use.

Private extensions have a restricted set of audience. If you wish to share the extension only within your organization, you can classify the extension as private. Private extensions do not go through a review process. Any user who has the extension's URL can install and use it.

How to create an extension?

Step 1: Install the node and ZET CLI

Start building your extension by setting up a run time environment.

  • Install node.js
  • Install Zoho's Command Line Interface- Zoho Extension Toolkit (ZET CLI). The CLI allows you to build, test and package extensions.
  • For Mac/Unix system:
sudo: npm install -g zoho-extension-toolkit
  • For Microsoft Windows:
system: npm install -g zoho-extension-toolkit
Additonal Notes:
  • Before installing the node, run the following command to check if there are any previous versions of it. We support version 7.1.0 and above.
node -v
  • The -g command in ZET denotes global installation. This allows you to execute ZET commands anywhere in your machine.
  • To verify the version of ZET:
zet -v (or) zet -version
  • To view all the available commands in ZET:
zet -h (or) zet -help

Step 2: Build the extension

In the terminal window, navigate to the directory under which you want to build the extension.

  • Run the following command:
zet init
  • Choose Qntrl from the list of services displayed.
  • Give a name to your extension and hit Enter.

A project template directory comprising all the necessary folders, dependency node packages, and files is created.

Next, execute cd[extension name], to navigate to the current path of extension's directory.

plugin-manifest.json

You can find this file in the extension directory. It contains meta information about the extension. Developers can configure information such as widget details, widget locations, connectors etc. Get a detailed insights of the file here.

  • Widget details: Specifications of the widget like name, URL and, location can be configured in the plugin-manifest.json file. Learn more about the parameters used to configure widgets.
  • Widget locations: Qntrl allows widgets to be rendered in specific locations of the product. Get a detailed view of the supported locations here.
  • Connectors:Connectors is a built-in Zoho service used to authenticate and integrate extensions with third-party applications. Learn more about connectors.

JS SDK

JS SDK helps the developers gain contextual details about different entities. You can use the JS SDK methods by importing QntrlSDK to your widget app file.

Data storage in extensions

In Qntrl, extensions can be used to store data, where the properties of various entities can be stored against the extension itself. This helps the developers store key-value pairs of data against entities and extensions.

  • Entity properties: Entity property supports storage of data against entities in the product. Learn more about storing data in entities.
  • Application properties: Application property supports storage of data against the extension. Learn more about data storage methods here.

Step 3: Test the extension

Once your extension is developed, you can test it in your local machine.

  • Run the following command in your terminal.
zet run

Enabling the developer mode

  • Navigate to and select Extensions Dev Guide from the left panel.
  • Toggle the Enable Developer Mode button to turn it on.
    • When the developer mode is enabled, other extensions installed in the product will not work.
  • Navigate to the location of your extension configured in the widget location and refresh the window to render the extension.
  • Once you wish to revert to normal mode, toggle the button and turn it off.

Step 4: Validate the extension

Once the extension is tested, the next step is to validate it.

  • Execute the following command in the terminal.
zet validate
  • The validation command checks if the guidelines specified in the plugin-manifest.json file are met.

Once the validation proves successful, you can start packaging the extension files. If not, make the necessary changes and run the command again.

Step 5: Pack the extension

In the terminal, execute the following command

zet pack

All the files of your project directory are not required while uploading the extension on Qntrl Marketplace. Executing this command zips only the essential files and folders like app and plugin-manifest.json, providing a ready to upload zip file.

Alternatively, you can also use Qntrl Studio, our cloud extension builder platform, to build and host extensions of Qntrl. Learn more about Qntrl Studio and its supported features from our help document.
Quick Links