Connecting to Zoho Books

Applications that support ODBC interface with an ODBC Driver Manager, which is included with the operating system, and also the Easysoft ODBC driver distribution on some platforms. One of the jobs that the ODBC Driver Manager does is to manage ODBC data sources. A data source specifies which ODBC driver to load, which data store to connect to, and how to connect to it.

Before setting up a data source, you must have successfully installed the Easysoft ODBC-Zoho Books Driver.

Connecting from Windows

Creating an ODBC data source

In the Windows taskbar search box, enter “Run”.

Do one of the following:

If your application is 64-bit, in the Run dialog box, enter:
```
odbcad32.exe
```
-Or-

If your application is 32-bit, in the Run dialog box, enter:

%windir%\syswow64\odbcad32.exe

If your not sure whether your application is 32-bit or 64-bit, start your application, then in Windows Task Manager check whether your application’s process name contains (32-bit). For example, the process name for the 32-bit version of Excel is Microsoft Excel (32-bit); the process name for the 64-bit version of Excel is Microsoft Excel. On older versions of Windows, 32-bit applications contain *32 in the process name rather than (32-bit).
For applications such as Oracle or SQL Server that run as a service, check the *Background processes* list rather than the Apps list in Task Manager.
If you’re running a programming language from within a Windows command-line shell (for example, Command or PowerShell), in your shell, run the .exe file for the programming language. For example, run perl, php, python, or node. In Task Manager, expand the process list for Windows Command Processor or Windows PowerShell, as appropriate, and check whether the process for your programming language contains (32-bit).

Do one of the following:
- To create a data source that only the user you’re currently logged in as can access, choose the User tab.
  If your application is a Windows service (for example, SQL Server or Oracle) creating a user data source won’t work, unless the service is running as the same user you’re logged in as.
- To create a data source that all users on this computer can access, choose the System tab.
Choose Add.
In the list of ODBC drivers, select Easysoft ODBC-Zoho Books Driver, and then choose Finish.
Complete the Easysoft ODBC-Zoho Books Driver configuration dialog box.
To find out how to do this, refer to the Connection attributes section.
To test the connection to Zoho Books, choose Test.
Note that this doesn’t test that the Easysoft ODBC-Zoho Books Driver is licensed. If you haven’t yet licensed the Easysoft ODBC-Zoho Books Driver, this ODBC data source won’t work with your application, even if the Test button succeeds.

Authentication

Zoho Books uses the OAuth security standard to authorise users.

To use the Easysoft ODBC-Zoho Books Driver, you need to obtain a refresh token, which enables the driver to get the access tokens it needs to make Zoho Books API requests.

By default, the Easysoft ODBC-Zoho Books Driver uses an app that we have registered with Zoho Books to supply an OAuth client ID and secret. If you want to use your own Zoho Books OAuth app, specify its client ID and secret in your Easysoft ODBC-Zoho Books Driver data source.

The reasons for using your own OAuth app are:

You want to create more than one Easysoft ODBC-Zoho Books Driver data source. For example, you need three data sources:
1. For the first data source, don’t specify a client ID or secret, the Easysoft ODBC-Zoho Books Driver will supply one.
2. Create an OAuth app. Specify this app’s client ID and secret in the second data source.
3. Create another OAuth app. Specify this app’s client ID and secret in the third data source.
You want to replace "Easysoft ODBC-Zoho Books Driver" with your own text in the web page that prompts users to grant access to their Zoho Books data. This page displays when users initially authenticate and obtain a Zoho Books refresh token. This is done as when configuring an Easysoft ODBC-Zoho Books Driver data source.

To create an OAuth app:

In the Zoho Books API console, choose Add Client.
In the Choose a Client Type list, choose Server-based Applications > Create Now.
In the Client Name box, enter a name.

This name is displayed to users in the web page that prompts them to allow access to their Zoho Books data.
Enter a home page URL.
In the Authorized Redirect URIs box, enter http://localhost:port. For example, http://localhost:8096.
Choose Create.

The Client Secret tab contains the values you supply in the Easysoft ODBC-Zoho Books Driver DSN configuration dialog box.

To obtain a refresh token on Windows, choose the Authenticate and obtain token button in the configuration dialog box when setting up your data source. This launches your default browser. Sign into your Zoho Books account and grant the permissions the Easysoft ODBC-Zoho Books Driver needs when prompted. Close the web browser window or tab when prompted.

You now have a refresh token. The Easysoft ODBC-Zoho Books Driver uses this to request the access tokens it needs to access your Zoho Books data.

Connection attributes

Name Value

Name	Value
DSN	The name of the data source. You’ll need to specify this in your application. For example, your application may prompt you to choose this from a list of DSNs.
Description	Some applications display this to help users identify a particular data source.
Acc Server	The URI of your Zoho Books server. For example, `https://accounts.zoho.eu/`. If you leave this field blank, the Easysoft ODBC-Zoho Books Driver attempts to discover this value when you authenticate and obtain a refresh token.
Location	The location of your Zoho Books server. For example, `eu`. If you leave this field blank, the Easysoft ODBC-Zoho Books Driver attempts to discover this value when you authenticate and obtain a refresh token.
Refresh Token	The Zoho Books refresh token that enables the Easysoft ODBC-Zoho Books Driver to work with your Zoho Books data.
Local Filtering	When turned on, the Easysoft ODBC-Zoho Books Driver increases its preferred batch size for queries, which alters the number of Zoho Books API calls it makes. Zoho Books may create batches that are larger or smaller than the requested size to maximise performance. There is no one correct setting for Local Filtering, it depends on how your application executes its queries. You may find that this attribute increases query performance for one application and decreases performance for another. By default, Local Filtering is turned off.
Proxy	If you use a proxy server connect to Zoho Books, use this attribute to specify this server’s details. Use this format: `http://address:port` where address is the host name or IP address of the proxy server and port is the proxy server port. For example: `http://squid.example.com:8080`
Proxy User	If your proxy server has authentication turned on, use this attribute to supply a user name that can connect to the proxy server. The Easysoft ODBC-Zoho Books Driver supports the Basic and Digest proxy authentication schemes.
Proxy Password	The password for the proxy user.
Driver Logging	Whether to turn on Easysoft ODBC-Zoho Books Driver logging. Normally, you’ll only do this if so directed by the Easysoft support team.
Log File	The file name and path of the file you want the driver to write log information to. For example: `C:\Windows\Temp\Easysoft.log` If the file doesn’t exist, the Easysoft ODBC-Zoho Books Driver creates it.
Flush On Update	Whether the Easysoft ODBC-Zoho Books Driver flushes its cache when it is used to update or delete Zoho Books data. When this setting is turned on, the effect of your changes will apply in your current session. For example, you turn on this setting and delete a record. If you then do a select in the same session, the record will no longer be present in the result set, If you do the same with Flush On Update turned off, the result set contains the deleted record until the Easysoft ODBC-Zoho Books Driver cache expires or you reconnect your application (for example, you restart your SQL Server instance).
Cache Timeout	The time in seconds that Easysoft ODBC-Zoho Books Driver stores records in its cache. If you set the timeout to 0, the Easysoft ODBC-Zoho Books Driver always caches records. The default value for Cache Timeout is 0. The Easysoft ODBC-Zoho Books Driver flushes the cache when you close the connection to Zoho Books. (For example, you quit your application or restart your application’s service.) To reduce Zoho Books API usage and reduce the amount of data retrieved over the network, the Easysoft ODBC-Zoho Books Driver caches Zoho Books records. By default, a record remains in the cache until the timeout elapses. Note that any changes to the record that happen at the Zoho Books end aren’t reflected in the cached copy until the cache is refreshed (that is, the timeout expires and the record is fetched again.) If a cached record is changed by the Easysoft ODBC-Zoho Books Driver, the cache is refreshed to reflect this change.
Max Num	The maximum number of records to return for each Rest API request the Easysoft ODBC-Zoho Books Driver makes.
Organization Id	The ID of your Zoho Books organization. If you leave this field blank, the Easysoft ODBC-Zoho Books Driver attempts to discover your organization ID. If you have multiple organizations and leave this field blank, the Easysoft ODBC-Zoho Books Driver gets all the available organizations, and uses the first one in the list. To find out your organization ID, in the Zoho Books web interface, choose the down arrow that’s next to your organization’s name in the top right corner.
Client Id	If you have created your own Zoho Books OAuth client app, enter the app’s client id here. Otherwise, leave this field blank.
Client Secret	The client secret for your Zoho Books OAuth client app.

DSN

The name of the data source. You’ll need to specify this in your application. For example, your application may prompt you to choose this from a list of DSNs.

Description

Some applications display this to help users identify a particular data source.

Acc Server

The URI of your Zoho Books server. For example, https://accounts.zoho.eu/.

If you leave this field blank, the Easysoft ODBC-Zoho Books Driver attempts to discover this value when you authenticate and obtain a refresh token.

Location

The location of your Zoho Books server. For example, eu.

If you leave this field blank, the Easysoft ODBC-Zoho Books Driver attempts to discover this value when you authenticate and obtain a refresh token.

Refresh Token

The Zoho Books refresh token that enables the Easysoft ODBC-Zoho Books Driver to work with your Zoho Books data.

Local Filtering

When turned on, the Easysoft ODBC-Zoho Books Driver increases its preferred batch size for queries, which alters the number of Zoho Books API calls it makes. Zoho Books may create batches that are larger or smaller than the requested size to maximise performance.

There is no one correct setting for Local Filtering, it depends on how your application executes its queries. You may find that this attribute increases query performance for one application and decreases performance for another.

By default, Local Filtering is turned off.

Proxy

If you use a proxy server connect to Zoho Books, use this attribute to specify this server’s details. Use this format:

http://address:port

where address is the host name or IP address of the proxy server and port is the proxy server port. For example:

http://squid.example.com:8080

Proxy User

If your proxy server has authentication turned on, use this attribute to supply a user name that can connect to the proxy server.

The Easysoft ODBC-Zoho Books Driver supports the Basic and Digest proxy authentication schemes.

Proxy Password

The password for the proxy user.

Driver Logging

Whether to turn on Easysoft ODBC-Zoho Books Driver logging. Normally, you’ll only do this if so directed by the Easysoft support team.

Log File

The file name and path of the file you want the driver to write log information to. For example:

C:\Windows\Temp\Easysoft.log

If the file doesn’t exist, the Easysoft ODBC-Zoho Books Driver creates it.

Flush On Update

Whether the Easysoft ODBC-Zoho Books Driver flushes its cache when it is used to update or delete Zoho Books data. When this setting is turned on, the effect of your changes will apply in your current session. For example, you turn on this setting and delete a record. If you then do a select in the same session, the record will no longer be present in the result set, If you do the same with Flush On Update turned off, the result set contains the deleted record until the Easysoft ODBC-Zoho Books Driver cache expires or you reconnect your application (for example, you restart your SQL Server instance).

Cache Timeout

The time in seconds that Easysoft ODBC-Zoho Books Driver stores records in its cache. If you set the timeout to 0, the Easysoft ODBC-Zoho Books Driver always caches records. The default value for Cache Timeout is 0.

The Easysoft ODBC-Zoho Books Driver flushes the cache when you close the connection to Zoho Books. (For example, you quit your application or restart your application’s service.)

To reduce Zoho Books API usage and reduce the amount of data retrieved over the network, the Easysoft ODBC-Zoho Books Driver caches Zoho Books records. By default, a record remains in the cache until the timeout elapses.

Note that any changes to the record that happen at the Zoho Books end aren’t reflected in the cached copy until the cache is refreshed (that is, the timeout expires and the record is fetched again.) If a cached record is changed by the Easysoft ODBC-Zoho Books Driver, the cache is refreshed to reflect this change.

Max Num

The maximum number of records to return for each Rest API request the Easysoft ODBC-Zoho Books Driver makes.

Organization Id

The ID of your Zoho Books organization. If you leave this field blank, the Easysoft ODBC-Zoho Books Driver attempts to discover your organization ID. If you have multiple organizations and leave this field blank, the Easysoft ODBC-Zoho Books Driver gets all the available organizations, and uses the first one in the list.

To find out your organization ID, in the Zoho Books web interface, choose the down arrow that’s next to your organization’s name in the top right corner.

Client Id

If you have created your own Zoho Books OAuth client app, enter the app’s client id here. Otherwise, leave this field blank.

Client Secret

The client secret for your Zoho Books OAuth client app.

DSN-less connections

Some applications allow you to make an ODBC connection without configuring a data source. To do this, you supply a connection string that contains the ODBC driver name and other driver-specific attribute-value pairs.

Here’s an example connection string for the Windows version of the Easysoft ODBC-Zoho Books Driver:

Driver={Easysoft Zoho Books ODBC Driver};Refresh_Token=2000.d2927da21cff612e6818f832a47c256e.379428ee4a4abc3040799dff191f8620;Location=eu;AccServer=https://accounts.zoho.eu;Logging=Yes;LogFile=C:\\Temp\\ZB2.log;

Connection string attributes have different names to the ones shown in the Easysoft ODBC-Zoho Books Driver data source configuration dialog box. Use these attribute names in a connection string:

Description
AccServer
Location
Refresh_Token
Organization
Proxy
Proxy_User
Proxy_Pass
Query_Timeout
Max_Num
Logging
Logfile
Filter_Local
Flush_On_Update