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

      • [Webinar] Automate generation of wills, trusts, POAs, and other estate planning documents with Zoho Writer

        Managing the lifecycle of the estate planning documents such as wills, trusts, and POAs, from client intake to final storage, can be complex and time-consuming. Join our live webinar to learn how Zoho Writer transforms this process by automating document

      • Create / Update Rule in TeamInbox when record is updated in ZohoCRM using flow?

        I'm currently evaluating options and trying to work out if the possible scenario is possible; If a record in ZohoCRM is updated, take 2 of the fields from that - lets call them 'OrderRef' and 'OrderTo'. Using flow, if a record is added or updated, add

      • Plans to allow more columns of monitoring, and monitoring not only your own channels?

        Are their any plans to allow more columns of monitoring, and monitoring not only your own channels? Here's why - I'm sure I'm not alone in that we sell other brands products, so not only am I interested in my own brand social channels, but also the social

      • Unwrapping the best practices for the Zoho Desk mobile app: Part 1

        In focus: Empowering the field and frontline customer support representatives Imagine having to carry your computer everywhere to respond to customers, handle escalations, and update your process. This series presents you with efficient tips to handle

      • dealing with post dated cheques

        Hi, can you help me please the best way to deal with this We sell an item of three months duration that is paid for with post dated cheques in monthly stages example - item is sold £3000 Cheque 1 is for £1000 due at time of sale (say Sept) cheque 2 is dated 25th of next month (Oct) cheque 3 is dated 25th of next month +1 (Nov) Now, with invoice number one it's simple - i send a standard invoice as usual But with the other two here's what i want zoho to do next month i want it to send an invoice on

      • Is there a way to sell in a practical method multiple subscriptions of the same product? i.e. domain names

        In evaluating Zoho Billing, a hurdle to adopting it is that Zoho Billing does not seem designed to support businesses that sell multiple subscriptions of the same product. In our case, we need to sell and manage several domain names per client. Am I right

      • Bug Report: "Name A-Z" sorting fails when Note titles start with an Emoji

        Hello, I recently migrated from Evernote (~2600 notes across 23 notebooks). I use emojis at the start of my note titles for visual organization. The Issue: When I set the view to Sort by: Name (A to Z), the sorting logic breaks for any note starting with

      • Copy & Paste not working

        I could create and save 10 new documents but when I go to copy and paste content (just text) into them, only 1 of 10 would save the content. It would appear to save the content but when I go back into the documents, they are empty.

      • Currency for Petty Cash

        Currencies for Petty Cash should be available

      • editing/applying online payments

        We have customers who pay part or all of an invoice and then cancel their service and want the payment as a credit to future work. It would be ideal if we could make it an excess payment and then void the invoice. I can't make it an excess payment because

      • Contacts per department

        Hello, Is it possible to limit Contacts to a Department? Thanks

      • This site can’t be reached mail.zoho.com took too long to respond

        In my office at any system, we couldnt able to login zoho email. it shows " This site can’t be reached mail.zoho.com took too long to respond". please fix it soon.

      • Can send email from zoho mail, but can't receive any.

        Hi, My domain is sattvameditationresort.com. I've updated MX records with those of Zoho. But i can't send any mails to this email id from gmail. I have checked the MX status with MXTOOLS, its showing the correct entry either. The error is as shown below:

      • My domain did not activate

        Hi, my domain (apsaindustrial.com.ar) did not activate, and the phone verification message never arrived. Please would you solve this problem? Thanks.

      • Host not found?

        Howdy! So i'm trying to add my custom domain for with the mail server. I have 100% control of my DNS and have tried every single option (TXT, CNAME, and even HTML) multiple times, ensuring i did it properly, to no luck. I get the same error message every

      • Auto End Chats After Customer Inactivity

        Hello Everyone, I may be missing something, but is there a way to auto-end chats when a customer has been inactive for an amount of time? I have several operators (we use a shared set of account with schedules for people... that's another story) but at

      • Report on opportunities showing only the last note added.

        Hi I need to create a report that shows the most recent note added to each opportunity. This is so management can see what the latest update is according to the assigned salesperson. One workaround is to use the status field but this implies added manual work and mistakes as the salesperson would have to copy the existing status to a note before adding the latest status... otherwise the activity history would be lost. My current workaround is a report on Notes with Opportunities as the related module.

      • Please add Zelle as an online payment option

        Hello, I would like to request Zelle be added to the online payment service providers for Zoho Invoice. Considering how ubiquitous Zelle has become as a way to pay people via the major banking institutions, I feel like many freelancers would benefit from

      • Getting Project Template List using the REST API

        I am trying to confirm that I can use the REST API to create a project using a project template. The API documentation indicates this is possible by providing the Template ID, but it is not clear at all how to get a list of available Project Templates

      • How to display the CONTACT ID in the Contact page

        Hi, I've seen this conversation below and it is exactly the same question I'm raising now, but unfortunately the last message is not solved https://help.zoho.com/portal/community/topic/show-contact-id-while-editing-contact-form I need to show the ContactId and I don't know how to do this. The last message included in the conversaton shows the way but not it is not completed. "I am sorry by default we do not have the option to show the record ID for the contacts in the field in a record. When you

      • How to change margins in templates

        Hi, I'm new to Zoho Campaigns, and am trying to figure out how to adjust the margins within an email template.  The default margins make the text go all the way to the edges of the page.  Please advise.

      • Create Canvas list view templates from images powered by Zia

        Currently available for all paid editions of Zoho CRM in the US, EU, IN, JP & CN DCs. Designing a personalized CRM interface just got even easier. In today’s fast-evolving digital landscape, AI is transforming the way we work by automating complex tasks

      • Painfully Slow Zoho mail

        Since yesterday Zoho Mail seems to have starting functioning very slowly and having a few bugs. It's slow to open mails, slow to send, slow to change between email accounts. Sometimes clicking on a particular folder (eg Sent folder) stops working and

      • "Wrong password or login" Problem to configure Zoho on MAIL App on my Macbook

        Hi, I'm having problems to configure my e-mail on my MAIL App(Macbook pro). My e-mail is hari@trespontoum.net Actually was working perfectly, and still working on my Iphone. My MAIL App prompt me that my login or password is wrong. I tried to change 3

      • "User already exist in your org"

        Hello, I've just read a discussion about this issue, which didn't solve my problem. I'm trying to add the following emails: sales@kiss-my-boutique.co.uk returns@kiss-my-boutique.co.uk orders@kiss-my-boutique.co.uk I'm getting an error message each time I try and add them. None of them are primary or secondary emails and none of them have been created as users before. I know this as when I try and login and do 'forgot my password' all I get is an error message saying 'user invalid'. Please advise.

      • Operation Not Permitted

        Hi, I have problem in adding user after verifying the domain but it seems like error appeared which is "operation not permitted". For your information, I had delete other domain before did it.

      • Email forwarding setup fails

        I'm trying to set up email forwarding from my Zoho email to my gmail address. I followed the directions to set up email forwarding here: https://www.zoho.com/mail/help/email-forwarding.html. I did only steps 1-6. After doing this, rather than setting

      • Shopify store email issues- Not getting emails

        Hi We have migrated from Microsoft outlook to Zoho back in March, we have a shopify store, the domain is hosted on namesilo, not shopify, I have seen some people here complaining about not getting emails from customers who fill out the contact form on

      • Invoice Discount Account

        Is there a way to change the account used for Discounts applied to an invoice? The current Discount account (ZB native account) type is an "Income" type. I would like to change it to "Other Income", but that is not possible, I am assuming because it contains

      • Need Inactive accounts to be visible in Reports in Zoho Books

        I N=need Inactive accounts to be visible in Reports in Zoho Books to do recons of the accounts but when i see the same they are not visible in the Accountant - Account Transactions report

      • javax.mail.authenticationfailedexception 535 authentication failed

        Hi, I am facing 535 authentication failed error when trying to send email from zoho desktop as well as in webmail. Can you suggest to fix this issue,. Regards, Rekha

      • Phantom Opening Balance

        While experimenting w/ creating a composite item, Zoho added funds to Petty Cash and added Bank Account equal to previous day's balance. I'm unable to undo the adding of funds. Attaching screenshots of both bank account and petty cash transactions.

      • Importing customer comments and multiple shipto addresses

        I am evaluating Zoho Books and have most of my data imported with two exceptions: (1) Import customer comments - in my current system I have several comments of different types, and I need to bring these into Zoho. Preferably Books customer records, but

      • Detailed Account Reports - Add Running Balance

        When one clicks into an account from a report (say P/L or Balance Sheet), the default reports have the Debit, Credit, and then the Amount. The Amount column (last one) is duplicate information. It would be far better and fit more peoples' use cases if

      • How to Billed from two different GST Numbers

        How to Billed from two different GST Numbers. Suppose ABC & Co had GST registration in Delhi and Haryana and Zoho account is created with Delhi GST Registration number. Now i also want to issue invoice from Haryana GST Registration number. How can i proceed ?

      • Zoho IP blocked by SpamHaus

        ERROR CODE :550 - 5.7.0 Your server IP address is in the SpamHaus SBL-XBL database, bye

      • IMAP Communication Problems - IMAP Down Again

        We are experiencing the same problems over the last week or so that were supposedly 'solved' according to this thread. Zoho Imap Down Again This is affecting attempts to use IMAP on multiple ISPs and users so is definitely narrowed down to Zoho problems.

      • Make the Flexible User Pricing actually flexible - allow bundled apps to be licensed individually

        The 'Flexible User Pricing' is not flexible! Please make it flexible. Allow bundled apps to be licensed individually. Although Zoho One offers nearly all Zoho apps, one has to choose which apps to include in the bundle when joining Zoho One. Any included app is forced into Zoho One licensing. The unfortunate implication of this is that one cannot add an individual app user license for any of the bundled apps. If you try to add a user in any bundled app, it will redirect you to Zoho One licensing

      • Can't login to Zoho mail

        I'm logged into Zoho but when I try to go in zoho mail I get: Invalid request! The input passed is invalid or the URL is invoked without valid parameters. Please check your input and try again. I just set up my mx records and stuff with namecheap a few

      • Hotmail is STILL blocking the zoho mail IP

        Greetings, as I already mentioned in my last message, my Zoho IP has been blocked by Hotmail for more than 15 days. Although someone said that the issue was "solved," it still isn't, and this amount of time seems neither normal for a "serious" company,

      • Next Page