Bigin DRE Functions

Make use of our DRE functions in your toppings and integrations to enhance the Bigin's capabilities. This section provides information about the pre-built DRE functions and their descriptions, including parameters and examples.

Create a record

The function zoho.bigin.createRecord() creates a record within the specified module of Bigin. This function takes in a set of parameters and other necessary information to create a new record. Moreover, this function returns a response as a map with the newly created record ID and any other relevant information.

The following section outlines the function's parameters:

<module_name> stringrequired

This parameter indicates the API name of the module in which the record will be created. For example, if you want to create a record in the Companies module, you would pass Accounts as the value of <module_name>.

You can get the API name of modules from Get all modules.

<record_details> maprequired

This parameter is a map that provides necessary information to create a new record. The keys indicate the field API names and values indicate the values to be set for corresponding fields. For example, if you want to create a new contact record with Last_name as Williams, you should pass the value of <record_details> in the following format:

<record_details> = {"Last_name":"Williams"}

You can get the field API names from Get all records.

For information about mandatory fields in each module, see Modules and Fields.

<optional_details> mapoptional

This parameter is a map that includes any other optional details such as the execution of scripts or triggering of workflows when a new record is created. For example, if you want to trigger a workflow after the record is created, you should pass the value of <optional_details> in the following format:

<optional_details> = {"trigger":{"workflow"}}

When this parameter is not passed, approvals and stage transition rules execute by default. To prevent all operations from executing, you can pass an empty map with the trigger key set to an empty value.

<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.createRecord(<module_name>, <record_details>, <optional_details>, <connection_link_name>);

The function returns a map and stores it in <variable>. It includes success and failure details, and is equivalent to the Add records API response. To check the response, refer to the Add records API response object.

Update a record

This function zoho.bigin.updateRecord() is used to update values of a record within the specified module of Bigin using a record Id. This function takes in a set of parameters and other necessary information to update record values. Moreover, this function returns a response as a map with updated record details.

The following section outlines the function's parameters:

<module_name> stringrequired

This parameter indicates the API name of the module in which the values of a record with a specified Id are updated. For example, if you want to update the record's values from the Companies module, you would pass Accounts as the value of <module_name>.

You can get the API name of modules from Get all modules.

<record_Id> numberrequired

This parameter indicates the ID of a record within a specified module for which the values are updated.

You can get the ID of a record from Get all records.

<record_details> maprequired

This parameter is a map that provides the necessary information to update an existing record. The keys indicate the field API names and values indicate the values to be set for corresponding fields. For example, if you want to update a contact record with Last_name as Williams, you should pass the value of <record_details> in the following format:

<record_details> = {"Last_name":"Williams"}

You can get the field API names from Get all records.

For information about mandatory fields in each module, see Modules and Fields.

<optional_details> mapoptional

This parameter is a map that includes any other optional details such as execution of scripts or triggering of workflows when a record is updated. For example, if you want to trigger a workflow after the record is updated, you should pass the value of <optional_details> in the following format:

<optional_details> = {"trigger":{"workflow"}}

When this parameter is not passed, approvals and stage transition rules execute by default. To prevent all operations from executing, you can pass an empty map with the trigger key set to an empty value.

<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.updateRecord(<module_name>, <record_id>, <record_details>, <optional_details>, <connection_link_name>);

The function returns a map and stores it in <variable>. It includes creation and modification details, and is equivalent to the Update records API response. To check the response, refer to the Update records API response object.

Upsert a record

The function zoho.bigin.upsert() is used to update the values of a record within the specified module of Bigin using a record ID. Moreover, if the record ID is not provided, this function creates a new record with the specified values. This function takes in a set of parameters and other necessary information to update the existing record or create a new record. This function also returns a response as a map with the updated record details or newly created record ID and any other relevant information.

The following section outlines the function's parameters:

<module_name> stringrequired

This parameter indicates the API name of the module in which the values of a record with a specified Id are updated or a new record is created. For example, if you want to upsert a record from the Companies module, you would pass Accounts as the value of <module_name>.

You can get the API name of modules from Get all modules.

<record_details> maprequired

This parameter is a map that includes the necessary information to update an existing record. The keys indicate the field API names and values indicate the values to be set for corresponding fields. To identify a record, you should provide the record ID along with the updated values. If the record ID is not provided, a new record with the specified values is created. For example, if you want to update a contact record with Last_name as Williams, you should pass the value of <record_details> in the following format:

<record_details> = {"id":"50639489594738889", Last_name":"Williams"}

You can get the field API names from Get all records.

For information about mandatory fields in each module, see Modules and Fields.

<optional_details> mapoptional

This parameter is a map that includes any other optional details such as execution of scripts or triggering of workflows when a record is updated or created. For example, if you want to trigger a workflow after the record is updated or created, you should pass the value of <optional_details> in the following format:

<optional_details> = {"trigger":{"workflow"}}

When this parameter is not passed, approvals and stage transition rules execute by default. To prevent all operations from executing, you can pass an empty map with the trigger key set to an empty value.

<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.upsert(<module_name>, <record_details>, <optional_details>, <connection_link_name>);

The function returns a map and stores it in <variable>. It includes creation and modification details, and is equivalent to the Upsert records API response. To check the response, refer to the Upsert records API response object.

Get records

The function zoho.bigin.getRecords() is used to fetch records from the specified module of Bigin. This function takes in a set of parameters and other necessary information to fetch records. Moreover, this function returns a response as a map that contains all the details of fetched records.

The following section outlines the function's parameters:

<module_name> stringrequired

This parameter indicates the API name of the module from which records are fetched. For example, if you want to fetch records from the Companies module, you would pass Accounts as the value of <module_name>.

You can get the API name of modules from Get all modules.

<query_value> mapoptional

This parameter is a map that includes request parameters used in the Get Records API. These parameters are especially included to filter and fetch records based on specific conditions.

Notes:

  • The keys and values for this parameter should be provided as mentioned in the Get Records API.
  • To prevent this query parameter from executing, you must pass an empty map. For example: map()
<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.getRecords(<module_name>, <query_value>, <connection_link_name>);

The function returns a map and stores it in <variable>. It includes details of fetched records, and is equivalent to the Get records API and Get records from a Team Pipeline API response. To check the response, refer to the Get records API and Get records from a Team Pipeline API response object.

Get a record by ID

The function zoho.bigin.getRecordById() is used to fetch a record from the specified module of Bigin using a record Id. This function takes in a set of parameters and other necessary information to fetch the record. Moreover, this function returns a response as a map that contains the details of the fetched record.

The following section outlines the function's parameters:

<module_name> stringrequired

This parameter indicates the API name of the module from which the record with the specified ID is fetched. For example, if you want to fetch a record with the specified ID from the Companies module, you would pass Accounts as the value of <module_name>.

You can get the API name of modules from Get all modules.

<record_Id> numberrequired

This parameter indicates the ID of the record that needs to be fetched.

You can get the ID of a record from Get all records.

<query_value> mapoptional

This parameter is a map that includes request parameters used in the Get all records. These parameters are especially included to filter and fetch records based on specific conditions.

Notes:

  • The keys and values for this parameter should be provided as mentioned in the Get Records API.
  • To prevent this query parameter from executing, you must pass an empty map. For example: map()
<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.getRecordById(<module_name>, <record_Id>, <query_value>, <connection_link_name>);

The function returns a map and stores it in <variable>. It includes details of a fetched record, and is equivalent to the Get records API response. To check the response, refer to the Get records API response object.

The function zoho.bigin.getRelatedRecords() is used to fetch the related lists data associated with a record from the specified module of Bigin. This function takes in a set of parameters and other necessary information to fetch the records of a related list. Moreover, this function returns the response as a map that contains the details of the fetched related list records.

The following section outlines the function's parameters:

<related_list_name> stringrequired

This parameter indicates the API name of a related list from which records are fetched.

You can get the API name of related lists from Get related list metadata.

<module_name> stringrequired

This parameter indicates the API name of the module from which the related list records are fetched. For example, if you want to fetch related list records from the Companies module, you would pass Accounts as the value of <module_name>.

You can get the API name of modules from Get all modules.

<record_Id> numberrequired

This parameter indicates the ID of a record within a specified module from which the related list records are fetched.

You can get the ID of a record from Get all records.

<query_value> mapoptional

This parameter is a map that includes request parameters used in the Get related records details. These parameters are especially included to filter and fetch records from related lists based on the specific conditions.

Notes:

  • The keys and values for this parameter should be provided as mentioned in the Get related list details.
  • To prevent this query from executing, you must pass an empty map. For example: map()
<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.getRelatedRecords(<related_list_name>, <parent_module_name>, <record_id>, <query_value>, <connection_link_name>);

The function returns a map and stores it in <variable>. It includes details of the fetched related list records, and is equivalent to the Get related list records API and Get the Team Pipeline records related to a specific contact API response. See the Get related list records API and Get the Team Pipeline records related to a specific contact API response object.

Get Bigin variables

The function zoho.bigin.getOrgVariables() is used to fetch the values of the Bigin variables that are created under custom properties of the Bigin Developer Console. This function takes in a set of parameters and other necessary information to retrieve the required values. Moreover, this function returns the value of specified Bigin variable.

Note:

The connection details that are passed along with this function need to be configured with the following scope:

  • ZohoBigin.settings.variables.READ

The following section outlines the function's parameters:

<variable_api_name> stringrequired

This parameter indicates the api name of Bigin variable. To get values of multiple Bigin variables, you can pass more than one variable separated by comma.

<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.getOrgVariables(<variable_api_names>, <connection_link_name>);

This function returns a value as a response and stores it in <variable>. The response includes the value of the specified Bigin variable. Alternatively, If you pass more than one variable, the function returns a map as a response and stores it in <variable>. In the map, the keys represent the variable api name and values represents the values of Bigin variables.

Set Bigin variables

The function zoho.bigin.InvokeConnector() is used to set the value for the Bigin variables that are created under custom properties of the Bigin Developer Console. This function takes in a set of parameters and other necessary information to set the value for the appropriate variable. Moreover, this function returns a response as a map with success or failure details.

Note:

The connection details that are passed along with this function need to be configured with the following scope:

  • ZohoBigin.settings.variables.CREATE

The following section outlines the function's parameters:

<nameSpace> stringrequired

This parameter invokes function to set the Bigin variables. For set organization variable, you would pass crm.set as the value of <nameSpace>.

<queryparam_details> mapoptional

This parameter is used when you want to provide additional query parameters for executing the function. To prevent this query parameter from executing, you must pass an empty map. For example: map()

<header_details> mapoptional

This parameter is a map that includes the header details specified for Bigin. The keys represent the header names and values represent the header values. This parameter is used when you want to provide additional header information for executing the function.

<payLoad_details> maprequired

This parameter is a map that includes the necessary information to set a value for Bigin variable. Pass the Payload details in the following format:

variableMap = map();
variableMap.put("apiname", <variable_api_name>);
variableMap.put("value", <value>);
payLoad = map();
payLoad.put("VARIABLES", variableMap);

From the above syntax,
<variable_api_name> represents the api name of Bigin variable.
<value> represents the actual value that is going to be assigned to Bigin variable.

<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.InvokeConnector(<nameSpace>, <queryparam_details>, <header_details>, <payLoad_details>, <connection_link_name>);

This function returns the response as a map and stores it in <variable>. The response contains the success and failure details.

Create bulk records

The function zoho.bigin.bulkCreate() is used to create multiple records at once within the specified module of Bigin. This function takes in a set of parameters and other necessary information to create multiple records. The syntax used for this bulk record creation function is similar to zoho.bigin.createRecord(), but with few changes in the input format of the <request_details> parameter that contains details for multiple records. This function returns a response as a map with the newly created multiple record Ids and any other relevant information. Moreover, this function is based on the Insert Records API.

Note:

This function creates up to 100 records at once.

For example, if you want to create multiple records at once in the Contacts module, you would pass multiple contact details as a map through the zoho.bigin.bulkCreate() function.

The following section outlines the function's parameters:

<module_name> stringrequired

This parameter indicates the API name of the module in which multiple records will be created. For example, if you want to create multiple records in the Companies module, you would pass Accounts as the value of <module_name>.

You can get the API name of modules from Get all modules.

<record_details> listrequired

This parameter is a list that provides the necessary information to create multiple records. The keys indicate the field API names, and the values indicate the values to be set for corresponding fields. For example, if you want to create multiple contact records, you would pass the value of <record_details> in the following format:

payload = List();

// Record Values to be Created

valueMap1 = Map();
valueMap1.put("First_Name", "Bigin");
valueMap1.put("Last_Name", "By Zoho CRM");
valueMap1.put("Email", "support@bigin.com");
payload.add(valueMap1);

valueMap2 = Map();
valueMap2.put("First_Name", "Bigin");
valueMap2.put("Last_Name", "CRM");
valueMap2.put("Email", "support1@bigin.com");
payload.add(valueMap2);

You can get the field API names from Get all records.

For information about mandatory fields in each module, see Modules and Fields.

<optional_details> mapoptional

This parameter is a map that includes any other optional details such as the execution of scripts or triggering of workflows when multiple records are created. For example, if you want to trigger a workflow after multiple records are added to a module, you should pass the value of <optional_details> in the following format:

<optional_details> = {"trigger":{"workflow"}}

When this parameter is not passed, approvals and stage transition rules execute by default. To prevent all operations from executing, you can pass an empty map with the trigger key set to an empty value.

<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.bulkCreate(<module_name>, <record_details>, <optional_details>, <connection_link_name>);

Update bulk records

The function zoho.bigin.bulkUpdate() is used to update multiple records at once within the specified module of Bigin. This function takes in a set of parameters and other necessary information to update multiple records. The syntax used for this bulk record upgradation function is similar to zoho.bigin.updateRecord(), but with few changes in the input format of the <request_details> parameter that contains details for multiple records. The function returns a response as a map with the newly created multiple record Ids and any other relevant information. Moreover, this function is based on the Update Records API.

Note:

This function updates up to 100 records at once.

For example, if you want to update multiple records at once in the Contacts module, you would pass multiple contact details as a map through the zoho.bigin.bulkUpdate() function.

The following section outlines the function's parameters:

<module_name> stringrequired

This parameter indicates the API name of the module in which multiple records will be updated. For example, if you want to update multiple records in the Companies module, you would pass Accounts as the value of <module_name>.

You can get the API name of modules from Get all modules.

<record_details> listrequired

This parameter is a list that provides the necessary information to create multiple records. The keys indicate the field API names, and the values indicate the values to be set for corresponding fields. For example, if you want to create multiple contact records, you would pass the value of <record_details> in the following format:

payload = List();

// Record Values to be Updated

valueMap1 = Map();
valueMap1.put("id", "554023000000527002");
valueMap1.put("First_Name", "Bigin");
payload.add(valueMap1);

valueMap2 = Map();
valueMap2.put("id", "554023000000527004");
valueMap2.put("Last_Name", "By Zoho CRM");
payload.add(valueMap2);

In the above sample, you must include the ID of the record in each map value, along with the fields that needs to be updated.

You can get the field API names and record IDs from Get all records.

For information about mandatory fields in each module, see Modules and Fields.

<optional_details> mapoptional

This parameter is a map that includes any other optional details such as the execution of scripts or triggering of workflows when multiple records are updated. For example, if you want to trigger a workflow after multiple records are updated in a module, you should pass the value of <optional_details> in the following format:

<optional_details> = {"trigger":{"workflow"}}

When this parameter is not passed, approvals and stage transition rules execute by default. To prevent all operations from executing, you can pass an empty map with the trigger key set to an empty value.

<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.bulkUpdate(<module_name>, <record_details>, <optional_details>, <connection_link_name>);

Attach a file

The function zoho.bigin.attachFile() is used to attach a file to a record within the specified module of Bigin. This function takes in a set of parameters and other necessary information to attach a file. Moreover, this function returns a response as a map with the details related to the attached file.

The following section outlines the function's parameters:

<module_name> stringrequired

This parameter indicates the API name of the module in which the file is attached to a record. For example, if you want to attach a file to a record in the Companies module, you would pass Accounts as the value of <module_name>.

You can get the API name of modules from Get all modules.

<record_Id> numberrequired

This parameter indicates the ID of a record within a specified module to which the file will be attached.

You can get the ID of a record from Get all records.

<file_object> filerequired

This parameter indicates the file variable that contains the attachment file.

The <file_object> can be defined as shown in File data type before passing through the function.

<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.attachFile(<module_name>, <record_id>, <file_object>, <connection_link_name>);

The function returns a map and stores it in <variable>. It includes creation and modification details of the attached file, and is equivalent to the Upload an attachment API response. To check the response, refer to the Upload an attachment API response object.

Get ZApikey

The function zoho.bigin.InvokeConnector() is used to fetch ZApikey, which is an unique authentication key generated for each user who interacts with the topping. This function is used in Custom Functions or Install Actions of the Bigin Developer Console to obtain the value of ZApikey. This function takes in a set of parameters and other necessary information to retrieve ZApikey. Moreover, this function returns a response as a map with success or failure details.

Note:

The connection details that are passed along with this function need to be configured with the following scopes:

  • ZohoBigin.settings.widgets.READ and
  • ZohoBigin.settings.widgets.CREATE

The following section outlines the function's parameters:

<nameSpace> stringrequired

This parameter invokes function to set the Bigin variables. For getting ZApikey, you would pass crm.zapikey as the value of <nameSpace>.

<queryparam_details> mapoptional

This parameter is used when you want to provide additional query parameters for executing the function. To prevent this query parameter from executing, you must pass an empty map. For example: map()

<header_details> mapoptional

This parameter is a map that includes the header details specified for Bigin. The keys represent the header names and values represent the header values. This parameter is used when you want to provide additional header information for executing the function.

<payLoad_details> maprequired

This parameter is a map that includes the necessary information to get the ZApikey. Pass the Payload details in the following format:

variableMap = map();
variableMap.put("nameSpace", <portal>.<topping_namespace>);
payLoad = map();
payLoad.put("VARIABLES", variableMap);

From the above syntax,
<portal> represents the portal name of your topping. It can be found in the URL path of your Bigin Developer Console.

<topping_namespace> represents the namespace of your topping. It can be found in the Edit Topping page of your Bigin Developer Console.

<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.InvokeConnector(<nameSpace>, <queryparam_details>, <header_details>, <payLoad_details>, <connection_link_name>);

This function returns the response as a map and stores it in <variable>. The response contains the success and failure details.

Raise signals

The function zoho.bigin.raiseSignals() is used to create signals for Bigin. It accepts a set of parameters and other necessary information to trigger the signal. Additionally, this function returns a response as a map that includes the details of the raised signal.

Note:

The connection details that are passed along with this function need to be configured with the following scope:

  • ZohoBigin.signals.ALL

The following section outlines the function's parameters:

<signal_namespace> stringrequired

This parameter is a unique name given to a custom signal, which is generated in the <toppingNamespace>_<signalName> format.

<payload_map> maprequired

This parameter is a map that includes the necessary information to raise signals. Pass the payload in the following format:

payload = Map();
payload.put("subject", "Bigin Signals");
payload.put("message", "Detailed description of Signals in Bigin");

actionsList = List();

//A sample action property

actionProp1 = Map();
actionProp1.put("type", "link");
actionProp1.put("open_in", "tab");
actionProp1.put("display_name", "Bigin Website Link");
actionProp1.put("url", "www.bigin.com");
actionsList.add(actionProp1);

//If required, multiple action properties can be specified here

payload.put("actions", actionsList);

Notes:

  • Signals can only be raised for the Contacts module. In order to raise signals, you must specify either the email or id of a contact record.
    • payload.put("email",<email_of_a_contact>); or
    • payload.put("id", <contact_id>);
  • The values of action properties, referred to as "actionProp1" of the List data type, should be as mentioned below:
    • "type" - specify link
    • "open_in" - specify tab and popup
<header_map> mapoptional

This parameter is a map that includes the header details specified for Bigin. The keys represent the header names, and the values represent the header values. This parameter is used when you want to provide additional header information for executing the function.

To prevent this query parameter from executing, you must pass an empty map.

<connection_link_name> stringrequired

This parameter indicates the Connection Link Name of a connection. For more information about Connection Link Name, see Connections.

Syntax

Copied<variable> = zoho.bigin.raiseSignals(<signal_namespace>, <payload_map>, <header_map>, <connection_link_name>);

This function returns the response as a map and stores it in <variable>. The response contains the success and failure details.