This tutorial describes how to connect to Zoho CRM.

In this walkthrough:

• Requirements
• General information
• Creating ZohoConnection
• Opening connection
• Closing connection
• Modifying connection

Requirements

In order to connect to Zoho CRM you need to have the corresponding account, dotConnect for Zoho CRM installed and IDE running. You also have to know the required connection parameters described below.

Note that if you do not use design-time (specifically, if you do not place designer ZohoConnection component from the Toolbox to the form), you have to embed licensing information manually. This is described in topic Licensing.

Required Connection Parameters

To establish a connection to server you have to provide the required connection parameters to dotConnect for Zoho CRM. This information is used by ZohoConnection component to connect to Zoho CRM. The parameters are represented as a connection string. You can compose the connection string manually or have dotConnect for Zoho CRM construct it for you.

The following connection string parameters are required:

• Zoho domain - if your Zoho CRM is hosted in EU, India, Australia, or China, you need to specify the corresponding domain. Domain can be crm.zoho.com, crm.zoho.eu, crm.zoho.in, crm.zoho.com.au, or crm.zoho.com.cn.
• Zoho CRM API version to use - v1 or v2. depending on the API version used, different connection parameters are required. Note that API v1 has already reached End-of-Life.
• Security Token - The automatically generated key that is used for logging in to Zoho CRM from an untrusted network. For generating authentication token, you must have the permission to access the API service. If you do not have permission, please contact your CRM administrator. This parameter is required for Zoho CRM API v1.
• Zoho time zone - the timezone that is specified in your Zoho CRM account settings. This parameter is required for Zoho CRM API v1.
• Client Id - a unique identifier provided to every Zoho CRM client application when a Zoho CRM client application is registered with Zoho. This parameter is required for Zoho CRM API v2.
• Client Secret - a secret code, mapped to a Zoho CRM client application. This parameter is required for Zoho CRM API v2.
• Refresh Token - the Zoho CRM OAuth 2.0 token to retrieve access tokens automatically.

API v1 have already reached End-of-Life, and new API v1 tokens cannot be generated any more. As for obtaining parameters for API v2, see the following links:

• https://www.zoho.com/crm/help/developer/api/register-client.html
• https://www.zoho.com/crm/help/developer/api/auth-request.html
• https://www.zoho.com/crm/help/developer/api/access-refresh.html

Creating a Connection to Zoho CRM

Design time creation

The following assumes that you have IDE running, and you are currently focused on a form designer.

1. Open Toolbox and find ZohoConnection component in dotConnect for Zoho CRM category.
2. Double-click the component. Notice that new object appears on the designer underneath the form. If this is first time you create the ZohoConnection in this application it is named zohoConnection1.
3. Click on the zohoConnection1 object and press F4 to focus on object's properties.
4. Enter the required connection string parameters, described above, to the corresponding boxes.
5. Notice that as you assign values to these properties the ConnectionString property is automatically updated to reflect your settings. Now it contains something like "API Version=V2;Refresh Token=1000.a6fde76542bfbb5244a7e539d4390e72.87e34ea57023c2d0e7dcb9ce55e3e7f3;ClientId=1000.M4FJLKYTSED90LJHUTVMKKAA432RUK;ClientSecret=89a0ed79957808814cdb20b9765423efffa767d1d0".
6. If necessary, click the Advanced button and configure other connection string parameters. You can find the description of these connection string parameters in the ZohoConnection.ConnectionString topic.

Run time creation

You can also configure a connection at run-time by setting its ConnectionString property (note that you have to add references to Devart.Data.Zoho.dll, Devart.Data.SqlShim.dll, and Devart.Data.dll assemblies):

zohoConnection1.ConnectionString = "API Version=V2;Refresh Token=1000.a6fde76542bfbb5244a7e539d4390e72.87e34ea57023c2d0e7dcb9ce55e3e7f3;ClientId=1000.M4FJLKYTSED90LJHUTVMKKAA432RUK;ClientSecret=89a0ed79957808814cdb20b9765423efffa767d1d0";

zohoConnection1.ConnectionString = "API Version=V2;Refresh Token=1000.a6fde76542bfbb5244a7e539d4390e72.87e34ea57023c2d0e7dcb9ce55e3e7f3;ClientId=1000.M4FJLKYTSED90LJHUTVMKKAA432RUK;ClientSecret=89a0ed79957808814cdb20b9765423efffa767d1d0"

Using connection string builder

If you decide to setup connection by assigning values to several properties, consider using ZohoConnectionStringBuilder class. It has all of the possible connection settings exposed as properties, thus allowing to customize the connection at full extent.

ZohoConnectionStringBuilder connectionStringBuilder = new ZohoConnectionStringBuilder();

connectionStringBuilder.APIVersion = "V2";
connectionStringBuilder.RefreshToken = "1000.a6fde76542bfbb5244a7e539d4390e72.87e34ea57023c2d0e7dcb9ce55e3e7f3";
connectionStringBuilder.ClientId = "1000.M4FJLKYTSED90LJHUTVMKKAA432RUK";
connectionStringBuilder.ClientSecret = "89a0ed79957808814cdb20b9765423efffa767d1d0";

ZohoConnection myConnection = new ZohoConnection(connectionStringBuilder.ConnectionString);

Dim connectionStringBuilder As ZohoConnectionStringBuilder = New ZohoConnectionStringBuilder

connectionStringBuilder.APIVersion = "V2"
connectionStringBuilder.RefreshToken = "1000.a6fde76542bfbb5244a7e539d4390e72.87e34ea57023c2d0e7dcb9ce55e3e7f3"
connectionStringBuilder.ClientId = "1000.M4FJLKYTSED90LJHUTVMKKAA432RUK"
connectionStringBuilder.ClientSecret = "89a0ed79957808814cdb20b9765423efffa767d1d0"

Dim myConnection As ZohoConnection = New ZohoConnection(connectionStringBuilder.ConnectionString)

Notice that in this example we used ZohoConnection constructor that accepts connection string as argument.

For the information on arguments allowed in the connection string, refer to the description of the ZohoConnection.ConnectionString property.

Creating Connection in Server Explorer

To create a Server Explorer connection, you just need to:

1. Click Connect to Database on the Server Explorer toolbar
   
   
2. If the Zoho CRM Data Source is not selected by default, click the Change button.
3. Select Zoho CRM Data Source (dotConnect for Zoho CRM) and click OK.
4. Select the API Version to use - v1 or v2.
5. For API v2, click Web Login and sign in to your Zoho CRM account, then allow access to Zoho CRM data. For API v1 specify your Security Token and time zone from your Zoho CRM account settings.

After this you can browse Zoho CRM objects in Server Explorer.

Opening connection

Opening a connection is as simple as that:

myConnection1.Open();

myConnection1.Open()

Of course, the myConnection1 object must have a valid connection string assigned earlier. When you call Open, dotConnect for Zoho CRM tries to find the host and connect to Zoho CRM. If any problem occurs it raises an exception with brief explanation on what is wrong. If no problem is encountered dotConnect for Zoho CRM tries to establish the connection during ConnectionTimeout interval. Finally, when connection is established, the Open method returns and State property is changed to Open.

In design time you can connect to server in few steps:

1. Right-click on the connection object in designer and then click Connect.
2. In the dialog window provide the required connection parameters.
3. Click on the connection object and press F4 to focus on object's properties.
4. If necessary, click the Advanced button and configure other connection string parameters. You can find the description of these connection string parameters in the ZohoConnection.ConnectionString topic.
5. Click Connect to establish connection.

Or you can simply change the State property to Open in the Properties window to establish a connection using the current connection string.

Closing connection

To close a connection call its Close method, or set its State property to Closed.

The following example summarizes aforementioned information and shows how to create, setup, open, use and then close the connection.

ZohoConnection myConn = new ZohoConnection();
myConn.ConnectionString = "API Version=V2;Refresh Token=1000.a6fde76542bfbb5244a7e539d4390e72.87e34ea57023c2d0e7dcb9ce55e3e7f3;ClientId=1000.M4FJLKYTSED90LJHUTVMKKAA432RUK;ClientSecret=89a0ed79957808814cdb20b9765423efffa767d1d0";
myConn.Open();
MessageBox.Show(myConn.ServerVersion);
myConn.Close();

Dim myConn As ZohoConnection = New ZohoConnection()
myConn.ConnectionString = "API Version=V2;Refresh Token=1000.a6fde76542bfbb5244a7e539d4390e72.87e34ea57023c2d0e7dcb9ce55e3e7f3;ClientId=1000.M4FJLKYTSED90LJHUTVMKKAA432RUK;ClientSecret=89a0ed79957808814cdb20b9765423efffa767d1d0"
myConn.Open()
MessageBox.Show(myConn.ServerVersion)
myConn.Close()

The sample code connects to server, shows its version and then closes the connection. This actually is a rare usage, because in real applications connections are used by other objects like ZohoCommand, ZohoDataReader and others. For more information on this please see corresponding tutorials or reference information.

Modifying Connection

You can modify connection by changing properties of ZohoConnection object. Keep in mind that while some of the properties can be altered freely, most of them close connection when new value is assigned.