Invoke URL task

An Invoke URL task is used to access third party services from Cliq through Connections. The Invoke URL task supports four HTTP methods, GET, POST, PUT, DELETE.

Sample Invoke URL task

response=invokeUrl                    
[
*url: <url>
*type: <GET/PUT/POST/DELETE>
parameters: <parameters>        
headers: <headers>             
connection: <connection name>  
files: <file object>            
]; 
//All mandatory parameters are marked with an *

A list of parameters is passed when the invoke URL task is executed. They are explained in this table. 

How to use the invoke URL task 

Let us consider an integration between Cliq and Google Drive, wherein you'll be able to pull files from Google drive straight into Cliq. For this integration to work, start by creating a connection with Google Drive.

1. Create the connection by choosing Google Drive from the pre-registered service. 
2. Give a Connection Name and configure the Use Credentials of Login User option according to your requirement. If the option is enabled, it will work with every user's authentication and in case the option is not enabled, the connection will use the admin (connection owner) authentication.
3. Upon creating the connection, an invoke URL task will be generated. 
4. Now, create a /gdrive command in Cliq.
5. The invoke URL deluge script should be used in the command execution code to let you pull files from Google Drive. 

The Google Drive resource URL that lets you get your Gdrive files is given below. Refer Google Drive API references for more information.

https://www.googleapis.com/drive/v3/files

Take a look at the sample invoke URL deluge script for connecting to Google Drive. The following deluge script, when executed will pull your Google Drive files directly into Cliq. 

response=invokeurl
[
	url :"https://www.googleapis.com/drive/v3/files"
	type :GET
	parameters:params
	connection: //Enter your connection name
];

The params and their description are given below

• url: Provide the get Google Drive files API
• type: The HTTP method for this request is GET
• connection: Give the connection name. Use credentials of login user (checkbox): Enabling this option will ask permission from the user to access their Google Drive account; which means — the connection will work with the user's authentication. In case this checkbox is disabled, the connection will work with the connection owner (creator) authentication. 

/gdrive Command

Let us now put the invoke URL task to use in a command's execution code. The /gdrive command can be used to pull files from the user's google drive directly into Cliq. The file to be pulled is given as arguments during command execution. Refer the command execution handler to understand more. 

    //User can pass search keyword as arguments along with the command
    searchKeyword = arguments;
    messageTitle = "Files in your drive";
    if(!searchKeyword.isNull()) {
        messageTitle = "Files in your drive for search *" + searchKeyword + "*";
    }
    //Invoking Google drive's API
    params = Map();
    params.put("q","name contains '" + searchKeyword + "' and 'me' in owners");
    params.put("pageSize","10");
    params.put("restrictToMyDrive","true");
    params.put("fields","*");
    response = invokeurl
    [
        url :"https://www.googleapis.com/drive/v3/files"
        type :GET
        parameters:params
        connection:"gdrive"
    ];
    info response;
    files = response.get("files");
    list = List();
    //Formatting the files response to post as message
    for each  file in files
    {
        if(file.get("trashed"))
        {
            continue;
        }
        label = file.get("name").trim();
        if(file.containsKey("webContentLink"))
        {
            label = "[" + file.get("name").trim() + "](" + file.get("webContentLink") + ")";
        }
        else if(file.containsKey("webViewLink"))
        {
            label = "[" + file.get("name").trim() + "](" + file.get("webViewLink") + ")";
        }
        list.add(label);
    }
    response = Map();
    slidesList = list();
    slidesList0 = Map();
    slidesList0.put("type","list");
    slidesList0.put("data",list);
    slidesList.add(slidesList0);
    response.put("slides",slidesList);
    response.put("text",messageTitle);
    // Return the response to the user
    return response;
    

Take a look at the GIF below to understand how the /gdrive command is executed to pull files directly from your Google Drive. 

Apart from the mandatory parameters, there are a few additional parameters that can be used in the invoke URL task. 

• Using the headers parameter
• Using the files parameter
• Passing additional parameters

How to use the headers parameter in the invoke URL task 

Headers in REST

HTTP Headers are an important part of an API request and the corresponding response. They represent the metadata associated with the API request and response for the following

• API request and Response body
• Authorization Requests
• Response Caching 
• Response Cookies

Some of the most common headers that needs to be passed with an API request are:

• Authorization: Authentication credentials for the resource being requested
• Content-Type: Indicates the media type of the resource

Message Action - Upload files to Google Drive

Take for example, a message action to upload files shared in Cliq directly to your Google Drive account. For this integration to work, create an integration with Google Drive. The google drive resource URI for uploading files is given below. Refer Drive API references for more information

​
https://www.googleapis.com/upload/drive/v3/files

A sample invoke URL deluge script for the Google Drive connection is shown below.

​
response = invokeUrl [
    url : "https://www.googleapis.com/upload/drive/v3/files"
    type : POST
    headers : gDriveHeaders
    files : gDriveFiles
    connection : // Give your connection name
];

The task parameters and their description are:

• url: Give the google drive API to send attachments/ upload files.
• type: Specify the HTTP method - POST
• connection: Give the connection name. This connection has the use credentials of login user (user access value) set as true. When this code is executed, the user will be prompted to give access and perform integration with their own credentials.
• headers: Specify the request headers to be passed. headers is of the data type MAP. 
• files: The files object of the data type LIST is used to store the list of files.  

Uploading a file in Cliq to Google Drive

Add a file shared in chat directly to your GDrive account through the upload file message action. 

message = Map();
file = attachments.get(0);
params = Map();
params.put("name",file);
comments = Map();
comments.put("stringPart","true");
comments.put("paramName","metadata");
comments.put("content",params.toString());
comments.put("contentType","application/json");
comments.put("encodingType","UTF-8");
fileList = List();
fileList.add(comments);
fileList.add(file);
driveHeaders = Map();
driveHeaders.put("Content-Type","multipart/related");
response = invokeurl
[
	url :"https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart"
	type :POST
	headers:driveHeaders
	files:fileList
	connection: //Give your connection name
];
info response;
fileDetails = invokeurl
[
	url :"https://www.googleapis.com/drive/v3/files/" + encodeUrl(response.get("id")) + "?fields=name,id,webViewLink&restrictToMyDrive=true"
	type :GET
	connection: //Give your connection name
];
button = List();
if(!fileDetails.get("webViewLink").isNull())
{
	button.add({"label":"View","action":{"type":"open.url","data":{"web":fileDetails.get("webViewLink")}},"type":"+"});
}
message = {"text":"The file [" + response.get("name") + "]("+fileDetails.get("webViewLink")+") has been uploaded to your Google Drive. :thumbsup:"};
return message;

How to use the files parameter in the invoke URL task 

As an example let us again consider a message action - to upload files shared in chat directly to your Zoho Docs. The Zoho Docs resource URL to upload files is shown below. Refer Zoho Docs upload file API for more details about the query string parameters required

https://apidocs.zoho.com/files/v1/upload

To create a connection with Zoho Docs, follow the below given steps:

1. Choose Zoho under the pick your service section in the Connections page
2. Give your connection name and under scopes — select ZohoPC/docsapi 
3. Click on Create and Connect to create the connection with Zoho Docs

A sample invoke URL deluge script for the Zoho Docs connection with the file upload API is shown below.

​
response = invokeurl
[
	url :"https://apidocs.zoho.com/files/v1/upload"
	type :POST
	files: fileslist
	connection: //Give your connection name
];

• url: Give the Zoho Docs api to send attachments/ upload files.
• type: Specify the HTTP method - POST
• connection: Give the connection name. This connection has the use credentials of login user (user access value) set as true. When this code is executed, the user will be prompted to give access and perform integration with their own credentials. headers: Specify the request headers to be passed. 
• files : The files object of the data type LIST is used to store the list of files.  

Uploading a file in Cliq to Zoho Docs

Add a file shared in chat directly to your Zoho Docs account through the Upload to ZDocs message action.

output = Map();
docsparams = Map();
att = attachments.get(0);
docsparams.put("stringPart","true");
docsparams.put("paramName","filename");
docsparams.put("content","" + att);
fileslist = List();
fileslist.add(docsparams);
att.setParamName("content");
fileslist.add(att);
response = invokeurl
[
	url :"https://apidocs.zoho.com/files/v1/upload"
	type :POST
	files:fileslist
	connection: //Give your connection name
];
info response;
result = response.get("response").toList().get(2).toList();
info result;
docid = result.toMap().get("result").toList().get(1).toMap().get("uploaddocid");
output.put("text","Uploaded to your ZOHO Docs! (y) [View in Docs](https://docs.zoho.com/file/" + docid + ")");
return output;

Using the parameters attribute in the invoke URL task

The parameters attribute of the datatype MAP can be used in the invoke URL task when an API requires you to send additional data in the request body. Let us take an example of a weekly scheduler that brings the list of major open issues in a project. The resource URL to get the list of issues from a project is given below. Refer Zoho Projects API guide for more details. 

https://projectsapi.zoho.com/restapi/portal/[PORTAL ID]/projects/[PROJECT ID]/bugs/

The first step would be to create a connection with Zoho Projects and generate the invoke URL task. The steps to create a connection with Zoho Projects is given below

1. Choose Zoho under the pick your service section in the Connections page
2. Give your connection name and under scopes — select ZohoProjects/projectsapi
3. Click on Create and Connect to create the connection with Zoho Docs

A sample invoke URL deluge script for the Zoho Projects connection with the Get all issues API is shown below.​

getissues = invokeurl
[
	url :"https://projectsapi.zoho.com/restapi/portal/[PORTAL ID]/projects/[PROJECT ID]/bugs/"
	type :GET
	parameters: paramsMap
	connection: //Give your connection name
];

The params and their description are given below

• url: Provide the get all issues/bugs API
• type: The HTTP method for this request is GET
• connection: Give the connection name. Use credentials of login user (checkbox): Enabling this option will ask permission from the user to access their Google Drive account; which means — the connection will work with the user's authentication. In case this checkbox is disabled, the connection will work with the connection owner (creator) authentication. 
• parameters : A map containing all the request parameters. 

The issues scheduler scipt is shown below. This scheduler will be triggered every week to pull the list of recently filed open issues with severity marked as Major and post it in a channel. 

paramsMap = Map();
paramsMap.put("statustype","open");
paramsMap.put("severity",{"Provide the severity ID"});
paramsMap.put("index",0);
paramsMap.put("range","5");
paramsMap.put("sort_order","ascending");
getissues = invokeurl
[
	url :"https://projectsapi.zoho.com/restapi/portal/[PORTAL ID]/projects/[PROJECT ID]/bugs/"
	type :GET
	parameters:paramsMap
	connection: //Give your connection name
];
info getissues;
bugs = getissues.toMap().get("bugs");
info bugs.size();
rows = List();
for each  bug in bugs
{
	row = Map();
	row.put("Issue Title",bug.get("title"));
	row.put("Issue ID",bug.get("bug_number"));
	row.put("Severity",bug.get("severity").toMap().get("type"));
	rows.add(row);
}
message = {"text":"List of Major issues pending this week.","card":{"theme":"modern-inline","title":"Issue List:"},"bot":{"name":"Team Bot","image":""},"slides":{{"type":"table","title":"","data":{"headers":{"Issue Title","Issue ID","Severity"},"rows":rows}}}};
info zoho.cliq.postToChannel(channel_unqiue_name,message);