Best Practices and Guidelines for Internal Tools

A few important things to consider once you start building your component (command, bot, message action, function) are 

• Design and Usability
• Data Privacy and Compliance
• Performance and Limitations

Design and Usability

A primary point you should check off your list, right when you are building your extension. You can ensure a quality experience to users by keeping the below suggestions in mind. 

Choose your Cliq component based on the use case:

It is important to consider the use case first and then apply it on a component, to understand what would suit the user best. 

For example, lets consider a scenario where a user wants to see the list of top 10 issues from Zoho Projects. Now, this can be easily achieved with a command or a bot. In case of a command, a simple /issues would act as a shortcut and do the trick, where as in case of a bot, it would be either sending a message to the bot thereby invoking the message handler or can be through the bot's menu action. One question to be considered here is, is it valid enough to ask the user to open a bot's chat and execute a menu action just to get the list of issues, when the same can be achieved through a simple shortcut? And with that, you've the answer. 

Offer help tips:

Help tips come in handy when users are struggling to find out how a certain component works. For example, a bot can have an About me or Help menu configured in the menu handler.  This menu can contain details about each component in the bot and how to get started using it! 

Manage configuration/Set up:

Handle user configuration and account set up steps using Connections. 

Message Card Components:

Use Cliq message card components to display information aesthetically. 

Error Handling:

Handle all negative use cases with a relative error response. Predict where a user is likely to go wrong and provide an error message with a help tip to let them know where they're wrong. 

Data Privacy and Compliance - GDPR

What is GDPR?

General Data Protection Regulation is a regulation in EU law on data protection and privacy for all individuals within the European Union (EU) and the European Economic Area (EEA). It also addresses the export of personal data outside the EU and EEA areas. The GDPR aims primarily to give control to individuals over their personal data and to simplify the regulatory environment for international business. (Source: GDPR)

Cliq Platform and GDPR

Cliq Platform is GDPR compliant, strictly adhering to the regulations' by taking measures to let users know that their data is safe with us and that it will be passed to any third party service only with your explicit permission. The best part to note here is that, Cliq Platform is aware of all the third party connections, internal Zoho connections and even Cliq connections made. 

Platform Consent Dialog

First time execution of any internal component will throw a dialog pop-up to the user asking them to grant permission for the command (or) bot (or) message action (or) function to access/ authenticate the variables, APIs and deluge tasks used in the respective component's code. This dialog will be displayed under the following circumstances:

• Command: When a user executes a command for the first time
• Unsubscribed Bots: When a user subscribes to a bot. This is applicable only for newly created bots. 
• Subscribed Bots: When a user sends message to the bot. 
• Message Action: On execution
• Function: On button click / form submission

Granting permissions

Only upon user's permission, the component will be executed to give a response. 

Permission validity

Permissions granted by the user are valid for 60 days. Once the said period is over, the permission is automatically revoked. 

Revoking a permission

Users can also choose to revoke a granted permission for a component at any given point of time. All granted permissions are visible in each component's preview page. Click on the revoke permission, to remove permission!

Let's take a look at the dialog pop-ups displayed for each variable used in the component's code. The consent pop-up has three categories,

• Cliq deluge objects which hold user identity and chat context
• Deluge tasks which can pull data or trigger an action in other Zoho services - through Connections
• External APIs to fetch / push data to a third-party services and Zoho services - through Connections 

For example, let's create a command and use a few Cliq deluge objects in the execution code. On execution for the first time, the usage consent pop-up is displayed to the user. 

info user;
info chat;
info location;
return Map();

The second section in the consent prompt will display details of any Zoho Deluge tasks used in the component code. Create a slash command with the below given code snippet to see how the usage consent dialog is displayed to the user. 

zoho.cliq.postToChat(chat.get("id"),"Hello!");
return Map();

Let us consider one example with a third party service's API, to understand how consent pop up is displayed to the user. The /twitter command allows users to post a tweet right from Cliq. This can work with each user's individual authentication or can work with the admin's (connection owner's) authentication. The connection taken for this example works with the admin's authentication. The sample code snippet for the /twitter command is given below.

result = Map();
//User passes the tweet as arguments along with the command
tweet = arguments;
response = invokeurl
[
	url :"https://api.twitter.com/1.1/statuses/update.json?status=" + tweet
	type :POST
	connection: // Give your connection name
];
info response;
//Get the user's twitter screen name handle name and the tweet's unique ID
user_name = response.get("user").get("screen_name");
info user_name;
id = response.get("id_str");
// Frame the command's execution response
result = {"text":"Your tweet has been posted successfully! Here is the link to [view it](https://twitter.com/" + user_name + "/status/" + id + ")","card":{"title":"Tweeted!","thumbnail":"","theme":"modern-inline"}};
// Return the response to the user
return result;

​​

Performance

• Optimise the number of API calls made by each component in your extension. 
• Use Cliq storage when you want to store data for the user
• Use extension properties to store extension configurations 
• Always use limit in any get list api calls.

Limitations

• The maximum execution time for any platform component is 15 seconds.
• The Cliq getRecords deluge task will pull only a maximum of 100 records.