Connections

Overview

Connection is used to establish authentication with other Zoho or third-party services to perform integration with them. You can consider connection as a way to login to any Zoho or third-party service. So, if you're already logged in (connected) to a particular service, you can always access your data stored in those services. Once a connection is created and connected, you can use it in Deluge integration tasks and invoke URL scripts to access data from the required service. For example, to access your Twitter account using Twitter's REST APIs from your Zoho CRM, you can create a Twitter connection, connect to it, and use the connection link name in invoke URL Deluge task. The invoke URL task will perform the specified API call to your connected Twitter account. 

Types

• Default connection: You can choose from the already available list of services, provide your credentials, and establish a connection.
• Custom connection: If the desired service is not available in the default services list, you can configure it on your own and connect to it.

Default connection

Perform the following actions to create a connection with a default service:

1. Navigate to the Connections page and click on the service under Pick your Service to which you want to connect your Zoho Service.
   Note: The above image exhibits the connections page in Zoho CRM. There could be minor variations in the way the connections page look in different Zoho services. However, their functionalities will be the same.
2. In the Connection Details window, perform the following actions:
   • Provide connection name. This will be the display name for your connection. Display name can contain up to 50 characters.
   • Provide connection link name. Link names must be unique and can be used in Deluge integration tasks and invoke URL scripts to establish authentication.
     Note: The link name that you provide must satisfy the following conditions:

     • It must begin with a lower case letter.
     • It can contain lower case letters, numbers, and underscores (_).
     • It can contain up to 50 characters.
   • Choose appropriate scopes, if required.
     Note: The scopes and their availability vary depending upon the service that you pick. You can find the applicable scopes in the desired service's API documentation.
   • Click on Create and Connect.
   

   use credentials of login user checkbox: This allows other users to utilize the connection that you've created. If this checkbox is checked, other users can authenticate your connection using their credentials and a copy of it will be listed under “Shared connections” in their connections page.

   Shared connection: The connections that are not created by you but only authenticated using your credentials will be listed under "shared connections". These connections will be listed under "own connection" for the user who created the connection and under "shared connection" for the users who simply authenticated it using their credentials.

   Consider the following scenarios to understand the "user credential of login user" checkbox and shared connections:

   • Let's assume you want to create and publish a Zoho Cliq bot for everyone in the organization that will upload the files forwarded to it into the user’s Google Drive account. To achieve this integration, you must create a connection to Google Drive and use it in the invoke URL Deluge task. And while creating the connection, you must check the “user credential of login user" checkbox so that the users can authenticate your connection using their credentials. Hence, the files will be uploaded to the user’s Google Drive account. If the checkbox was not checked, the connection will run using the credentials of the connection owner and the files sent by all the users will be uploaded in your (connection owner’s) Google Drive account.
     
     In this example, the "user credential of login user" checkbox should be checked and all the bot users will authenticate your Google Drive connection using their credentials. Therefore, a copy of your connection will be listed under shared connections in their connections page while it will be listed under “own connections” in your connections page.
      
   • Imagine you want to create and publish a  Zoho Cliq slash command for everyone in the team that will fetch the team's task list from Zoho Projects. Unlike the previous example, you need not check the "use credentials of login user" while creating the connection because every user wants to access the same data. So, rather than encouraging every single user to authenticate your connection in order to access your team's common data, you can use allow them to use your connection to communicate with Zoho Projects.
     
     In this example, the users will not authenticate your connection using their credentials, instead they make use of your connection as such. So, this connection will not be listed in the user’s connections page.
      
   • A User Permissions dialog will pop up, provide your login credentials, and proceed. Or, click on Allow if you are already logged into the service.
     
   • A summary page displaying the Connection summary will be displayed.
     
   • Upon successful authorization, the connection listed in your connections page under Own Connection.
     
   • Hover the cursor over the Connection to edit, revoke or delete the Connection.
     

Custom connection

• Navigate to the Connections page
• Navigate to the Add connection button
• Click on Create Your Own under Custom Service.
• Under service details, provide the following information:
  • Service Name: This is the display name of the service that you want to create. Display name can contain up to 50 characters.
  • Service LinkName: Link name of the service to help you to uniquely identify your custom service.
    Note: The link name that you provide must satisfy the following conditions:

    • It must begin with a lower case letter.
    • It can contain lower case letters, numbers, and underscores (_).
    • It can contain up to 50 characters.
  • Authentication Type: Choose from the following authentication types based on the desired service's API documentation

    Type	Description	Fields
    API Key	This auth type requires you to specify the params for establishing a connection with the desired service. In the next step, you will have to supply values for these params to perform the integration. For example, if you specify authtoken as param, the next step would be to provide your account's auth token to establish a successful connection.	On choosing API Key as authentication type, you need to provide values to the following fields: Actual Parameter: Name of the key (as specified in the API documentation of the desired service) against which the parameter needs to be sent  Parameter Display Name: Display name for the parameter. This name will be prompted when you authenticate a connection. Param Type:  This decides how the authentication parameters will be sent along with the URLs specified in the invoke URL scripts. Supported param types: Query string, Form Data, and Header Note: You can add as many parameters as required. Parameter could be any type of key that is required for authentication. Example: api-key, user-key, authtoken, apitoken, etc.
    Basic	This auth type requires you to specify the username and password in the next step. The provided username and password will be automatically encrypted with base64 algorithm and passed as header in the format: basic <encrypted_username>:<encrypted_password>.	N/A
    OAuth 1	This auth type requires you to specify the required parameters to perform an OAuth 1 authentication.	On choosing OAuth 1 as authentication Type, you need to provide values to the following fields: Consumer Key: Consumer key that is issued by the service provider Consumer Secret: Your consumer secret to authorize your application Request Token URL: URL to fetch the request token as specified in the API documentation of the desired service Authorize URL: Authorize URL as specified in the API documentation of the desired service Access Token URL: URL to fetch the access token as specified in the API documentation of the desired service Param Type: This decides how the authentication parameters will be sent along with the URLs specified in the invoke URL scripts. Supported param types: Query string, Form Data, and Header
    OAuth 2	This auth type requires you to specify the required parameters to perform an OAuth 2 authentication.	On choosing OAuth 2 as authentication Type, you need to provide values to the following fields: Grant type: Grant type that the desired service uses to perform authorization. You can choose from the supported grant types: Authorization code and client credentials Client Id: Client ID that is issued by the service provider Client Secret: Your client secret to authorize your application Authorize URL: Authorize URL as specified in the API documentation of the desired service Access Token URL: URL to fetch the access token as specified in the API documentation of the desired service Refresh Token URL: URL to fetch the request token as specified in the API documentation of the desired service Param Type: This decides how the authentication parameters will be sent along with the URLs specified in the invoke URL scripts. Supported param types: Query string, and Header. Note: When registering a Zoho client in the required service's developer console, the callback URL needs to be: US domain: https://deluge.zoho.com/delugeauth/callback EU domain: https://dre.zoho.eu/delugeauth/callback CN domain: https://dre.zoho.com.cn/delugeauth/callback IN domain: https://deluge.zoho.in/delugeauth/callback AU domain: https://dre.zoho.com.au/delugeauth/callback JP domain: https://dre.zoho.jp/delugeauth/callback

  • Under connection details, provide the following information:
    • Connection Name: Display name of your connection
    • Connection LinkName: Link names must be unique and can be used in Deluge integration tasks and invoke URL scripts to establish authentication.
      Note: The link name that you provide must satisfy the following conditions:

      • It must begin with a lower case letter.
      • It can contain lower case letters, numbers, and underscores (_).
      • It can contain upto 50 characters.
    • Scope (applicable only to OAuth 2 auth type): Scopes required to perform integration as specified in the desired service's API documentation.
    • Scope Delimiter (applicable only to OAuth 2 auth type): Delimiter with which the desired service API expects the scopes to be separated.
      Note:

      • You can select from the supported delimiters: comma, space, and plus. If not specified, comma is assumed as default delimiter.
      • You can choose delimiters only if you provide more than one scope.
  
  
• A User Permissions dialog will pop up, provide your authentication credentials and proceed.
• A summary of the connection will be displayed.
  
• Upon successful authorization, the connection will be created and listed in your connections page under "Own Connections". And, the configured service will be listed under Custom Service.
  Note: Once a custom service is configured, it will be available for everyone in the organization. So, other users need not configure the custom service instead they can simply create connections using the service.
  
• Hover over the connection to edit, revoke or delete it.
  

Edit a custom service

To edit a custom service:

• Navigate to connections page.
• Click on "Add connections" button.
• Click on the custom service that you want to edit. This page lists all the custom services configured by every user of your organization. However, you can only edit the services that are configured by you.
  
• In the connection details page, click on the edit button below the custom service display name
  
• Make the required changes and click on "update" button.