Connections

IN THIS PAGE

Connections overview
Default services
Custom services
Authorization
Use Connections in Functions

1. Connections overview 🔗

Connection is used to establish a simple authentication mechanism that integrates your Bigin account with other Zoho or third-party services. In simpler terms, a connection provides a secure way to authenticate and authorize any Zoho or third-party service in order to access their resources. It abstracts the implementation of a complex authorization flow you need to configure and simplifies the integration.

After you configure a connection and connect to a Zoho or third-party service, you will simply need to include the configured connection in Bigin's Deluge Functions or Integration tasks in Deluge scripts. This will enable you to perform REST operations on the connected Zoho or third-party services.

For example, If you're building a topping to integrate Google Drive with Bigin, you need to establish a Google Drive connection in Bigin. This can be done using Google Authorization and enables Bigin to access the Google Drive account. Once the connection is established, you can use the connection link name in the Deluge integration task to make API calls to your Google account. This allows a seamless integration between Bigin and your Google Drive account.

The Bigin Developer Console has two types of services that act as connectors for establishing connections: Default services, which are pre-configured services provided by the Bigin Developer Console, and Custom services, which are custom configured to meet user-specific requirements.

Default and Custom services are both essential in establishing connections and enabling interactions between Bigin and Zoho or third-party services.

2. Default services 🔗

Default services allow you to quickly create and authenticate a connection. Below is the list of Default services available in the Bigin Developer Console:

Here's the list of popular Default Services that are widely used for seamless integrations:

Shopify
Wordpress
Pipedrive
Dropbox
MailChimp
Zendesk
DocuSign

Create a default service connection 🔗

Let's create a connection using default services. You can create default service connections either from the My Connections or Default Services section.

In the Default Services section, search the default service for which you want to create a connection. This can be done by typing the name of the service in the search bar. For example, if you want to create a connection with the Bigin service, you will need to search for Bigin in the search bar.

Next, select the service and then click the Create Connection button. You will be directed to a page where you can configure the connection.

In the Connection Details section, provide the details:

Connection Name: Type the display name of the default service connection.
Connection Link Name: The connection link name is system generated in the <topping_namespace>__<connection_name> format. You can simply modify the <connection_name> portion of the connection link name here. If you wish to make any changes, follow these conditions:
- It must begin with a lower case letter.
- It can only contain lower case letters, numbers, and underscore.
✍ Note: The length of the connection name and link name must not exceed 45 characters.
Choose Scopes: Select the scopes as needed from the list of scopes. If the list of scopes is extensive, you can type the name of the scope in the search bar. The availability of scopes depends on the service you select. Refer to the official API documentation of the default service you choose to learn more about the scopes.

Click Create and Connect. You will be directed to a page where you can authorize the connection.

Here's default connection usage in functions:

Sample Deluge code snippet

CopiedcontactId = contact.get("Contacts.ID");
contactRecord = zoho.bigin.getRecordById("Contacts", "contactId", Map(), "zylker__biginconnect");
info "[INFO] Contact Record response :: " + contactRecord;
// Your custom logic goes here...
return "SUCCESS";

To know more details about how to use connections in functions, see Use Connections in Functions.

3. Custom services 🔗

When you want to use a third-party service that is not pre-configured and listed in the Default services section, you'll need to create a new custom service.

💡 Tip: Refer to the official API documentation of the third-party app that you want to create as a Custom Service for determining the appropriate authentication type.

In order to create a custom service, you should first navigate to the Connections > Custom Services section in the Bigin Developer Console.

Next, click the Create Service button and provide the service details as shown below:

Service Name: Type the display name of the custom service.
Service Link Name: Type the link name of the custom service that uniquely identifies the service. By default, the link name will be generated based on the display name of the custom service. If you wish to make any changes, follow these conditions:
- It must begin with a lower case letter.
- It can only contain lower case letters, numbers, and underscore.
✍ Note: The length of the connection name and link name must not exceed 45 characters.

Authentication Type: Select an authentication type supported by the custom service from the following:

💡 Tip: Do not share sensitive authentication data used in connections, such as Client ID, Client Secret, Parameter Key, Consumer ID, Consumer Secret, and similar credentials.

API Key

The API Key type allows for a client-provided token that can be sent in a query string, form data, or header. The token is unique to each user and will remain the same as long as they continue to access the service.

Fields	Description
Parameter Type	This specifies how the parameters will be sent along with the URLs indicated in the invoke URL integration tasks scripts. The supported parameter types are: Query String, Form Data, and Header.
Parameter Key	This specifies the key name as mentioned in the official API documentation of the custom service for which the parameter should be sent.
Parameter Display Name	This specifies the display name of the parameter.

✍ Notes:

You can create multiple parameters.
Parameters can be of any type that is required for authentication. For example: api-key, user-key, authtoken, apitoken and so on.

Basic Authentication

The Basic Authentication type establishes a connection by sending the user's username and password in the header. This authentication type uses the Base64 encoding standard to encode the username and password. Therefore, the provided username and password will be automatically encrypted with the Base64 algorithm and passed in the header as basic <encrypted_username>:<encrypted_password>.

There are no fields that need to be configured.

OAuth1

The OAuth1 type uses request and access tokens to access data from the resource servers. The access token will not be expired until the user revokes it.

Fields	Description
Consumer Key	This specifies a key issued by the custom service to a consumer.
Consumer Secret	This specifies a private key issued by the custom service along with the consumer key.
Request Token URL	This specifies the custom service's URL request to obtain a request token. The Request Token URL can be found in the official API documentation of the custom service.
Authorize URL	This specifies the custom service's authorization URL that allows consumers to get approval from the users of the custom service. The Authorize URL can be found in the official API documentation of the custom service.
Access Token URL	This specifies the custom service's URL request to obtain an access token. The Access Token URL can be found in the official API documentation of the custom service.

💡 Tip: Refer to the official API documentation of the custom service for the Request Token URL, Authorize URL, and Access Token URL details.

OAuth2

The OAuth2 type provides an access token that allows app limited access to specific resources. The access token used to access resources will have a limited validity.

Fields	Description
Parameter Type	This specifies how the parameters will be sent along with the URLs indicated in the invoke URL integration tasks scripts. The supported parameter types are: Query String and Header.
Grant Type	This specifies the type of method used by the custom service to perform authorization. The supported grant types are: Authorization Code and Client Credentials.
Client ID	This specifies a client identifier issued by the custom service to a client.
Client Secret	This specifies a secret key that generates along with the client ID and is used to authenticate the client with the custom service.
Access Token URL	This specifies the request URL used to obtain the access token.
Authorize URL	This specifies the custom service's authorization URL that allows users to provide resource access for the client and generates an authorization code, which is further used to obtain access tokens.
Refresh Token URL	This specifies the request URL used to obtain a refresh token when an access token expires.
Scope	This allows you to restrict the access of the custom service to a limited and specific scope.
Scope Display Name	This specifies the display name of the scope.
Scope Delimiter	By default, the Scope Delimiter is set to comma (,). In some cases, you can use other delimiters, such as space, semicolon, and others. 💡 Tip: Refer to the official API documentation of the third-party application to determine the supported scope delimiter.

✍ Note: It is recommended to use predefined Deluge server callback URLs for each Data Center (DC) to ensure proper authorization and maintain an active connection for seamless integration. Hence, the custom redirect URL cannot be used, and you must provide the redirect URLs for each DC listed below:

https://deluge.zoho.com/delugeauth/callback

https://dre.zoho.eu/delugeauth/callback

https://dre.zoho.com.au/delugeauth/callback

https://deluge.zoho.in/delugeauth/callback

https://dre.zoho.com.cn/delugeauth/callback

https://dre.zoho.jp/delugeauth/callback

https://dre.zoho.sa/delugeauth/callback

https://dre.zohocloud.ca/delugeauth/callback

Dynamic Parameters: Type the key name and display name of the dynamic parameter. This parameter enables users to provide important details when establishing connections with a service. The dynamic parameter is configured as a placeholder using the ${<dynamic_parameter_key>} format in the Deluge integration task, Authorize URL, Access Token URL, and Refresh Token URL. This placeholder is substituted with the value supplied by the user during the authorization process.
Here's is an example of how to use dynamic parameters in a FreshBooks Custom Service to fetch a specific Invoice ID:

Sample Deluge code snippet

Copied// @APIDocumentation: https://www.freshbooks.com/api/invoices
// @Description: Get Specific Invoice id from Third-Party service
invoiceId = "2201278";
getInvoiceFrmBooks = invokeurl
[
	url :"https://api.freshbooks.com/accounting/account/${account_id}/invoices/invoices/" + invoiceId
	type :GET
	connection:"zylker__freshbooksconnect"
];
info "[INFO] Fetch Invoice ID ::" + invoiceId + " response :: " + getInvoiceFrmBooks;

To know more details about how to use connections in functions, see Use Connections in Functions.

In the above code snippet, ${account_id} is a dynamic parameter, which allows users to provide its value during the authorization process of the connection.

Then, to save the custom service, click Create Service.

✍ Notes:

You can only edit or delete the custom services that you have configured.
If a custom service is edited or deleted, all the existing connections created using the service will be revoked.

Create a custom service connection 🔗

Let's create a connection using custom services. You can create custom service connections either from the My Connections or Custom Services section.

In the Custom Services section, select the custom service for which you want to create a connection.

Next, click the Create Connection button. You will be directed to a page where you can configure the connection.

In the Connection Details section, provide the details as shown below:

Connection Name: Type the display name of the custom service connection.
Connection Link Name: The connection link name is system generated in the <topping_namespace>__<connection_name> format. You can simply modify the <connection_name> portion of the connection link name here. If you wish to make any changes, follow these conditions:
- It must begin with a lower case letter.
- It can only contain lower case letters, numbers, and underscore.
✍ Note: The length of the connection name and link name must not exceed 45 characters.
Choose Scopes: Select the scopes as needed from the list of scopes.

Click Create and Connect. You will be directed to a page where you can authorize the connection.

✍ Note: When you specify a dynamic parameter in the custom service configuration, a prompt will be displayed to enter the parameter value during the authorization of the connection.

Here's custom connection usage in functions:

Sample Deluge code snippet

Copied// @APIDocumentation: https://www.freshbooks.com/api/expenses
// @Description: Get Specific Invoice id from Third-Party service
getEstimatesFrmBooks = invokeurl
[
	url :"https://api.freshbooks.com/accounting/account/${account_id}/expenses/expenses"
	type :GET
	connection:"zylker__freshbooksconnect"
];
info "[INFO] Fetch Estimates response :: " + getEstimatesFrmBooks;

To know more details about how to use connections in functions, see Use Connections in Functions.

4. Authorization 🔗

To establish a safe and secure connection, authorization is a crucial step in the process of connecting Bigin and other Zoho or third-party applications. Authorization enables users to grant access to their accounts. By authorizing the connection, users can ensure that the apps are communicating effectively and that the data is being shared securely.

Authorize during development - Sandbox Testing

During the development of topping, you can grant permission for Bigin's default connection to access the Sandbox environment. This helps ensure that the connection is properly established and data can be securely exchanged between the topping and Bigin account before deployment.

While authorizing the connection, select the namespace of the topping being created under the SANDBOX section in the Choose the services dialog.

Production Authorization

Once the topping is installed in a user's Bigin account, they need to authorize the connection. This step is crucial for enabling the topping to access and interact with the user's Bigin data or configured external services based on the defined permissions.

If you want to authorize your Production environment instead of Sandbox, we recommend you set up the same configuration in your topping's Sandbox account first and then get hands-on experience of the topping being developed for seamless experience.

5. Use Connections in Functions 🔗

Once your connection is created, it automatically generates an invokeUrl script that you can use in Deluge scripts to make API calls.

Here's how the auto-generated script looks like:

Copiedresponse = invokeUrl [
    url : <url>
    type : GET/POST/PUT/DELETE
    parameters : <paramMap/string>
    connection : "<Connection_Link_Name>"
];

💡 Tip 1: By default, when you use GET and POST methods in integration tasks, the Map data type variables specified in parameters are passed as query parameters to the API. Refer to the sample code below:

Sample Deluge code snippet

Copied// @APIDocumentation: https://www.freshbooks.com/api/invoice_profiles
// @Description: Get Invoice profiles from Third-Party service
getInvoiceProfilesQryParam = Map();
getInvoiceProfilesQryParam.put("search[clientid]", "234823");
getInvoiceProfilesQryParam.put("per_page", "100");
getInvoiceProfilesFrmBooks = invokeurl
[
    url: "https://api.freshbooks.com/accounting/account/${accountid}/invoice_profiles/invoice_profiles"
    type: GET
    parameters: getInvoiceProfilesQryParam //here it'll be passed as query parameter
    connection: "zylker__freshbooksconnect"
];
info "[INFO] Fetch Invoice profiles response :: " + getInvoiceProfilesFrmBooks;

💡 Tip 2: When you send a request body for the POST method using integration tasks, use the .toString() method in parameters to pass the request body to the API. Refer to the sample code below:

Sample Deluge code snippet

Copied// @APIDocumentation: https://www.freshbooks.com/api/invoice_profiles
// @Description: Create Invoice profile in Third-Party service
createInvoiceProfileReqBody = Map();
createInvoiceProfileReqBody.put("customerid", "23482");
createInvoiceProfileReqBody.put("create_date", "2018-08-25");
createInvoiceProfileReqBody.put("frequency", "m");
createInvoiceProfileReqBody.put("numberRecurring", 0);

createInvoiceProfileLine = Map();
createInvoiceProfileLine.put("name", "Test Item");
createInvoiceProfileLine.put("qty", "1");
createInvoiceProfileLine.put("unit_cost", { "amount": "27.00" });

createInvoiceProfileLineList = List();
createInvoiceProfileLineList.add(createInvoiceProfileLine);

createInvoiceProfileReqBody.put("lines", createInvoiceProfileLineList);

createInvoiceProfileBody = { "invoice_profiles": createInvoiceProfileReqBody };

createInvoiceProfileInBooks = invokeurl
[
    url: "https://api.freshbooks.com/accounting/account/${accountid}/invoice_profiles/invoice_profiles"
    type: POST
    parameters: createInvoiceProfileBody.toString() //here it'll be passed as request body
    connection: "zylker__freshbooksconnect"
];

info "[INFO] Invoice profile create response :: " + createInvoiceProfileInBooks;

One way to use connections in functions is by specifying the connection link name in Bigin's Deluge Functions. This allows seamless API calls without manually handling authentication. By simply including the connection link name in your function, you can fetch, update, or manage data in Bigin. Make sure the connection contains the necessary scope permissions for Bigin data access.

💡 Tip: Bigin's Deluge Functions dynamically construct URLs based on Data Centers (DCs), which eliminates the need to write complex code for different URLs.

For example, a function associated with a custom button uses Bigin's Deluge Function to fetch a record by its record ID. This function needs the connection link name (e.g., zylker＿biginconnect) to securely access Bigin data without requiring manual authentication.

Sample Deluge code snippet

CopiedcontactId = contact.get("Contacts.ID");
contactRecord = zoho.bigin.getRecordById("Contacts","contactId",Map(),"zylker__biginconnect");
info "[INFO] Contact Record response :: " + contactRecord;
// Your custom logic goes here...
return "SUCCESS";

On the other hand, you can also directly use connections in functions to make API calls to Bigin or external services. By using the auto-generates script when a connection is created, you can securely access data without handling authentication tokens manually. Make sure the connection contains the necessary permissions for Bigin or external data access.

For example, here's a function that retrieves Bigin contacts that were last modified before the end of yesterday. It uses a search API call with a set criteria and an existing connection.

Sample Deluge code snippet

Copiedyesterday_end = zoho.currentdate.addDay(-1).toString("yyyy-MM-dd") + "T23:59:59+05:30";
criteria = "Modified_Time:less_than:" + yesterday_end;
criteriaMap = Map();
criteriaMap.put("criteria",criteria);
criteriaMap.put("fields","Last_Name,Modified_Time");
criteriaMap.put("sort_by","Modified_Time");
criteriaMap.put("sort_order","desc");
records = invokeurl
[
	url :"https://www.zohoapis.com/bigin/v2/Contacts/search"
	type :GET
	parameters:criteriaMap
	connection:"zylker__biginconnect"
];
return records;

Additional References

Bigin's Deluge Functions

Zoho's Integration task in Deluge

Connections in Deluge