Important Terminology

1. Client: The application requesting access to data stored in an external system. When creating a connector, the client is Zoho FSM.
   
2. Resource: The application or service that the client is trying to access. In our case, the resource is the third-party service (ex: Dropbox) you are trying to integrate.
   
3. Request Token URL: This URL is used to send authorization requests to the resource server. The resource server prompts the resource owner (end-user) to authorize this request.
   
4. Access Token URL: Once the request is authorized by the resource owner, the server sends an access token to the client. This token has to be exchanged every time the clients wants to access the resource data.
   
5. Refresh Token URL: Some access tokens are valid only for a limited period of time. When an access token expires, the client has to get another access token from the resource, using the refresh token URL.
   
6. Client ID: A unique identifier provided to every client application. This ID is provided by the resource owner, i.e. Zoho FSM.
   
7. Client Secret: Every client application has a secret code mapped to it. This is done to prevent unauthorized access to the resource.
   
8. Redirect URL: This is the URL to which the end user will be redirected, once data access has been authorized. The client application will generate a redirect URL automatically.
   

Registering a Zoho Client

1. Visit this page https://accounts.zoho.com/developerconsole.
   
2. Click on Add Client ID.
   
3. Enter Client Name and Client Domain.
   
4. Enter the Redirect URI as "https://deluge.zoho.com/delugeauth/callback".
   
5. Select the Client Type as Web based.
   
6. Click Create.
   
7. Your Client app would have been created and displayed by now.
   
8. The newly registered app's Client ID and Client Secret will be displayed.
   

You can view the Client ID and Client Secret details at https://accounts.zoho.com/developerconsole by selecting Edit from the more options [  ] icon.

Note: Please note that this step has to be followed for Apps which are not natively available in 'Connections' tab. For instance, this step is required if you want to add a "Custom Service" in Connections.

Creating a Connection

1. Go to Setup > Developer Space > Connectors.
   
2. Click Get Started.
   
3. Select the Custom Service tab.
   
4. Provide a name for the service to be connected (ex: Google contacts).
   
5. Select the type of Authentication that is supported by the third-party application or service.
   
   
   
   
6. Provide the following details about the third-party server:
   
1. Client ID and Client Secret.
   
2. Request Token URL: This allow the connector to request authorization to access data on the resource server.
   
3. Access Token URL: Once authorized, the Request Token and Token Key will be exchanged for the Access Token, allowing the connector to draw specific information from the third-party server.
   
4. Refresh Token URL: Some applications increase security by limiting the duration of time a particular token is valid. In these cases, you will need to provide the Refresh Token URL to allow the connector to reauthorize access.
   
   
   
   
7. Give a name of your choice for the Connection.
   
8. Provide Scopes for the connection. Scope for each connection is given by the third-party service. Please check the help for the respective third-party service to know about their provided scopes.
   
   
   
   
9. Click Create and Connect.
   Once the connection is created, it will be available in the Pick Your Service tab.

About Tokens  

Using a Connection

1. Go to Setup > Developer Space > Connections.
   
2. Select the required Connection from the Pick Your Service tab.
   
3. Provide a Connection name.
   
   
   
   
4. Click Create and Connect.
   
5. In the following page, the Link name, Service name and Status of the Connection are shown.
   
6. Additionally, the code to be used in a function to invoke the connection is also given in a box.
   
   
   
   
1. The URL can be obatined form the third-party service.
   
2. The Types POST, PUT, GET and DELETE are the HTTP methods that determine the type of action that request performs.
   
3. The Parameters are used by the function to replace dynamic values present in the API with user-specific values. For example, if the API must fetch the lead's details such as name, email address, contact number, etc., these values will be represented by a dynamic value in the API. This dynamic value can be replaced with the actual value from the Leads Details page using the parameter function. Examples given later in this document will give more detailed information about this function.
   
4. The Connection in the code is the link name.
   You can use the above block of code to invoke the URL and integrate the third-party app with Zoho FSM.

Sample Connection

Step 1: Getting Request, Access and Refresh tokens

1. Go to Setup > Developer Space > Connections
   
2. Click the Custom Service tab
   
3. Give the Service name as GoogleContacts
   
4. Set the Authentication type as OAuth 2
   
5. Provide the following information:
   
1. Client ID: {your_client_id}
   
2. Client Secret: {your_client_secret}
   
3. Authorize URL: https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.google.com/m8/feeds
   
4. Access Token URL: https://www.googleapis.com/oauth2/v4/token
   
5. Refresh Token URL: https://www.googleapis.com/oauth2/v4/token
   
6. Give a name for the Connection.
   
7. Provide the Scopes for the connection as specified by Google Contact.
   
8. Click Create and Connect.