Extension 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"}

 

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

AttributeTypeDescription
titlestringSet a title for your extension activation success or failure. 
messagestringShow the extension activation success or failure message.
notearrayShow 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.
footerstringUse this 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

Sample Code Snippet


response = Map();
success = true;
if(success)
{
	response.put("status","200");
}
else
{
	response.put("status","500");
	response.put("title","Uh-oh!");
	response.put("message","We're sorry! The extension installation failed.");
	note = list();
	note.add("Installation failure might be due to the following reasons:");
	note.add("1. Your account is not in the premium plan.");
	note.add("2. You have not configured the webhook properly.");
	response.put("note",note);
	response.put("footer","Contact support@yourdomain.com for any related help / support.");
}
return response;

 


Note:

The above code snippet will return a success response by default.

User Scenario

Let us consider an extension integrating GitLab and Cliq.

  • First, the installation validator is triggered to confirm if the user is a GitLab admin.
  • Once the installation validator gives a success response, the installation handler is triggered to activate the extension successfully. 

//Extension's Incoming Webhook Endpoint
https://cliq.zoho.com/api/v2/applications/"APP-ID"/incoming?appkey="APP-KEY"&zapikey=" +zapikey (generated for each user) 

 


Note 1:

The extension token or the ZAPI can be created by each user through a token generation dialogue prompt. Refer this help guide on how to generate an extension token?




response = Map();
success = true;
if(success)
{
	response.put("status","200");
	response.put("title","Success!");
	response.put("message","We're glad you chose this extension!");
	note = list();
	note.add("1. Use the Gitlab bot to resolve issues quicker!");
	note.add("2. Use the slash commands and message actions to keep track for activities");
}
else
{
	response.put("status","500");
	response.put("title","Uh-oh!");
	response.put("message","We're sorry! The extension installation failed.");
	note = list();
	note.add("Installation failure might be due to the following reasons:");
	note.add("1. Your account is not in the premium plan.");
	note.add("2. You have not configured the webhook properly.");
	response.put("note",note);
	response.put("footer","Contact support@yourdomain.com for any related help / support.");
}
return response;