Building Extensions

Building Extensions: 

What are extensions?

Extensions are bundles of practicable code integrations; containing commands, bots, message actions, functions, channels combined together to suit your client or user requirements. Extensions created by you are listed under the My Extensions section. The extensions installed from Zoho Marketplace are listed under the Installed Extensions section.   

How to build an extension?  

Building an extension isn't as daunting as it sounds. Follow the below steps to create an extension:

  • First, create the commands, bots, message actions, functions you would like to bundle together as an extension. These components are the building blocks of your extension, refer internal tools to know more about how to create them. Once you have all the above mentioned components ready, you can create your extension
  • Click on the Settings icon and navigate to the Integrations tab and select Extensions  
  • Click Create Extension and give your extension a name, description, image and  select the commands, bots, message actions, functions and channels.
  • Once you have selected the components to be included, select the Create button to get the first version of your extension ready.  Simultaneously a sandbox version of your extension will be installed along with the extension components (internal tools ).   
  • The sandbox version of your extension should be used for developing extension upgrades and publishing them. 
  • This extension will be listed under the My Extensions section. You can either Publish or Edit it further.  
Note: It is not mandatory for an extension to have all the above mentioned components. You can have an extension containing only a single component (commands, bots, message actions, functions, channels) or bundle each component together as an extension.  

Cliq provides your extension an App Key that handles all API Endpoints, Installation Validator and Extension Handlers to streamline the extension installation. Click on the extension name to view details about the App Key, Installation Validator and Extension Handlers. 

Where can you create Extensions?

Extensions Preview

App Key:

The extensions created and listed under the My Extensions sections are the sandbox versions. This allows you to test the extension for issues before proceeding to publish. Each extension is provided with two app keys, the sandbox App key and the marketplace App key by default. App keys are like a token for your extensions and should be used in all api endpoints. You can also generate a new set of App keys by clicking the Generate option. The App key should be sent as a request parameter with the param name, appkey for posting messages to channels, bots and users and also used for all api endpoints. The sandbox app key can be while testing the extension in the sandbox environment.  

Installation Validator:

The installation validator is triggered to validate the user before installing the extension.If the installation validator is not configured, user will be allowed to install the extension without validation. Click Edit Code under Installation Validator to write the script. You will get the below given attributes when the installation handler is executed:

AttributeDescription
userDetails of the user who is installing the extension.
app_info

 Details of the extension being installed.

{"current_version":"1.5", "type": "install"}

Details of the extension being upgraded.

{"current_version":"1.5","existing_version":"1.3","type":"upgrade"}

Validation Success:

 If the installation validator is configured, the user will be allowed to install the extension only when the validator returns a response 200. 

Validation Failed:

The installation validator can be programmed to render a response message to the user when the extension validation fails. The message can have the following attributes:

  • title - Attribute of the type String, can be used to set a title for your extension installation failure. 
  • message - Attribute of the type String, can be used to show the extension installation error message.
  • note - Attribute of the type Array, can be used to show the user a list of reasons why the installation was not successful. 
  • footer - Attribute of the type String, can be used to give the user any extra information. For example, the support email ID can be given in the footer. 

Sample message when extension validation fails

Installation Handler:

This handler is triggered after the installation of the extension. The main purpose of this handler is to let you (extension creator) handle certain processes, like configuring webhooks after a user installs the extension. Click Edit Code under Installation Handler to write the script. If this handler is not configured, the extension will be activated by default. You will get the following attributes when the installation handler is executed:

AttributeDescription
userDetails of the user who is installing the extension.
app_info

 Details of the extension being installed. 

{"current_version":"1.5", "type": "install"}

Details of the extension being upgraded. 

{"current_version":"1.5","existing_version":"1.3","type":"upgrade"}

 
authtokenThis authtoken is generated when the installation handler is executed and should be used to configure the webhooks in external services with the extension's incoming webhook handler. 

The installation handler can also be used to give a response message to the user upon successful activation of the extension or when the extension activation fails. The message can have the following attributes:

  • title- Attribute of the type String, can be used to set a title for your extension activation success or failure. 
  • message- Attribute of the type String, can be used to show the extension activation success or failure message.
  • note- Attribute of the type Array, can be used to show the user a list of reasons why the extension activation was not successful, in case of successful activation this attribute can be used to show a list of key points to be noted about the extension.
  • footer- Attribute of the type String, can be used to give the user any extra information. For example, the support email ID can be given in the footer. 

Activation Success:

The installed extension will be activated, only when the installation handler returns 200 as the status response. A sample  extension activation success message and how it will be displayed to the user is shown below.

Sample message when Extension is installed successfully

Activation Failure:

The installed extension will not be activated when the installation handler does not return 200. In this case, the extension status will be displayed as Installed. In cases where the extension is not activated, the user can click the Activate option when hovered over the extension name under installed extensions. A sample extension activation failed message is shown below:

Sample message when Extension installation fails

Incoming Webhook Handler:

Integration with external applications can be done with the help of incoming webhook APIs. A ZAPI key will be provided during the extension installation in Cliq should be used for handling incoming webhooks and messaging apis. You will get the below given list of attributes when the extension's incoming webhook handler is executed:

AttributeDescription
headersHeader details from the request made to the server.
parametersParameter details from the request made to the server.
bodyRequest body as the type string.
http_methodGET | PUT | POST | DELETE
userDetails of the user triggering the handler.
ZAPI key (zapi key)The authtoken received when the installation handler is executed.
 App key (appkey)This market place app key provided once the extension is created.

In this sample URL, use the auth token received when the installation handler is executed as a value for the key zapikey and substitute the app key provided once the extension has been created as a value for the key appkey.

https://cliq.zoho.com/api/v2/applications/{APPID}/incoming?zapikey={AUTHTOKEN}&appkey={APP_SECRET_KEY}

Editing an extension :

Only extensions created by you can be edited.

To edit an extension, click Edit by hovering over then extension name.

Edit an Extension

  • Editing an extension before publishing:

Cliq permits you to change the extension name, description, image and even alter the components you would like to bundle. Just unchecking a previously added component will remove it from the extension bundle. 

  • Editing an extension after publishing:  

Once an extension is published, the extension name cannot be edited. Only the extension description, image and the components can be edited. 

Deleting an extension:

Delete an extension by clicking on the extension icon present next to the extension name. Deleting will not delete the extension from marketplace.  

Deleting an Extension

 

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohocliq.com