Functions
IN THIS PAGE
1. Functions overview 🔗
Functions are collections of Zoho's Deluge scripts that enable the addition of new functionalities and the execution of specific tasks. These sets of Deluge scripts can be organized under a designated name and can be invoked from within the application. Deluge, being a low-code scripting language, facilitates the development of structured, effective, and easily maintainable code. By structuring Deluge scripts in a modular way, functions help improve efficiency and maintainability.
In the Bigin Developer Console, functions are essential in customizing toppings or integrations to meet specific requirements. For example, functions can be used in toppings and integrations as follows:
- Automating tasks and integrating various third-party applications.
- Defining custom business logic or rules applicable to data or processes.
- Manipulating data, including sorting, filtering, and transforming.
- Acting as webhooks to trigger actions in response to events or data changes.
Moreover, the Bigin Developer Console supports Bigin's Deluge Functions offered by Bigin. These functions simplify working with records by serving as API wrappers. They enable direct API calls without the need for manual coding to handle API endpoints, HTTP methods, request parameters, or authentication mechanisms. Input for these functions is accepted in the form of key-value pairs, similar to JSON.
💡 Tip: Bigin's Deluge Functions dynamically construct URLs based on Data Centers (DCs), which eliminates the need to write complex code for different URLs.
In the Bigin Developer Console, functions are categorized into two types based on the actions they perform:
Standalone functions
Standalone functions are independent blocks of Deluge scripts that you can invoke from various places within the topping. You can customize these functions to perform a specific task that is not currently offered in Bigin.
These functions can pass one or more arguments of compatible data types and return values with one of the supported data types. The Bigin Developer Console allows you to choose the return type and define the input parameters. Additionally, the functions that are associated with Custom Buttons, Workflows, and Schedules are also known as Standalone Functions.
Rest API functions
REST API functions allow you to trigger them from various sources, such as within a topping or from any third-party applications using its API URL. Third-party applications can call upon this REST API function as a webhook URL. This way, the REST API function provides a convenient and efficient method for integrating Bigin with external applications.
2. Create functions 🔗
In the Bigin Developer Console, create a standalone or REST API function by navigating to the Automate > Functions section.
Firstly, in the Functions section, click the New Function button, and then type a name in the Function Name field.
💡 Tip: Spaces are not allowed in function names, but you can use underscores instead.
Next, based on your requirement, choose any one of the following:
For a standalone function:
To execute this function as a standalone function, select No for the Invoke as REST API option.
Next, choose a Return Type for the function.
To specify arguments for the function, click Add Arguments, provide a name for the argument, and then select a data type for it. You may provide multiple arguments or leave them empty.
For a REST API function:
To execute this function as a REST API function, select Yes for the Invoke as REST API option.
✍ Notes:
- By default, the return type for REST API functions is set to the string data type, while the argument is set to the Map type and it's referred to as crmAPIRequest.
- Once the custom function is set as a REST API function, you cannot change it back to a standalone function.
Lastly, you can click Next. When the Deluge Script Editor appears, add the appropriate script for your use case, and then click Save & Close.
3. Basic REST API function definition 🔗
A Basic REST API function should be defined in a way to handle incoming API requests and return structured responses. Here's a sample REST API function that is constructed to handle various HTTP methods and provide appropriate responses.
Sample Deluge code snippet - REST API function
Copiedmethod = crmAPIRequest.get("method");
params = ifNull(crmAPIRequest.get("params"), Map());
if(method.equalsIgnoreCase("get"))
{
info "[INFO] Rest API HTTP method :: GET";
// Your custom logic here...
resp_body = {"code":"SUCCESS","status":"success","message":"Function executed successfully"};
}
else if(method.equalsIgnoreCase("post"))
{
request_body = ifNull(crmAPIRequest.get("body"),Map());
info "[INFO] Rest API HTTP method :: POST";
// Your custom logic here...
resp_body = {"code":"SUCCESS","status":"success","message":"Function executed successfully"};
}
// @Description: Response returned by REST API
crmAPIResponse = Map();
// @Description: Response code for CF as Rest API
status_code = 200;
crmAPIResponse.put("status_code",status_code);
// @Description: Response body for CF as Rest API
crmAPIResponse.put("body",resp_body);
// @Description: Response headers for CF as REST API
crmAPIRespHeaders = Map();
crmAPIRespHeaders.put("content-type","application/json;charset=UTF-8");
crmAPIRespHeaders.put("content-disposition","attachment; filename=response.json");
crmAPIRespHeaders.put("x-frame-options","SAMEORIGIN");
crmAPIResponse.put("headers",crmAPIRespHeaders);
return {"crmAPIResponse":crmAPIResponse};It's worth noting the following request and response objects:
a. REST API function parameter - crmAPIRequest 🔗
The crmAPIRequest argument contains the entire request object and dynamically passes keys when the REST API function is triggered. This means there is no need to pass multiple arguments in the function as crmAPIRequest already holds all the required data. Moreover, the request object will automatically be mapped to the crmAPIRequest argument.
Get the details of the input types as shown in the table:
Name | Description | Syntax |
|---|---|---|
Body | The body key in crmAPIRequest can obtain the data that is sent in the request body when a POST API call is made. | request_body = crmAPIRequest.get("body"); |
Parameters | The params key in crmAPIRequest can obtain the data that is sent as query parameters in the API request. | parameters = crmAPIRequest.get("params"); |
File content | The file_content key in crmAPIRequest can obtain the multipart content passed as a file to the API request.
Supported File Formats: TXT, CSV, JSON, XML, PDF Maximum Upload Size: 4MB | fileContent = crmAPIRequest.get("file_content"); |
User information | The user_info key in crmAPIRequest can obtain user details. You can use the API key method to get super admin details. | user_info = crmAPIRequest.get("user_info"); |
HTTP method | The method key in crmAPIRequest can obtain the HTTP method used in the API request.
Supported HTTP Methods: GET POST | method = crmAPIRequest.get("method"); |
Headers | The headers key in crmAPIRequest can obtain details from the header of the request, such as additional information about the request. | headers = crmAPIRequest.get("headers"); |
b. REST API function response - crmAPIResponse 🔗
The default return type for REST API functions is String. However, you can specify the response as a String, or additionally, define a response object using crmAPIResponse.
crmAPIResponse is an object that allows you to define and structure the response of a REST API function in Bigin. You can use crmAPIResponse to send structured data, which includes key-value pairs, status codes, and messages that ensures a well-formatted response.
A sample crmAPIResponse object in Deluge looks like this:
CopiedcrmAPIResponse = Map();
// @Description: Response code for CF as Rest API
status_code = 200;
crmAPIResponse.put("status_code",status_code);
// @Description: Response body for CF as Rest API
body = Map();
body.put("status","success");
body.put("code","SUCCESS");
body.put("message","Function executed successfully.");
crmAPIResponse.put("body",body);
// @Description: Response headers for CF as REST API
headers = Map();
headers.put("content-type","application/json;charset=UTF-8");
headers.put("content-disposition","attachment; filename=response.json");
headers.put("x-frame-options","SAMEORIGIN");
crmAPIResponse.put("headers",headers);
return {"crmAPIResponse":crmAPIResponse};The crmAPIResponse object includes the following specifications:
Status Code
The status code key is used to determine the outcome as a response code of the REST API request. The common status codes are 200, 204, 404, or 500.
CopiedcrmAPIResponse.put("status_code",status_code);Body
The body key is used to pass the information that needs to be sent as a response to a third-party's request. The default value of body is empty.
CopiedcrmAPIResponse.put("body",body);Headers
The headers key defines HTTP headers that are sent with the response. These headers can provide additional instructions to the client, such as status codes, content type, cache control, or file disposition.
CopiedcrmAPIResponse.put("headers",headers);✍ Note: A sample body and headers are included in the above snippets. You can use your preferred keys for both body and headers map.
To know more details about how to invoke this function as REST API, see Invoking REST API functions from third-party applications.
4. Invoke standalone and REST API functions 🔗
Once you've created a function, the next step is to add your custom logic and invoke it from other functions or any external sources. You can invoke the standalone and REST API functions in the following ways:
a. Invoking standalone functions from other functions 🔗
Standalone functions do not run automatically and need a trigger to start their execution. This trigger could be a workflow, schedule, invoking from a related list, or button click, which depends on the function and its purpose. You can create separate functions for each trigger and call the standalone function from within those specific functions.
A sample syntax for invoking a standalone function within other functions is shown below:
Copiedresponse = <topping_namespace>.<function_name>(<arguments>);✍ Note: REST API functions can be invoked as standalone functions whenever needed.
Standalone functions cannot be invoked outside of the current topping setup, and they cannot invoke functions created for triggers such as workflow, schedule, related list, and button.
Sample Deluge code snippet
Copied// Your custom logic goes here....
info "[INFO] Function Arguments :: " + arguments;
// \"StandAloneFunction2\" is a Standalone function present in this topping.
func_response = functions.StandAloneFunction2();
info "[INFO] Function Returned :: " + func_response;b. Invoking REST API functions from standalone functions 🔗
The standalone function invokes a REST API function that has already been defined within the topping being developed. In the standalone function, you can send data as a map to an internal REST API function, which processes the request, performs necessary actions, and then returns the response. This allows you to leverage REST API functions directly within the topping to exchange data and trigger actions seamlessly.
Sample Deluge code snippet
Copied// Your custom logic goes here....
// \"RestAPIFunction\" is a Rest API function present in this topping.
crmAPIRequest = Map();
func_response = functions.RestAPIFunction(crmAPIRequest);
info "[INFO] RestAPI Function response :: " + func_response;
return func_response;c. Invoking REST API functions from third-party applications 🔗
Invoking REST API functions from an external source, such as third-party applications, offers seamless integration. The Bigin Developer Console provides a simple way to invoke a function as REST API. Navigate to your REST API function, and click the settings icon next to the function name. Then, select the Invoke as REST API to open the Invoke Function dialog.
To know how the REST API functions are defined, see Basic REST API function definition.
When a function is invoked as a REST API, it generates a URL that allows for accessing and executing the function – it also serves as a webhook. This URL can then be used by external sources, such as third-party applications, to call the function and perform specific tasks.
✍ Notes:
- When you invoke a REST API function to generate URL, you'll receive two separate URLs. One of these URLs is meant for testing purposes and is called the Sandbox URL. The other URL is meant for actual use in third-party applications and is called the Production URL. It is important to understand the difference between these two URLs and use them accordingly in order to ensure the proper functioning of the REST API function.
- Do not modify the query parameters in the REST API Function's URL when sharing it as it may disrupt the function's execution.
For example, let's say you want to receive notifications to your Bigin account from other services whenever certain events occur within those services, you can take advantage of the webhook support offered by many third-party applications. Through the use of the REST API function, a URL can be generated and manually registered as a webhook URL in third-party applications with the help of a user-friendly option provided by the third-party application.
d. Invoking REST API functions from widgets 🔗
The SDK function – ZOHO.BIGIN.FUNCTIONS.execute() enables you to invoke REST API functions from widgets. You can import this function into the widget code using the Bigin's SDK library.
A sample SDK function for invoking a REST API function from a widget is shown below:
CopiedZOHO.BIGIN.FUNCTIONS.execute(function_name, req_data);The function_name refers to the API name of the REST API function. It can be obtained from the Sandbox URL or Production URL generated in step 3(c).
https://www.zohoapis.com/bigin/v1/functions/functions_restapifunction/actions/execute?auth_type=apikey&zapikey=<zapikey>
The req_data refers to the user inputs provided by the widgets to the REST API function. These inputs can be retrieved from the widget using the params argument.
Sample JavaScript code snippet
Copiedreq_data = {}; // passing custom request body as per your use-case
ZOHO.BIGIN.FUNCTIONS.execute('functions__restapifunction', req_data).then(function(response)) {
// success response here
console.log(response);
}, function(response) {
// error response here
console.log(response)
}))5. Schedule functions 🔗
Schedule functions are functions that are linked to schedules in order to carry out a specific task at a predetermined time. This means, through the use of schedule functions, you can set up customized actions to be performed at a specific time or on a recurring basis. This allows you to streamline your scheduled actions and save time by automating routine tasks.
Schedule functions can be defined when creating a schedule action in the Bigin Developer Console, and they can be edited and managed in the schedules section of the console. These functions can be written in Deluge scripts. It is also possible to invoke standalone and REST API functions from scheduling functions, but the reverse is not possible.
a. Create a schedule function 🔗
To create a schedule function, access the Bigin Developer Console and navigate to Automate > Schedules.
Click + Create New Schedule, enter a name and description for the schedule.
Select Writing Function from the Function to be executed drop-down, which will open the Create New Function section.
Provide details such as Function Name, Display Name, and Description, and then click Create.
The Deluge Script editor will appear, where you can add the script logic according to your use case and save the changes.
To execute the function at a scheduled time, specify the execution start data, frequency, and end details, and then save it.
✍ Note: You must set the execution start date and time ahead of the current time.
Additionally, to edit the scheduling function, hover over the Function to be executed section and click the edit icon next to the function name. To make changes in the deluge script of the function, click Edit Function.
Sample Deluge code snippet
Copied// Your custom logic goes here....
info "[INFO] Schedule Function executed at " + toDateTimeString(zoho.currenttime.toString().unixEpoch(),"dd/MM/yyyy@HH:mm:ss z : ","IST");6. Other functions 🔗
Toppings provide additional functions that can be used for executing simple tasks. These functions include:
a. Functions embedded with custom buttons and related lists 🔗
Functions can be used within custom buttons to automate actions based on user interactions. These custom buttons can be positioned in various areas of the modules, which allows users to trigger functions with a single click. These functions are written in the Deluge Script editor and can interact with Bigin records, external APIs, or internal workflows. For more information on how to create embedded functions with custom buttons, see Buttons.
In addition to custom buttons, functions can be used in custom related lists to dynamically display related data within the detail page of a record. This allows users to fetch and view related records directly from Bigin. For more information on how to use functions in custom related lists, see Related lists.
Here's a sample code snippet for the function used in custom buttons:
Sample Deluge code snippet
CopiedcontactId = contact.get("Contacts.ID");
contactRecord = zoho.bigin.getRecordById("Contacts","contactId",Map(),"functions__bigin1");
info "[INFO] Contact Record response :: " + contactRecord;
// Your custom logic goes here...
return "SUCCESS";b. Install and uninstall action functions 🔗
Install and Uninstall Action Functions help automate actions during installation, upgrades, and uninstallation. These functions ensure smooth topping management and seamless user experience.
To create these functions, access the Bigin Developer Console and navigate to Install Actions > Topping.
The Deluge script editor appears, where you can add your custom logic for both install and uninstall actions.
💡 Tip: Click the right arrow on the scroll bar to view the available keys that can be passed to these functions.
Install action functions
Install Action Functions are the scripts that execute immediately after all components of a topping is installed or updated. These scripts help in automating initial setup tasks such as notifying Bigin users or external systems about the installation, which ensures the topping is ready for use.
Each topping supports a single install action function, which triggers automatically upon installation or update and executes only once.
Sample Deluge code snippet
Copiedinstalled_user_id = installParamMap.get("organizationId");
installed_org_id = installParamMap.get("installerId");
is_topping_installed = installParamMap.get("isInstall");
is_topping_upgraded = installParamMap.get("isUpgrade");
previous_version_number = installParamMap.get("previousVersion");
info "[INFO] Function triggered after topping installation";
// Your custom logic goes here...Uninstall action functions
Uninstall Action Functions are the scripts that allow you to execute specific actions when a topping is removed. This includes tasks like cleaning up data, revoking access, or notifying external systems. The script executes automatically during the uninstallation process and ensures no data or configurations are left behind.
Sample Deluge code snippet
Copieduninstalled_user_id = installParamMap.get("organizationId");
uninstalled_org_id = installParamMap.get("installerId");
info "[INFO] Function triggered before topping un-installation";
// Your custom logic goes here...