Java SDK for Zoho CRM
Table of Contents
Java SDK for Zoho CRM APIs provides wrapper for Zoho CRM APIs. Hence invoking a Zoho CRM API from your client Java application is just a method call.
Download the SDK file here to get started on your project.
Since Zoho CRM APIs are authenticated with OAuth2 standards, you should register your client app with Zoho. To register your app:
- Visit this page https://accounts.zoho.com/developerconsole.
- Click on “Add Client ID”.
- Enter Client Name, Client Domain and Redirect URI.
- Select the Client Type as Web based.
- Click “Create”.
- Your Client app would have been created and displayed by now.
- The newly registered app's Client ID and Client Secret can be found by clicking Options → Edit.
(Options is the three dot icon at the right corner).
Java SDK is available as a JAR file. The SDK expects the following from the client app.
- The client app should be running on at least Java 7.
- The jar and the required configuration files should be added as a SDK to the client project and should be available in the class path during compilation and running.
- While starting up your application, the method ZCRMRestClient.initialize(); must be called and invoked successfully without any exceptions.
- Only upon the successful execution of the above snippet, the SDK would work properly. Hence we recommend you to stop your application, if the SDK initialization throws any exception.
Your OAuth Client details should be given to the SDK as a property file. Please create a file oauth_configuration.properties and place it under “resources” folder and make sure that the “resources/oauth_configuration.properties” is available in your class path.
The file must be in the following format with the following properties & their respective values.
- client_id, client_secret and redirect_uri are your OAuth client’s configurations that you get after registering your Zoho client.
- Scope can be one or many (comma separated) valid Zoho CRM scopes. Add Aaaserver.profile.Read scope to your given scopes. It is mandatory.
- access_type shall be set to offline or online.
- persistence_handler_class is your implementation of the ZohoPersistenceHandler interface, which has handler methods to store OAuth data. Example: persistence_handler_class=com.zoho.oauth.clientapp.ZohoOAuthFilePersistence (or) com.zoho.oauth.clientapp.ZohoOAuthDBPersistence (or) your own persistence handler class.
- If you prefer to use our DB persistence, you need to give the mysql_username and mysql_password keys for mysql connectivity. By default, mysql_username = "root" and mysql_password = "".
Other than the above OAuth configurations, the SDK also provides options to override certain HTTP request attributes. These configurations should be provided in a file named zcrm_configuration.properties, which should also be placed under the “resources” folder.
The following are the supported configurations in the zcrm_configuration.properties file.
- timeOut value represents the request time out in seconds. Let timeout be empty if not needed.
- userAgent value provides an optional name for your client's identification.
- minLogLevel value represents the minimum log level for the logger prints of SDK. The supported values are ALL, TRACE, DEBUG, INFO, WARNING, ERROR and OFF. The default minimum log level is WARNING.
- If you are serving multiple users, in order for the SDK to identify the specific user who requests, the requester's email address should be set through the following code snippet before making the actual method call of the SDK.
- Else in case of single user, you can either set the user's email id in ZCRMRestClient (as the above) for every request or you may give the user's email id in zcrm_configuration.properties file with the key currentUserEmail as a one time configuration.
- accessType (optional) - Type of environment in CRM
- Production - Environment that have active paying users accessing critical business data.
- Development - Environments where you can extend, integrate and develop without affecting your production environments.
- Sandbox - Environments specifically used for testing application functionality before deploying to production or releasing to customers.
- domainSuffix (optional) - Multi DC support.
- us - www.zohoapis.com
- eu - www.zohoapis.eu
- cn - www.zohoapis.com.cn
After the app is being authorized by the user, OAuth access and refresh tokens can be used for subsequent user data requests to Zoho CRM. Hence they need to be persisted by the client app.
To facilitate this, you should write an implementation of the builtin ZohoPersistenceHandler interface, which has the following callback methods.
- saveOAuthData(ZohoOAuthTokens tokens) — this is invoked while fetching access and refresh tokens from Zoho.
- deleteOAuthTokens()—this is invoked before saving the newly received tokens.
- getOAuthTokens() — this is invoked before firing a request to fetch the saved tokens. This method should return ZohoOAuthTokens object for the library to process it.
The name (along with its package) of this implementation class should be given as peristence_handler_class in oauth_configuration.properties. Two sample implementations of ZohoPersistenceHandler are readily available with the client library.
You could readily use any of the two sample implementations we have provided along with the library — ZohoOAuthFilePersistence or ZohoOAuthDBPersistence.
ZohoOAuthDBPersistence uses a custom MySQL persistence. To use this, you should make sure of the following.
- MySQL should be running in the same machine serving at the default port 3306.
- The database name should be “zohooauth”.
- There must be a table “oauthtokens” with the columns “useridentifier” (varchar), “accesstoken” (varchar), “refreshtoken" (varchar) and “expirytime” (bigint).
ZohoOAuthFilePersistence uses a local file to write and read the OAuth tokens data. The full path of the file which shall be used by the library to write and read the tokens data should be specified in the oauth_configuration.properties file as the value of the property “oauth_tokens_file_path”. (For example, oauth_tokens_file_path=/user-path/src/resources/oauthtokens.properties).
ZohoOAuthFilePersistence implementation only supports to store and refresh only a single user’s token. Hence this shall be used if your app accesses Zoho APIs on behalf of a single user only. In case if your app has to support for multiple users, please use ZohoOAuthDBPersistence or write your own implementation of ZohoPersistenceHandler.
The app is ready to be initialized after defining OAuth configuration file and OAuth persistence handler class for your app.
Generating grant tokens
For Single user:
The developer console has an option to generate grant token for a user directly. This option may be handy when your app is going to use only one CRM user's credentials for all its operations or for your development testing.
- Log in to the User's account.
- Visit https://accounts.zoho.com/developerconsole.
- Click on the Options → Self Client option of the client for which you wish to authorize.
- Enter one or more (comma separated) valid Zoho CRM scopes that you wish to authorize in the Scope field and choose the time of expiry.
- Copy the grant token that is displayed on the screen.
- The generated grant token is valid only for the stipulated time you chose while generating it. Hence, the access and refresh tokens should be generated within that time.
- The OAuth client registration and grant token generation must be done in the same Zoho account's (meaning - login) developer console.
For Multiple Users:
For multiple users, it is the responsibility of your client app to generate the grant token from the users trying to login. Your Application's UI must have a "Login with Zoho" option to open the grant token URL of Zoho, which would prompt for the user's Zoho login credentials.
Upon successful login of the user, the grant token will be sent as a param to your registered redirect URL.
Generating access and refresh tokens
After obtaining the grant token, the following code snippet should be executed from your main class to get access and refresh tokens. Please paste the copied grant token in the string literal mentioned.
ZohoOAuthClient cli = ZohoOAuthClient.getInstance();
String grantToken = “paste_the_self_authorized_grant_token_here”;
ZohoOAuthTokens tokens = cli.generateAccessToken(grantToken);
String accessToken = tokens.getAccessToken();
String refreshToken = tokens.getRefreshToken();
System.out.println(“access token = “ + accessToken + “ & refresh token = ” + refreshToken);
Please note that the above code snippet is valid only once per grant token. Upon its successful execution, the generated access and refresh tokens would have been persisted through your persistence handler class.
Once the OAuth tokens have been persisted, subsequent API calls would use the persisted access and refresh tokens. The SDK will take care of refreshing the access token using refresh token, as and when required.
The SDK requires the following line of code being invoked every time your app gets started.
Once the SDK has been initialized by the above line, you could use any APIs of the SDK to get proper results.
All Zoho CRM entities are modelled as classes having members and methods applicable to that particular entity. ZCRMRestClient is the base class of the SDK. ZCRMRestClient has methods to get instances of various other Zoho CRM entities.
The class relations and hierarchy of the SDK follows the entity hierarchy inside Zoho CRM. The class hierarchy of various Zoho CRM entities is given below:
Each class entity has functions to fetch its own properties and to fetch data of its immediate child entities through an API call.
For example: a Zoho CRM module (ZCRMModule) object will have member functions to get a module’s properties like display name, module Id, etc, and will also have functions to fetch all its child objects (like ZCRMLayout).
It is not always effective to follow the complete class hierarchy from the top to fetch the data of an entity at some lower level, since this would involve API calls at every level. In order to handle this, every entity class will have a getInstance() method to get its own dummy object and methods to get dummy objects of its child entities.
Please note that the getInstance() methods would not have any of its properties filled, since it would not fire an API call. This would just return a dummy object that shall be only used to access the non-static methods of the class.
Summing it up,
- ZCRMRestClient.getModule(“Contacts”) would return the actual Contacts module, that has all the properties of the Contacts module filled through an API call.
- ZCRMRestClient.getModuleInstance(“Contacts”) would return a dummy ZCRMModule object that would refer to the Contacts module, with no properties filled, since this doesn’t make an API call.
Hence, to get records from a module, you need not start all the way from ZCRMRestClient. Instead, you could get a ZCRMModule instance with ZCRMModule.getInstance() and then invoke its non-static getRecords() method from the created instance. This would avoid the API call that would otherwise have been triggered to populate the ZCRMModule object.
Accessing record properties
Since record properties are dynamic across modules, we have only given the common fields like createdTime, createdBy, owner etc. as ZCRMRecord’s default members. All other record properties are available as a map in ZCRMRecord object.
To access the individual field values of a record, use the getter and setter methods available. The keys of the record properties map are the API names of the module’s fields. API names of all fields of all modules are available under Setup → Marketplace → APIs → CRM API → API Names.
- To get a field value, use record.getFieldValue(fieldAPIName);
- To set a field value, use record.setFieldValue(fieldAPIName, newValue);
While setting a field value, please make sure of that the set value is of the apt data type of the field to which you are going to set it.
APIResponse and BulkAPIResponse are wrapper objects for Zoho CRM APIs’ responses. All API calling methods would return one of these two objects.
- A method-seeking entity would return APIResponse object, whereas a method-seeking list of entities would return BulkAPIResponse object.
- Use the getData() method to get the entity data alone from the response wrapper objects. APIResponse.getData() would return a single Zoho CRM entity object, while BulkAPIResponse.getData() would return a list of Zoho CRM entity objects.
Other than data, these response wrapper objects have the following properties:
- ResponseHeaders - remaining API counts for the present day/window and time elapsed for the present window reset.
- ResponseInfo - any other information, if provided by the API, in addition to the actual data.
- List<EntityResponse> - status of individual entities in a bulk API. For example: an insert records API may partially fail because of a few records. This array gives the individual records’ creation status.
All unexpected behaviours like faulty API responses, SDK anomalies are handled by the SDK and are thrown only as a single exception — ZCRMException. Hence its enough to catch this exception alone in the client app code.