Setting up and using connections in Bigin toppings

Setting up and using connections in Bigin toppings

When building a topping to extend Bigin's functionality and connect it with third-party applications, creating and handling connections is an important step. Connections provide a secure way for your topping to authenticate and communicate with other applications' APIs without exposing sensitive credentials to end users. This abstraction is both secure and makes the integration easier because it eliminates the need for developers to implement complex authorization flows manually or handle authorization tokens directly.

Bigin's Developer Console offers a feature called a connection, which acts as a bridge between your topping and the third-party application you wish to integrate with. Once a connection is configured, you can reference it in your topping's functionalities using its unique link name. This enables the topping to execute REST operations such as fetching, updating, or syncing data with the connected application securely.

Now that we've achieved a basic understanding of what a connection is and how it helps toppings interact with other applications, the next step is to understand the types of connections available in Bigin's Developer Console.

Establishing connections with services

The connections feature in Bigin's Developer Console offers two types of services to help developers configure integrations according to their requirements: default services and custom services. Default services are preconfigured services available in Bigin's Developer Console that simplify integrations with some Zoho and third-party applications. If the application you want to integrate with isn't listed in the default services, you can create a custom service and configure it according to the API specifications of the third-party application.

Default services

The connections feature offers certain default services as preconfigured options that can be easily integrated with Bigin. These services come with predefined settings such as authentication type, token endpoints, scopes, and headers, which reduces the need for manual configuration. Currently, there are around 50 default services available in the Developer Console, covering a wide range of applications and platforms. This enables developers to connect to services with minimal effort.


If the application you want to integrate with your topping isn't listed in the default services, you can create a new custom service.

Custom services

Custom services enable developers to configure all aspects of a connection manually, including the authentication type, endpoints, headers, and scopes, which enables integration with third-party applications.

When setting up a custom service, developers can specify the exact authentication flow required by the external application, whether it's basic authentication, OAuth, an API key, or another method.
Notes
Note:

Refer to the official API documentation of third-party applications when configuring these settings, as this will provide the necessary details for authentication and data access.
To create a custom service, navigate to the Connections section and choose Custom Services in the Developer Console. Based on the authentication type supported, configure the custom service for the required product.


For more details on creating and configuring custom services, please refer to this guide.
Notes
Note:

Always handle sensitive information such as client IDs, client secrets, and API keys securely, and never share them publicly. After configuring and authorizing a custom service, reference it in Deluge scripts and workflow functions by using its unique connection link name, just as you do with default services.
Next, let's look at how to implement the default service connection with an example.

Create a default service connection

Let's say you're developing a Bigin topping to synchronize contact information between Bigin and Zoho Books. This integration enables contacts created or updated in Bigin to be automatically reflected in Zoho Books. The topping uses Zoho Books APIs to create, update, and retrieve customer data using a default service connection.

To create a default service connection for the topping, choose Connections from the left panel of the Developer Console and click Get Started.


Next, navigate to My Connections or Default Services. To fetch data from the Contacts module in Bigin, create a connection first. From Default Services, select Bigin and then click Create Connection to set it up.


The system will prompt you to enter the connection details. Provide a name for the connection (for example: Bigin Connection). A connection link name is generated automatically.

Next, select the scopes required for the topping's functionality. In this use case, select ZohoBigin.modules.ALL to access data from Bigin's Contacts module.

After selecting the scope, click Create and Connect to initiate the authorization process. The system redirects you to the authorization page. Click Connect, and you'll be taken to the service's login page. Choose the Bigin organization for which the topping was created, click submit, and the connection will be created.


After establishing the connection with Bigin, you must also create a connection for Zoho Books to enable record creation. To do this, create a default service connection for Zoho Books, similar to the one created for Bigin. Select the scope ZohoBooks.fullaccess.ALL to grant complete access to modules and operations in Zoho Books.

Once you've created the connections for both Bigin and Zoho Books, the system will generate connection link names for each. These link names must be used in the business logic.



Notes
Notes
Note:

During development, authorize the connection in the Sandbox environment to test integration workflows safely.
To understand the authorization process and how to implement them, please refer to this guide on authorizing connections.


After you authorize the connection, set up a workflow rule in the Bigin Developer Console that gets triggered whenever you create or update a contact in your Bigin account. Here, we need to specify the conditions that apply to the workflow and check that the email field isn't empty.

Notes
Note:

In our use case, we'll use the email address to check whether the newly created contact in Bigin already exists as a customer in Zoho Books.



When the workflow meets the specified conditions, an instant action - in this case, a function - which will execute a custom functionality that performs the following operations:
  1. Retrieves the contact details from Bigin by referencing the established connection link name biginandbooksconnection0__booksconnection.
  2. Searches Zoho Books for an existing contact that matches the email.
  3. If a matching contact exists, update the contact's phone and contact person details in Zoho Books.
  4. If the script doesn't find a matching contact, it creates a new contact in Zoho Books with the relevant information.
Below is the code that automates contact synchronization between Bigin and Zoho Books:
  1. //Retrieve contact details from Bigin using the established connection
  2. biginContact = zoho.bigin.getRecordById("Contacts",contact.get("Contacts.ID"),Map(),"biginandbooksconnectionnew__biginconnection");
  3. //Extract relevant contact data
  4. biginData = biginContact.get("data");
  5. contactDetails = biginData.get(0);
  6. email = contactDetails.get("Email");
  7. phone = contactDetails.get("Phone");
  8. mobile = contactDetails.get("Mobile");
  9. fullName = contactDetails.get("Full_Name");
  10. //Search Zoho Books for existing contacts by email
  11. searchParams = Map();
  12. searchParams.put("search_text", email);
  13. booksContactsResponse = invokeurl
  14. [
  15. url :"https://books.zoho.com/api/v3/contacts"
  16. type :GET
  17. parameters:searchParams
  18. connection:"biginandbooksconnectionnew__booksconnection"
  19. ];
  20. info "Searched by name in Books: " + booksContactsResponse;
  21. booksData = booksContactsResponse.get("contacts");
  22. if(booksData != null && booksData.size() > 0)
  23. {
  24. // Extract the existingContactId
  25. existingContactId = booksData.get(0).get("contact_id");
  26. // Update existing contact
  27. updateParams = Map();
  28. updateParams.put("contact_name",fullName);
  29. updateParams.put("phone",phone);
  30. updateParams.put("mobile",mobile);
  31. updateParams.put("email",email);
  32. // Define contact person details
  33. contactPerson = Map();
  34. contactPerson.put("last_name",fullName);
  35. contactPerson.put("mobile",mobile);
  36. contactPerson.put("phone",phone);
  37. contactPerson.put("email",email);
  38. contactPerson.put("is_primary_contact",true);
  39. contactPersonsList = List();
  40. contactPersonsList.add(contactPerson);
  41. updateParams.put("contact_persons",contactPersonsList);
  42. //Prepare and execute update request
  43. parameters_data = Map();
  44. parameters_data.put("JSONString",updateParams.toString());
  45. info "parameters_data value:" + parameters_data;
  46. updateResponse = invokeurl
  47. [
  48. url :"https://books.zoho.com/api/v3/contacts/" + existingContactId + "?organization_id=XXXXXXX"
  49. type :PUT
  50. parameters:parameters_data
  51. connection:"biginandbooksconnectionnew__booksconnection"
  52. ];
  53. info "Updated Contact: " + updateResponse;
  54. }
  55. else
  56. {
  57. // Create new contact
  58. contactDetails = Map();
  59. contactDetails.put("contact_name",fullName);
  60. contactDetails.put("email",email);
  61. contactDetails.put("phone",phone);
  62. contactDetails.put("mobile",mobile);
  63. // Define contact person details
  64. contactPerson = Map();
  65. contactPerson.put("last_name",fullName);
  66. contactPerson.put("mobile",mobile);
  67. contactPerson.put("phone",phone);
  68. contactPerson.put("email",email);
  69. contactPerson.put("is_primary_contact",true);
  70. // Add to contact persons list
  71. contactPersonsList = List();
  72. contactPersonsList.add(contactPerson);
  73. contactDetails.put("contact_persons",contactPersonsList);
  74. // Prepare and execute the create request
  75. parameters_data = Map();
  76. parameters_data.put("JSONString",contactDetails.toString());
  77. createResponse = invokeurl
  78. [
  79. url :"https://books.zoho.com/api/v3/contacts?organization_id=XXXXXXX"
  80. type :POST
  81. parameters:parameters_data
  82. connection:"biginandbooksconnectionnew__booksconnection"
  83. ];
  84. info "Created Contact: " + createResponse;
  85. }
For details about the API endpoints and request formats used in this code, refer to the Bigin Deluge reference library and Zoho Books contacts API documentation.
After you configure the workflow and associate the function with the instant action, test the topping in the sandbox environment.
  1. To do this, click Test Your Topping in the upper-right corner of the Developer Console. This action will redirect you to the Bigin sandbox account, where you can create a new contact to test whether the functionalities work properly.
  2. After creating a new contact in Bigin, navigate to the Customers module in the Sales section of Zoho Books. When you set up the integration correctly, you'll see the newly created contact here, which confirms that Bigin and Zoho Books are synchronizing as expected. This process provides a safe and effective way to validate the workflow before deploying the topping to a production environment.


In this post, we've explained that default service connections in Bigin simplify authentication and connection with third-party applications by using predefined settings such as authentication type, token endpoints, and scopes. These connections are convenient because the Developer Console pre-configures the authentication flow and endpoints of the application you're integrating with.

To sum up: Bigin's connections feature provides a flexible foundation for integrating with a wide range of external services, and using these connections, developers can extend Bigin's integration capabilities.

Stay tuned for more about developing toppings and exploring other related features available in the Bigin Developer Console.

<< Previous                                                                                                                                                      Next>>                                                                                                                                                                                                                                              

    Nederlandse Hulpbronnen


      • Recent Topics

      • Zoho Learn Zapier Integration

        Hello all, Is there any plan to integrate Zoho Learn with Zapier? It seems almost all Zoho products are in Zapier, with the exception of Learn and Marketing Automation.

      • Notice: SalesIQ integration paused on Zoho Sites

        I have this notice on my Zoho Sites in the SalesIQ integration setup. Can someone assist? "This integration has been temporarily paused for users. Reconnecting SalesIQ after disconnection will not be possible until we provide further updates." thank

      • Differences between Zoho Books and Zoho Billing

        Without a long drawn out process to compare these. If you were looking at these Books and Billing, what made you opt for one and not the other. Thanks

      • New Feature : Copying tickets with all the contents such as conversations/history/attachments etc

        Sometimes our customers and distributors do create tickets (or send emails) which contain more than one incident in them and then also some of the further conversations which are either created by incorrect new tickets or replies to old tickets are being created as combined tickets. In such cases we require to "COPY" the contents of the tickets into separate tickets and merge them into their corresponding original tickets. The "CLONE" feature doesn't copy the contents (especially the conversations

      • Como se agregan los empleados

        Necesito saber si para agregar empleados los mismos necesitan tener licencias

      • Deluge Error Code 1002 - "Resource does not exist."

        I am using the following script in a Custom Button on a Sales Return. Basically, the function takes the information in the sales return (plus the arguments that are entered by the user when the button is pushed) and creates a return shipping label via

      • Adding multiple Attendee email addresses when adding a Zoho Calendar event in Zoho Flow

        I am trying to integrate Notion and Zoho Calendar via Zoho Flow. However, the Attendee email address supported by Zoho Calendar - Create event only supports one email address, so I am having difficulty implementing automation to automatically register

      • Graceful Handling of Exceeded Option Limits

        Hi Zoho SalesIQ team. I would like to submit a feature request to deal with a bug in salesIQ Current Behavior (Bug): When a dynamic list passed to the Single Select Option Card contains more than 20 options, the Zobot stops responding (freezes/hangs)

      • System default SLA descriptions can't be modified

        The system default SLAs have identical descriptions for all SLA levels, but their settings differ. However, I am facing an issue where I cannot modify these descriptions and save the changes. The content of the description box can be edited but the changes

      • Adding non-Indian billing address for my Zoho subscription

        Hey Need help with adding a non-Indian billing address for my Zoho subscription, trying to edit the address to my Singapore registered company. Won't let me change the country. Would appreciate the help. Regards, Rishabh

      • How to create one ZohoCRM organisation out of a multi-organization?

        Hi, we have a multi-org including two different Zoho CRM organizations for two companies using respectively EUR and USD as default currency. I was wondering if there is any easy way to merge the two organizations into just one, so that users may access

      • Gray screen while signing documents

        We are all getting a "gray" screen when trying to sign documents in Zoho sign. Anyone else having issues?

      • Projects custom colors replaced by default orange

        Since yesterday, projects uploaded to Zoho, to which I had assigned a custom color, have lost the customization and reverted to the default color (orange). Has anyone else had the same problem? If so, how did you resolve it?

      • Interview booked through Invite but no Notifications

        We have a workflow that was developed through a developer/partner that was tested and worked. Today, we pushed a candidate through the process and invited them to an in-office interview. They were sent the booking link (as usual and as tested before successfully)

      • WebDAV support

        I need WebDAV support so that I can upload/download (and modify) documents from my local file system. Is anything planned in his direction?

      • Automatiser la gestion des SLA dans Zoho Desk avec Zoho Contracts

        Les équipes du service client s’efforcent d’assurer un support rapide, régulier et fiable pour garantir la satisfaction de chaque client. Les accords de niveau de service (SLA) permettent de clarifier les engagements en définissant les termes et conditions

      • iOS App doesn't refresh for Document Creation

        Hello Zoho team, I have created a workflow to be used on a mobile iOS device which starts in Zoho Creater and ends with a murge and store function that then opens the newly created document within the Zoho Writer app. This process is working great however

      • Uploading a signed template from Sign to Creator

        Good day, Please help me on how to load a signed document back into Creator after the process has been completed in Sign. Below is the code that I am trying, pdfFile = response.toFile("SignedDocument_4901354000000372029.pdf"); info pdfFile; // Attach

      • Zoho DataPrep and File Pattern configuration

        I'm using Zoho data prep to ingest data from One Drive into Zoho Analytics... The pipeline is super simple but I can't any way to get all the files that I need. Basically I need to bring all the files with a certain pattern and for that I'm using a regex

      • Assistance needed: Activation of a domain

        Hello Zoho Support, I purchased the .com domain "primesolva.com" via Zoho 6 days ago. The domain is still pending, and I cannot access the DNS panel to add the TXT verification for domain ownership. Please confirm the registration status and help me activate

      • Operation not permitted

        I am trying to add an email address to the list of user but I am getting error Operation not permitted

      • Request to Permanently Delete Email User (info@mehbobgulf.com ) from Old Organization

        Please permanently delete the user email info@mehbobgulf.com It is still associated with my old Zoho organization. I cannot delete it because it shows ‘You cannot delete email. Zoho host’. I need to use this email in a new Zoho account.”

      • Client host [89.36.170.5] blocked using Spamhaus

        Hello please make make actions for delist ..... "Client host [89.36.170.5] blocked using Spamhaus"

      • Suggestion: Option to Re-run a migration

        As I'm going through a migration process, I like the IMAP migration tool, but it would be better if there were an option to re-run the same migration as configured. There's not even an option to copy/edit one that's already there. Just run if it hasn't

      • Issue with "Add Your Mobile Number"

        Hello, I am trying to sign up for email service for a domain name, and I cannot finish the authentication. When I enter my mobile number, I receive the message "We’re unable to send OTP to this mobile number. Please contact support-as@zohocorp.com". I

      • zoho mail non vérifié

        Bonjour, Il y'a un jour que j'ai acheté un domaine et toute les tentatives pour l'associé a mon compte shopify son vaine. j'ai essayé TXT sans suite après, j'ai essayer avec CNAME sans suite. j'aurais besoin de votre assistance pour associé mon mail.

      • Unable to send message;Reason:553 Relaying disallowed. Invalid Domain

        i have facing the issue "Unable to send message;Reason:553 Relaying disallowed. Invalid Domain" if i verify domain evertthing i did but still face the same error.

      • ZohoMail is so close to being Perfect BUT

        Why don’t you have HILIGHTING???!! I've been trying to find a substitute for Edison Mail but I want & need hilighting (preferably in more than just yellow)! Is this even on your To Do list? I’m so disappointed. 🙄

      • Override Auto Number field?

        We are preparing to migrate from Salesforce. In Salesforce, we auto-generate a unique number on our Opportunities (Potentials). If the Opportunity results in a contract, we use that unique number as the Contract number. There are some situations where

      • Using a third party service provider want to move directly with Zoho

        Hi good day I’m currently using Zoho but I’m using a third party service provider I want to move directly with you guys I’m using Zoho email and invoices and my domain please let me know if it’s possible to move away from the third party provider my email

      • Request for Assistance Regarding Email Sending Issue (554 5.1.8 - Email Outgoing Blocked)

        Dear Zoho Support Team, I hope this message finds you well. I am writing to request assistance with an issue we are currently facing regarding our Zoho Mail account. Our email account, admin@tuyensinhcanuoc.com, is encountering the following error when

      • Zoho Mail API returns empty inbox (0 messages) but webmail shows 37 unread emails

        Hello, I'm experiencing a discrepancy between Zoho Webmail and the Mail API (EU region). **Setup:** - Account: EU datacenter (mail.zoho.eu) - API: Self Client OAuth2 via api-console.zoho.eu - Scopes: ZohoMail.messages.READ, ZohoMail.messages.UPDATE, ZohoMail.folders.READ,

      • ShipStation and Zoho Inventory

        Hello, I am looking to sync zoho inventory with shipstation ZOHO INVENTORY           SHIP STATION Sales Order  ==>  create ORDERS INVOICE  <==    Shipments What exactly does BETA mean on the Shipstation connector?  This is required for me to sign-on in the next month. Thanks in advance for your efforts

      • E

        We are trying to add our Zoho Form embed in our Elementor Page Builder. After adding Zoho Forms widget in elementor page builder it’s displaying in backend page builder but it’s giving 403 error while trying to save, as it’s not reflecting in front end.

      • Connecting Zoho Inventory to ShipStation

        we are looking for someone to help connect via API shipStation with Zoho inventory. Any ideas? Thanks. Uri

      • custom module import.

        Is there a way to import data into a custom module? Thanks Rudy

      • HEIC File Type Viewer

        Hi, It would be nice to be able to click on the images in the All Entries/Reports Tables which are HEIC the same as JPG, PNG, etc. so they open in a viewer from Zoho or the Attachment Service, today HEIC requires you to download each image and open it

      • How to dynamically pass IDs from one API response to a second API call in Zoho DataPrep?

        Hi Team, I am setting up a global consolidated reporting pipeline in Zoho Analytics (India) using Zoho DataPrep as the ETL engine. I am pulling data from multiple Zoho Books Data Centers (US, Singapore, India) thats why i used the URL Source (OAuth 2.0)

      • Building Toppings #4 - Setting up and using connections in Bigin toppings

        When building a topping to extend Bigin's functionality and connect it with third-party applications, creating and handling connections is an important step. Connections provide a secure way for your topping to authenticate and communicate with other

      • Need code format to specify default values

        Can someone please direct me to the code syntax or the proper translation per the instructions circled below. These instructions don't seem correct.

      • Next Page