Kaizen #15 - Java SDK for Self Client

Hello everyone!

Welcome to yet another post in the Kaizen series.

This week, we are going to discuss the Java SDK for a self client .

What is a Software Development Kit (SDK)?

A software development kit contains all the tools (compiler, debugger, code samples, and so on) that are needed to create applications in one package. SDKs are language-specific and thus used to build client applications in a specific programming language.

Java Software Development Kit

Java SDK allows you to create a client Java applications that can be integrated with Zoho CRM effortlessly. It serves as a wrapper for the REST APIs , thus making it easier to use the services of Zoho CRM.

Here is a sample of how SDK acts as a middleware between Zoho CRM and Client Java Application.

What can you do with the Java Software Development Kit?

You can use Java SDK to exchange data between Zoho CRM and the client Java application.
The authentication process becomes hassle-free with Java SDK. Since it is handled in the SDK code by default, you need not worry about generating the grant token, access/refresh tokens every time you sync data between Zoho CRM and your self client.

Environment Setup

Java SDK requires Java version 7 or above to be set up in your development environment.

Including the Java SDK in your project

You can include the Java SDK in your project using:

a. Maven distribution

b. Gradle

c. Downloadable JARs

a. Maven distribution - It is a build automation tool used primarily for Java projects. Include the following code to your pom.XML file.

<repositories>

<repository>

<id>java-sdk</id>

<url> https://maven.zohodl.com </url>

</repository>

</repositories>

<dependencies>

<dependency>

<groupId>com.zoho.crm</groupId>

<artifactId>java-sdk</artifactId>

<version>2.0.2</version>

</dependency>

</dependencies>

b. Gradle - It is also a build tool, similar to Maven. The major difference is that, instead of XML files, Gradle uses Groovy (a domain-specific programming language) to declare the Java project configuration. You need to add the following code to your build.gradle file.

repositories{

maven { url " https://maven.zohodl.com " }

}

dependencies{

implementation 'com.zoho.crm:java-sdk:2.0.2'

}

c. Downloadable JARs (by Zoho) - Java Archive is a platform-independent file format that aggregates many files into one. The JAR file consists of the SDK. You have to download individual dependency JARs and add them to your reference libraries in your Java application: Download JAR (SDK)

Click here to download the dependency JARs.

The list of dependency JARs are:

hamcrest-all-1.3 : Hamcrest consists of a single jar file that contains base classes and a library of useful matcher implementations.
httpclient-4.4.1 : The Apache HttpClient library allows you to handle HTTP requests.
httpcore-4.4.4 : HttpCore is a set of low-level HTTP transport components that you can use to build custom client and server-side HTTP services.
httpmime-4.5.3 : The Apache HttpMime library consists of MIME code entities.
json-20170516 : The files in this package implement JSON encoders/decoders in Java. It also includes the capability to convert between JSON and XML, HTTP headers, Cookies, and CDL.
servlet-api-2.5 : Servlet API consists of classes to support HTTP servlet.
commons-logging-1.1.3 : The commons-logging JAR provides an API for logging in server-based applications that you can use around a variety of different logging implementations.
mysql-connector-java-5.1.44-bin.jar : You need to include this JAR if you are using a MySQL database. MySQL Connector JAR provides connectivity for java client applications with MySQL Connector (a driver that implements the Java Database Connectivity (JDBC) API)

How to start using the Java SDK?

In this section, we will discuss how to start using the Java SDK for your application (authenticated via self-client) which uses Zoho CRM.

Prerequisite: Register your application
Knowlege Base: Adding persistence classes
Initialization

1. Prerequisite: Register your application

All the Zoho CRM APIs are authenticated by the OAuth2.0 standards . It is mandatory to authenticate the self client with Zoho.

Step 1: Goto https://api-console.zoho.com

Step 2: Click ADD CLIENT

Step 3: Choose Self Client and click CREATE NOW

Step 4: Choose the Client Type as Self Client , and click CREATE .

Step 5: Once you successfully register your self-client, you will receive a Client ID and Client Secret .

2. Knowledge Base: Adding persistence classes

This section consists of two parts:

a. Initializing your client application

b. Adding persistence classes

a. Initializing your client application

To authenticate the client application, you need to add the following key-value configuration pairs to the initialization code of your java client.

Key Description

Key	Description
client_id, client_secret, and redirect_uri mandatory	You can get these values after registering your client.
currentUserEmail mandatory	The Email ID of the current user.
persistence_handler_class mandatory	The implementation of ZohoOAuthPersistenceInterface
logFilePath optional	The absolute/relative file path of the file that stores the logs.
domainSuffix optional	The domain from which the API calls are made. It can be .com (for US), .eu (for Europe), .cn (for China). If you specify this value, you need not specify apiBaseUrl and iamURL.
accessType optional	The type of environment from which the API calls are made. Possible values are "Production", "Development", or "Sandbox"
access_type optional	Must be set as as "offline". Online OAuth client is not supported by the Java SDK as of now
apiBaseUrl optional	The URL that is used to make API calls. You need not specify this value if you give domainSuffix. The possible values are: https://www.zohoapis.com (default) https://www.zohoapis.eu https://www.zohoapis.com.cn https://www.zohoapis.in
iamURL optional	The accounts URL. You need not specify this value if you specify domainSuffix. The possible values are: https://accounts.zoho.com (default) https://accounts.zoho.eu https://accounts.zoho.com.cn https://accounts.zoho.in
mysql_password and mysql_username mandatory when you use MySQL persistence	The MySQL username and password, respectively.

Key Value Configuration

HashMap <String, String> zcrmConfigurations = new HashMap <String, String >();

zcrmConfigurations.put("minLogLevel", "ALL");

zcrmConfigurations.put("currentUserEmail","{user_email_id}");

zcrmConfigurations.put("client_id","1000. xxxxxxxxx");

zcrmConfigurations.put("client_secret","xxxxxxxxxxxx");

zcrmConfigurations.put("redirect_uri","");

zcrmConfigurations.put("persistence_handler_class","com.zoho.oauth.clientapp.ZohoOAuthDBPersistence ");//for database. "com.zoho.oauth.clientapp.ZohoOAuthFilePersistence" for file, user can implement his own persistence and provide the path here

zcrmConfigurations.put("oauth_tokens_file_path","/path/to/oauthtokens.properties");//optional path can be absolute(Ex:/User/Document/testapplication/src/oauthtokens.properties) or relative (Ex: /testapplication/src/oauthtokens.properties)

zcrmConfigurations.put("domainSuffix","com");//optional. Default is com. "cn", "eu", and "in" supported

zcrmConfigurations.put("accessType","Production");//Production->www(default), Development->developer, Sandbox->sandbox(optional)

zcrmConfigurations.put("access_type","offline");//optional

zcrmConfigurations.put("apiBaseUrl"," https://www.zohoapis.com ");//optional

zcrmConfigurations.put("iamURL"," https://accounts.zoho.com ");//optional

zcrmConfigurations.put("logFilePath","/path/to/file.log");//path can be absolute(Ex:/User/Document/testapplication/src/file.log) or relative (Ex: /testapplication/src/file.log)

zcrmConfigurations.put("mysql_password","pass@123");//optional

zcrmConfigurations.put("mysql_username",username");//optional

ZCRMRestClient.initialize(zcrmConfigurations);//for initializing

2. Adding persistence class

Your application should retain tokens (grant, access, and refresh tokens) to automate the process of data-sync between your java application and Zoho CRM.

You can persist tokens in your application by using any one of the below mentioned persistence methods:

a. By using an implementation of the inbuilt ZohoPersistenceHandler interface .

ZohoOAuthFilePersistence (To store tokens in a File )
ZohoOAuthDBPersistence (To store tokens in a Database )

b. By using your own implementation

Let us now look into each of the above mentioned methods.

a. By using an implementation of the inbuilt ZohoPersistenceHandler interface

Our Java SDK provides two default implementations of the ZohoPersistenceHandler interface within the client library. They are:

i. ZohoOAuthFilePersistence

ii. ZohoOAuthDBPersistence

i. ZohoOAuthFilePersistence - This type of persistence uses a file to read and write OAuth tokens. The file persists the token of a single user. So, it is best used for the 'self-client' type of authentication since it involves only one user.

Values to be given in configuration map

persistence_handler_class =com.zoho.oauth.clientapp.ZohoOAuthFilePersistence

oauth_tokens_file_path =absolute or relative path of the "oauthtokens.properties" file in the workspace.

ii. ZohoOAuthDBPersistence - This type of persistence uses MySQL persistence. You can use this type of persistence if you have more than one user using the application.

Some of the prerequisites for using this type of persistence are:

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(255)), "accesstoken" (varchar(255)), "refreshtoken" (varchar(255)) and "expirytime" (bigint).

Values to be given in configuration map

persistence_handler_class =com.zoho.oauth.clientapp.ZohoOAuthDBPersistence

mysql_username =root

mysql_password ={your MySQL password}

b. By using your own implementation

You can also use your own implementation. The ZohoPersistenceHandler interface must have the following methods:

getOAuthTokens() — invoked to fetch the saved tokens. This method should return ZohoOAuthTokens object for the library to process it.
saveOAuthData(ZohoOAuthTokens tokens) — invoked to store the tokens.
deleteOAuthTokens() — invoked to delete the tokens.

C. Initialization

Intializing your application involves the following steps:

Step 1: Generating the grant token

Step 2: Generating the access and refresh tokens using the grant token

Step 3: Generating the access token using the refresh token

Step 1: Generating the Grant Token

(i). Go to https://api-console.zoho.com/

(ii). Choose Self-Client

(iii). Enter the comma separated ZohoCRM scopes along with aaaserver.profile.READ . Choose the time duration (the grant token will be valid only till the time chosen here) and enter the description . Now, click GENERATE.

(iii). Copy the grant token displayed

Step 2: Generating the Access and Refresh Tokens

After obtaining the grant token, put the following code snippet in a java file and execute it from your main class to get access and refresh tokens.

ZCRMRestClient.initialize(configurations_map);

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);

2a. On using ZohoOAuthFilePersistence method

The access and refresh tokens are generated and stored in the oauth_tokens.properties file .

2b. On using ZohoOAuthDBPersistence method

The access and refresh tokens are generated and stored in " oauthtokens " table of your MySQL

Step 3: Generating the Access token from Refresh token

Use the below code snippet to generate the access token from the refresh token.

ZohoOAuthClient client = ZohoOAuthClient.getInstance();

client.generateAccessTokenFromRefreshToken(refreshToken, userMailId);

Sample SDK Code

When you build your application using the Java SDK, the code template will be similar to:

Refer to the attachment to get the code. For more sample codes, refer to our SDK guide .

The isTokenGenerated Method:

This method checks if the access token has already been generated or not. It returns a boolean value:

true - The access token has already been generated.

false - The access token has not been generated previously, thus, it shifts the control to the code snippet that leads to access token generation.

See you next week with another post.

Cheers!

Previous 'Kaizen' - Notification API

Next 'Kaizen' - Python SDK

Zoho Developer Community

New to Zoho LandingPage?

Access Zoho LandingPage

Zoho LandingPage Resources

New to Zoho Survey?

Access Zoho Survey

Latest Feature Updates

Explore our Pricing & Plans

Zoho Survey Resources

Android Mobile Surveys

Insurvey Blogs

Insight Blogs

Tips & Tricks

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Bigin?

Signup Now

Access Bigin

Latest Feature Updates

Zoho Desk Resources

Desk Community Learning Series
Digest
Functions
Meetups
Kbase
Resources
Glossary
Desk Marketplace
MVP Corner
Word of the Day

Tout forum

France ZUGs

Zoho SalesIQ Resources

Sticky Posts
Extension pointers for integrating Zoho CRM with Zoho products #8: Upload and manage Zoho Workdrive folders and files from within Zoho CRM
Keeping records on your customers and business prospects is essential for tracking data, conducting follow-ups, and running a business smoothly. When you use two separate applications, and store relevant data in each, checking and tracking data becomes
Extension pointers: Handle cases with personalized solutions using custom actions
In our last post, we detailed the steps involved in creating a custom action and the workflow from the developer and end user's side. Now let's look at a working example of how we can create a custom action and implement it in a Zoho CRM account to make
Extension pointers - Simple yet significant pointers #13: On change of field value for CRM variables
CRM variables provide global access to a variable across an entire extension. They also help in the storage of user-specific data provided by the user at the time of installation, which can later be fetched to perform data functionalities. Additionally,
Extension pointers: Extend end-user benefits and allow personalization by implementing extensions with custom actions
From our earlier post on custom actions, we know that we can create templated actions, share them with end users, and allow them to reuse those actions to achieve personalized outcomes. In this post, we'll look at how custom actions make it easy for users
Extension pointers - Simple yet significant pointers #12: Functions for Zoho CRM extensions
Functions are essential in achieving logical functionality for an extension. You can easily code your functions in Deluge using drag-and-drop tools to meet your requirements. How to create functions for Zoho CRM extensions in Sigma Go to Sigma and select