Kaizen #130 - Zoho CRM Scala SDK (V6) - Configuration and Initialization

Kaizen #130 - Zoho CRM Scala SDK (V6) - Configuration and Initialization

Hello and welcome to another Kaizen week!

In this week's post, we'll show you how to get started with Zoho CRM's Scala SDK, and walk you through the configuration and initialization process. Specifically, we will  discuss how to use the Scala SDK to make API calls authenticated via self-client. Please note that this article holds true for Scala SDK supporting version 6 of Zoho CRM APIs.

Software Development Kits (SDKs) are sets of tools and libraries designed to simplify the development process, and the integration between applications and specific platforms or services. They provide pre-built functionalities and abstract complex tasks, facilitating easier and faster development process. Zoho CRM's Scala SDKs act as a wrapper  for the REST APIs, thus making it easier to use the services of Zoho CRM.

Simplified Authentication using Scala SDK

Authentication with Zoho CRM APIs is facilitated by the OAuth 2.0 protocol, ensuring secure access to its resources. The process begins with the generation of a grant token for your organization in the Zoho Developer Console, where you specify the required scopes. Subsequently, using this grant token, you can generate both the access token, used for API call authentication, and the refresh token, employed for refreshing the access tokens after their one-hour expiry period. You must persist these tokens, along with their expiry times, in your server's data store for seamless API access. 

However, with the Scala SDK, this authentication process is significantly simplified. After generating the grant token and initialization, the SDK takes care of the rest. The SDK handles token generation, persistence, and refreshing the access token automatically, ensuring access to the resources without manual intervention.

Using the Zoho CRM Scala SDK

Before diving into the usage of Scala SDKs, ensure that the following prerequisites are met:
  • Ensure that the client app has Java version 11 or above.
  • Ensure that the client app has Scala version 2.13.5 or above.
  • Have an IDE such as IntelliJ installed.
  • An active Zoho CRM account.

1. Register your application with Zoho CRM

When you register a client with Zoho CRM, you establish a connection between your application and Zoho CRM, enabling your application to securely access and interact with Zoho CRM APIs and resources after authentication. The registration process involves providing essential details such as the client type, homepage URL, and authorized redirect URIs, depending on the type of client you choose.

To register your client:
  1. Go to the Zoho Developer Console
  2. Click on Get Started or +ADD CLIENT
  3. Choose the Client Type as Self-Client or Server based Applications depending on your application. Read our Kaizen post on the different client types to understand better. For this article, we will proceed with Self-client as we aim to develop a Scala application for our own use.
  4. Fill in the necessary details and click CREATE to register your client successfully. This will provide you with a Client ID and Client Secret.

2. Create a Scala project in your preferred IDE

If you already have your project set up, you may skip this step. However, if you are starting out, the next crucial step is to create a Scala Project in your preferred IDE. For the purpose of this guide, we will be using IntelliJ IDEA as the IDE of choice. 

3. Include the Zoho CRM Scala SDK in your project

To include the Zoho CRM Scala SDK in your project, you can follow different methods as outlined here.  However, for the purpose of this guide, we will demonstrate how to include the SDK using the build.sbt file.

Follow these steps to include the Zoho CRM Scala SDK in your project using the build.sbt file:
  1. Open your project in IntelliJ IDEA or your preferred IDE.
  2. Locate the build.sbt file in your project directory.
  3. Add the Zoho CRM Scala SDK dependency to your build.sbt file. To add the latest version (supporting version 6 of Zoho CRM APIs), include this line in the file  and Save: libraryDependencies ++= Seq( "com.zoho.crm" % "zohocrmsdk-6-0" % "2.0.0")
  4. Sync the changes and reload the files to ensure that the SDK has been added to the project.
Please note that when you install the Zoho CRM SDK, there are many dependencies which will also be installed. These dependencies are necessary for the proper functioning of the SDK and will be automatically managed by your build tool (such as sbt) during the installation process.


4. Obtain the grant token to authenticate your client

To make API calls, you need to authenticate your client by generating a grant token with the required scopes. For this guide, we will be using the self-client created in the first step. 
Log in to the Zoho Developer Console, and generate the grant token with the required scopes. Please note that this grant token has a short life span, and that it is used to generate the access and refresh tokens. Refer to our Kaizen on OAuth2.0 for more details.


5. Configuration and Initialization of the SDK

The configuration step in initializing the SDK involves setting up various objects to define how the SDK operates. This includes specifying the domain for API calls, token persistence, error logging, resource information storage, and more.

Before going into the specifics of various configurations, let us first discuss Token Persistence. Token Persistence refers to the mechanism through which access tokens and refresh tokens obtained during authentication are stored and managed by the SDK.  By storing tokens securely, the SDK can automatically manage token expiration and renewal, eliminating the need for manual token handling by the developer.For details on the different persistence methods supported by our SDKs, please refer to the last section of this post. In this guide, we will be using File Persistence as the method for Token Persistence. However, please note that users must choose the method that best suits their requirements and preferences.

Here is a sample code to initialize the SDK. Make sure to replace the client ID, client secret, grantToken, file paths, and other configurations with your specific values. 
  1. import com.zoho.api.authenticator.OAuthToken
  2. import com.zoho.crm.api.dc.USDataCenter
  3. import com.zoho.crm.api.exception.SDKException
  4. import com.zoho.crm.api.{HeaderMap, Initializer, SDKConfig}
  5. import com.zoho.api.logger.Logger
  6. import com.zoho.api.authenticator.store.FileStore

  8. object BulkWrite {
  9.   @throws[SDKException]
  10.   def main(args: Array[String]): Unit = {
  11.     val environment = USDataCenter.PRODUCTION
  12.     val token = new OAuthToken.Builder().clientID("1000.xxx").clientSecret("xxx").grantToken( "1000.xxx").findUser(false).build()
  13.     //Object containing the absolute file path to store tokens
  14.     var tokenstore = new FileStore("/Documents/SDK-Projects/Scala-SDK/ScalaSample/sdk_tokens_new.txt")
  15.     var logger = new Logger.Builder()
  16.       .level(Logger.Levels.ALL)
  17.       .filePath("/Documents/SDK-Projects/Scala-SDK/ScalaSample/scala_sdk_log.log")
  18.       .build
  19.     var sdkConfig = new SDKConfig.Builder().pickListValidation(false).autoRefreshFields(false).connectionTimeout(1000).requestTimeout(1000).socketTimeout(1000).build
  20.     new Initializer.Builder().environment(environment).token(token).store(tokenstore).logger(logger).SDKConfig(sdkConfig).initialize()
  21.   }
  22. }
  23. class BulkWrite {}

During the initialization step, the following configuration details have to be defined to configure the  behavior and functionality of the SDK. While two of them are mandatory, the others are optional.
  1. environment (mandatory): It determines the API environment, which dictates the domain and URL for making API calls. The format follows the Domain.Environment pattern.
    eg : val env = USDataCenter.PRODUCTION
  2. token (mandatory) : Contains the user token details. Create an instance of OAuthToken with the details that you get after registering your Zoho client. Depending on the available tokens, you can select one of the following flows:
    1. Grant Token Flow: Involves storing and persisting the grant token. This flow is used when you have a grant token available. The SDK will generate and persist the access and refresh tokens, and also refresh the access token upon expiry.
    2. Refresh Token Flow: Involves storing and persisting the refresh token. This flow is used when you have a refresh token available. The SDK will generate and persist the access and refresh tokens, and also refresh the access token upon expiry.
    3. Access Token Flow: In this flow, the access token is directly utilized for API calls without token persistence. The SDK will persist the access token, but upon expiry it won't be refreshed, and an INVALID_TOKEN error will be thrown once the access token has expired.
    4. Id FLow : You can use the id from the persisted token file/DB to make API calls. The id is a unique system generated value for each token details entry in the file/DB. Please note that you can use this method only after the SDK has already been initialized.
  3. logger (optional) : You can customize the logging behavior by setting the desired log level, which can be one of the following: FATAL, ERROR, WARNING, INFO, DEBUG, TRACE, ALL, or OFF. Additionally, you can configure the file path and file name for the log file.
  4. store (optional) : Allows you to configure token persistence for your application. If this is skipped, the SDK will create the "sdk_tokens.txt" file in the current working directory by default to persist the tokens. 

    Database Persistence
    File Persistence
    Custom Persistence
    var tokenstore = new DBStore.Builder()
      .host("hostName")
      .databaseName("databaseName")
      .tableName("tableName")
      .userName("userName")
      .password("password")
      .portNumber("portNumber")
      .build
    var tokenstore = new FileStore("/Users/user_name/Documents/scala_sdk_token.txt")
    var tokenStore = new CustomStore()

  5. SDKConfig (optional) : This method takes care of additional SDK configurations.

    Configuration Key
    Description
    autoRefreshFields
    Default Value : False
    A boolean configuration field to enable or disable automatic refreshing of module fields in the background. If set to true, fields are refreshed every hour, and if set to false, fields must be manually refreshed or deleted.
    pickListValidation
    Default Value : True
    This field enables or disables pick list validation. If enabled, user input for pick list fields is validated, and if the value does not exist in the pick list, the SDK throws an error. If disabled, the input is not validated and the API call is made.
    enableSSLVerification
    Default Value : True
    A boolean field to enable or disable curl certificate verification. If set to true, the SDK verifies the authenticity of certificate. If set to false, the SDK skips the verification.
    connectionTimeout
    Default Value : 0
    The maximum time (in seconds) to wait while trying to connect. Use 0 to wait indefinitely.
    timeout
    Default Value : 0
    The maximum time (in seconds) to allow cURL functions to execute. Use 0 to wait indefinitely.

  6. requestProxy (optional) : Configure this only if you're using a proxy server to make the API calls. To configure, create an instance of RequestProxy containing the proxy properties of the user.

    var requestProxy = new RequestProxy.Builder()
      .host("proxyHost")
      .port(80)
      .user("proxyUser")
      .password("password")
      .userDomain("userDomain")
      .build()

  7. resourcePath (optional) : To configure the absolute directory path to store user-specific files containing module fields information. If this object is skipped, the files will be stored in the project directory itself.
Once the initialization is successful, you can verify that the access and refresh tokens are generated and persisted. You can do this by checking the tokens file or the database, depending on the token persistence method you configured during initialization.


Token Persistence

There are three token persistence methods supported by our SDKs. 
  1. Token Persistence using a Database : In Database persistence, tokens are stored and retrieved from a database (e.g., MySQL). In this case, you should create a table in your database with the required columns. The custom database name and table name can be set in DBStore instance, when you initialise the SDK.
    For instance, to persist your tokens in a table named token in database named zoho in your mySQL DB, use this:

    CREATE DATABASE zoho; // use this to create database named zoho
    // use this to create a table named token, with the following necessary columns
    CREATE TABLE token ( 
      id varchar(10) NOT NULL,
      user_name varchar(255) NOT NULL,
      client_id varchar(255),
      client_secret varchar(255),
      refresh_token varchar(255),
      access_token varchar(255),
      grant_token varchar(255),
      expiry_time varchar(20),
      redirect_url varchar(255),
      api_domain varchar(255),
      primary key (id)
    );

  2. File Persistence : This method allows storing and retrieving the authentication tokens from the file in the file path that you configure. The file will contain the id, user_name, client_id, client_secret, refresh_token, access_token, grant_token, expiry_time, redirect_url, and api_domain.
  3. Custom Persistence : This is a method where users can create their own method of storing and retrieving authentication tokens. To use this method, users need to implement the TokenStore interface and override its methods according to their own logic. For more details, please refer here.
We hope that you found this useful. In next week's Kaizen post, we will discuss about Bulk Write operations using the Scala SDK for Zoho CRM, and on how to import both parent and child records in a single operation.

If you have any queries, let us know the comments below, or send an email to support@zohocrm.com. We would love to hear from you. 


Cheers!
Anu Abraham



Recommended Reads:





    • Recent Topics

    • POSTMAN - There was an error in evaluating the Pre-request Script:Error: Cannot read properties of undefined (reading 'json')

      I am beginning the journey to learn how to use the API for Zoho Sign. I am getting the following error when I try to use postman. To walk you through how I am getting this error... I wanted to start with a simple GET and expand my learning from there.

    • How do i integrate shipstation with zoho inventory

      Wanting to set up my own delivery driver in ship station so we can get real time tracking of where the package is but then i want it to automatically update zoho inventory packages/shipments how can i do this

    • Invalid value passed for salesorder_id

      Hi, I am using sales return API, details are given below: API: https://inventory.zoho.com/api/v1/salesreturns?organization_id=700571811 Post Json Data: { "salesreturn_number": "", "date": "2020-11-12", "reason": "Testing from API", "line_items": [ { "item_id":

    • Create Invoice and Invoice Items from Sales Order via API

      Currently, when creating an Invoice associated with a Sales Order via the API, it appears that I must manually include all of the items (line_items) even though they are already part of the Sales Order. My question is this: is it possible to raise an Invoice via the API based on all of the information associated with a Sales Order--such as the  items? In other words, do I always have to manually include the items (line_items) when raising an Invoice via the API when the Invoice is associated with

    • Outlook 2013 Calendar Syncs but "Related To" Field in Zoho is blank

      Outlook 2013 Calendar Syncs but Related To Field in Zoho is blank I expect the "Realted To" field to be populated with the calendar participants

    • Export a Course

      Is it possible to export a course from Zoho Learn to a SCORM file?

    • Add and Remove Agents from Departments and Groups in Zoho One

      Hi Zoho Flow Team, We hope you're doing well. Currently, Zoho Flow provides an action to add an agent to a group in zoho one, but there is no action to remove an agent from a group or a department. Another action that we find missing is the option to

    • Zoho learn Custom portal - networkurl & CustomPortalId

      I want to get my individual account’s networkurl and customportalId to use in this API: https://learn.zoho.com/learn/api/v1/portal/<networkurl>/customportal/<customportalId>/manual How can I retrieve the networkurl and customportalId using the API? I

    • Consumer Financing

      Does Zoho currently have a payment gateway (such as Stripe, Square, etc) which offers financing for customers? So, let's say the estimate we give the customer is greater than what they can afford at the time, but we can sell the service now, letting them

    • Intégration de la gestion des Passkeys dans Zoho Vault

      Zoho Vault est depuis plus d’une décennie une solution fiable pour les entreprises : pour la gestion, le partage et le stockage des mots de passe. En 2018, nous avons fait un pas en avant en proposant la connexion unique (SSO). Nous sommes fiers de franchir

    • Scan & Fill with double quote key/value pairs

      Hi, An old Ticket moved to a Topic/Idea: I love the idea of the new Scan & Fill as it nearly covers my previous request for a QR Scanner to read a multi-part QR Code. My QR Codes are hard-coded as below: {"key1":"value1","key2":"value2","key3":"value3"}

    • Analytics SQL Queries should allow # as comment

      # and // are very common for commenting in SQL. Not sure why analytics only allows /* and */ for commenting. Especially when # grays the line as if it's being commented out. This should be added for sure.

    • SalesIQ Operator Activity Reports in Zoho Analytics

      I'm busy building a dashboard in Zoho Analytics and I want to include SalesIQ stats in the dashboard, but I'm unable to get the statistics mentioned in the attached image. Any idea where I can get the stats for Operator Activity?

    • Default in fields on Form B based on the user selection in Form A

      Hi Everyone, I have added an action button to a form report to bring up a new form based on user selection, see it indicated in red below: Then when the ne form loads, I want to default in some of the fields based on the record the user was selected on.

    • No longer can indent

      Hey there! Is it just me or were we used to be allowed to used tab or indent when writing. It’s not working right now, has this always been the case?

    • Free webinar alert! Seamless Transition with Lossless Migration: Zoho One + Zoho Mail

      Hello Zoho Mail Community! 🚀 Attention IT Admins and Email Administrators! Are you planning to migrate your organization's email to Zoho Mail within the Zoho One ecosystem? 📧 Join our exclusive webinar, Seamless Transition with Lossless Migration: Zoho

    • Add Resource to Export

      The Export Data feature does not include a column for the Resource field. Without this column, Zoho Bookings cannot be used by any business for resource-based services or event types e.g. room bookings, equipment bookings. It seems to be an oversight,

    • Client Script | Update - Client Script Support For Custom Buttons

      Hello everyone! We are excited to announce one of the most requested features - Client Script support for Custom Buttons. This enhancement lets you run custom logic on button actions, giving you greater flexibility and control over your user interactions.

    • Mandatory field via deluge code

      I would like to ask you if it is possible to make a field mandatory via deluge script. For example, if I have a decision box and I click on it then I want a single line field to be mandatory. If uncheck the decision box then to do the single line as optional. I think it is not possible to do that and I have to do it via validation in 'on validate' field. 

    • Revenue Management: #1 What does it mean to "recognize" revenue?

      Earning revenue isn't just about collecting cash from your customers. It's about recording the income correctly and consistently. Revenue recognition is the process of deciding when and how to record revenue in financial statements so that they reflect

    • Power of Automation :: Auto-Populate Integration Field in Projects with CRM Account Data

      Hello Everyone, A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automate

    • Zoho Forms and ChatGPT - populating a field using AI.

      I have a form where I would like the user to enter a response or query, and have another field populated using AI. For example, user enters Field 1, AI populates Field 2 in response. I want to be able to wrap some additional instruction text around the

    • campo tag para api

      debo conectarme a una api de zoho inventory y ocupo tomar el campo tag para poder asi jalar el articulo que cuente con el campo correcto en tag ejemplo que tag existen carro y avion que cuando busque los articulo con tag carro arroje solo estos por mas

    • Uploading file as attachment to Zoho CRM

             Hi,   I am trying to attach a file to a Zoho CRM contact using Zoho Flow. Right now, I try to do it through the “Upload File” field in Zoho CRM (In my screenshots, it’s called Téléchargement du fichier 1).   Here is what I tried:   Case 1: Webmerge document The Flow is called “Custom Function” (see screenshot 101).   Step  1: Creating a Webmerge document (screenshot 99)   Step 2: I use “Update module entry” to upload the created file. I upload Webmerge’s “Document” in my “Téléchargemet du

    • Zia Answer Bot - Create Ticket

      Surprisingly, the current iteration of Zia will try to answer a question and unless you have "transfer to SalesIQ chat" enabled, it won't create a ticket for the user or offer them a method to create a ticket. We don't want it to create chats for us,

    • meassure leads phases

      Hi, I need to create a table to meassure the time that a lead stay in blueprint phases. the phases are first contact, second contact, lead spam, contacted, appointment. any idea? I have attached an example

    • Zoho Desk API Documentation missing a required field

      We are trying to create a section using this information. Even after preparing everything based on that page, we still get an error. The error we get is this: {"errorCode":"INVALID_DATA","message":"The data is invalid due to validation restrictions","errors":[{"fieldName":"/translations","errorType":"missing","errorMessage":""}]}

    • In the Custom Module I have 500 Records , this 500 record only want to view to the specific user only example user A ,

      In the Custom Module, I have 500 Old records that should only be visible to a specific user, for example, User A. Any new records created from today onwards should be visible to Record owner in the Custom Module. Pls help how i achive this .

    • Invoice template, how to change the text under "Notes" and "Terms and Conditions"

      In "Invoice templates", there are two text/info sections at the bottom:"Notes" and "Terms and Conditions". It is possible to change the names of these two headings, but how is it possible to change/alter the text under it. As a standard it says "Thank you for your business" under Notes - I need to change it into something different- How? Thank you.

    • How to reply to thread via API

      We have built a webapp for our customers that uses the Zoho Desk API to enable each customer to view their full list of tickets, view individual tickets and raise new tickets. The Zoho Desk API doesn't have the ability to reply to a ticket/thread. Replies

    • Sending merged mail templates for signatures fail since today

      We have ZOHO one, we use merge templates in CRM to edit in ZOHO Writer, and from there send it for signature through zoho sign. This all worked up until today, suddenly we read in the log that the merge is succesfull but the sending for signature failed.

    • Feature Request - Make Lead List Larger and Adjustable

      Hi LandingPage team, I recently started using LandingPage and I am happy to share my feedback to help improve the app. I've noticed on the Leads page, there is no option to make the columns wider. It would be great if the comlumns expanded to fit the

    • Zoho Projects - Pin Recent Projects

      Hi Projects Team, It would be great if I could "pin" projects on the Recent Projects list in Zoho Projects. We have some internal projects which we regularly have to add time and some regular client projects. It would be great if I could pin those projects

    • ZDK Error

      I get this error when trying to trigger a CRM Function from Client Script: Uncaught (in promise) ZDKError: {"code":"NOT_ACTIVE","details":{"api_name":"activate_client_from_prospect"},"message":"api is inactive for the given custom function","status":"error"}

    • "Disbursing product components in phases, monitoring them, and displaying only the final product."

      i have a product composed of multiple components, and these components will be delivered to the customer in batches. However, the final invoice should only show the finished product. How can I issue (or release) the components and track their delive

    • Followed Subtasks doesn't show up in the Subtasks Section

      I have a task assigned to me now in the same task, there's a subtask and I am added as the follower on that task Even though I am a follower I still don't see that in the subtasks section The view permission for the profile is Related It's supposed to

    • Tip #39- Strengthen account security with Multi-factor Authentication (MFA) – ‘Insider Insights’

      Securing your organization's data begins with verifying that only the correct individuals have access to it. One of the simplest yet most effective ways to accomplish this is to enable Multi-factor Authentication (MFA) within Zoho Assist. MFA introduces

    • Automate timeout chat tracking with Workflows in SalesIQ

      With our feature-packed Nova release, Workflows has become one of the most powerful tools in Zoho SalesIQ. They let you automate follow-up actions when key events occur, such as when a chat ends, a visitor leaves a bad/good rating, or a lead is updated.

    • Mass edit / Mass update products

      Hi, Is there any way to mass update or bulk edit product fields in Zoho Inventory?

    • Automatic Verification of IMAP Integration Status

      Our sales staff have their O365 email integrated with CRM, over time this integration requires re-authentication via the UI. I can manually check the integration status by accessing Settings -> Channels -> Email -> Email Sharing -> "Configuration Type"

    • Next Page