Kaizen #18 - Ruby SDK

Kaizen #18 - Ruby SDK

Hello everyone!
Welcome back to another week of Kaizen!
This week, we will discuss the Ruby SDK.

What is the Ruby SDK for Zoho CRM?

Ruby SDK allows you to create client Ruby applications that you can integrate 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 the SDK acts as a middle ware between Zoho CRM and a client Ruby Application.


What can you do with the Ruby SDK?
  • Exchange data between Zoho CRM and the client application where the CRM entities are modeled as classes.
  • Authenticate your application easily every time you sync data between Zoho CRM and your application, as the SDK takes care of generating the access/refresh tokens automatically.
Environment Setup
The client app must have the Ruby version 2.3.7 or above installed. Refer to Ruby Installation for the steps to install Ruby.

How to Start using the Ruby SDK?
Follow the below steps:
  • Step-1: Register your application (Self Client or Web-based client)
  • Step-2: Install the SDK
  • Step-3: Initialize the SDK
    3.a. Choose the token persistence method
    3.b. Set up the configuration dictionary
    3.c. Generate the tokens
  • Step-4: Connect to Zoho CRM through the available methods
Let us now discuss these steps in detail.

Step-1: Register your application

All the Zoho CRM APIs are authenticated by the OAuth2.0 standards. It is mandatory to authenticate your application with Zoho.
You can register your application either as a Self Client (single user app) or a web-based app (multiple users app).
1.a. Self Client
  1. Go to https://api-console.zoho.com.
  2. Click ADD CLIENT.
  3. Choose the Client Type as Self Client, and click CREATE.
  4. You will receive a client ID and a client secret upon successful registration.
1.b. Web-based Client
  1. Go to https://api-console.zoho.com.
  2. Click ADD CLIENT.
  3. Choose the client as Web based and click CREATE NOW.
  4. Specify the client name, homepage URL of your application's UI, and a redirect URI to which you want to redirect the users after they grant consent to your application.
  5. Click CREATE.

  6. Your Client ID and Client Secret will be displayed.
Step-2: Install the SDK

The Ruby SDK is available as a gem. 
Run the below command to install the Ruby SDK for Zoho CRM.

gem install ZCRMSDK

Step-3: Initialize the SDK 

Initializing the SDK involves the following steps.

  • Step 3.a - Choosing the token persistence method
  • Step 3.b - Setting up the configuration dictionary
  • Step 3.c - Generating the tokens

3.a. Token Persistence
Your application should retain tokens (grant, access, and refresh tokens) to automate the process of data transfer between your Ruby application and Zoho CRM.

You can persist (store) the tokens in three ways.
a. MySQL Persistence (default)
b. File Persistence
c. Custom DB Persistence

a. MySQL Persistence
When you want to store the tokens in the MySQL DB, ensure that MySQL2 is installed.
Run the below command to install MySQL2.

gem install mysql2 -v 0.5.2

For this type of persistence, you must include the following keys in the configuration dictionary (discussed in the next section), along with other mandatory keys.

"mysql_username":"root",
"mysql_password":"*****",
"mysql_port":"port_number"

Note
When you use MySQL persistence, ensure that
  • MySQL runs in the same machine serving at the mentioned port. (by default 3306).
  • There is a database named zohooauth.
  • There is a table name oauthtokens with the columns useridentifier (varchar(100)), accesstoken (varchar(100)), refreshtoken (varchar(100)) and expirytime (bigint).

b. File Persistence
If you want to store the tokens in a file, you can create a file named zcrm_oauthtokens.txt and provide the absolute path of the folder containing this file in the below key of the configuration array.

"token_persistence_path":"path_to_the_folder_containing_the_txt_file"

If you do not create this file, the SDK itself creates this file in the path you have specified, and persists the token there.
Note: This method is recommended only for self client apps.

c. Custom DB Persistence
To use this method, you need to provide the following keys in the configuration dictionary.

"persistence_handler_class_path":"absolute path to the custom DB implementation"
"persistence_handler_class":"class name of the custom implementation".

You can use the inbuilt ZohoPersistenceHandler interface and include the following custom functions.

  • saveOAuthData(ZohoOAuthTokens tokens)
  • deleteOAuthTokens($userEmailId)
  • getOAuthTokens($userEmailId)
Note
The order of precedence for token persistence is custom, file, and DB persistence. That is, if you provide the details for custom persistence (in persistence_handler_class_path) and file persistence details (in token_persistence_path), then custom persistence is given priority over file.

3.b. Configuration dictionary
The below tables contains the list of keys you must include in the configuration dictionary based on the type of persistence.

Mandatory Keys

File Persistence
MySQL Persistence
Custom DB Persistence
client_id
client_id
client_id
client_secret
client_secret
client_secret
redirect_uri
redirect_uri
redirect_uri
token_persistence_path
db_username
persistence_handler_class
-
db_password
persistence_handler_class_path
-
db_port
-
current_user_email
current_user_email
current_user_email

Optional Keys

File Persistence
MySQL Persistence
Custom DB Persistence
application_log_file_path
application_log_file_path
application_log_file_path
log_in_console
log_in_console
log_in_console
sandbox
sandbox
sandbox
access_type
access_type
access_type
accounts_url
accounts_url
accounts_url
api_base_url
api_base_url
api_base_url
api_version
api_version
api_version

Where,
  • client_id, client_secret, and redirect_uri - Client details you received after registering your application. For self client apps, you can pass a dummy value for the redirect uri.
  • token_persistence_path - The relative path to store the OAuth tokens in the zcrm_oauthtokens.txt file. This key is mandatory if you want to use file persistence.
  • db_username, db_password, db_port - The MySQL username, password, and the port, respectively.
  • persistence_handler_class - Name of the class of the custom implementation for persistence. This key is mandatory if you want to use custom persistence.
  • persistence_handler_class_path - The absolute path to the custom DB implementation (.rb file).
  • application_log_file_path - The absolute path to log the exceptions during the usage of the SDK.
  • log_in_console - To print the exceptions on the console screen, when set as "true".
  • sandbox - Boolean key to make API calls to the sandbox environment. The value true makes API calls to the sandbox. Default value is false.
  • access_type - Must be set as offline as the SDK does not support online OAuth client, now.
  • accounts_url - The domain-specific accounts URL from which you generate the tokens.
    This key is mandatory when the user is not in the "com" domain.
    For US:
    https://accounts.zoho.com
    For EU:
    https://accounts.zoho.eu
    For CN:
    https://accounts.zoho.com.cn
    For IN:
    https://accounts.zoho.in
  • api_base_url - The domain-specific API URL from which you make API calls. For users from domains other than the US, this key is mandatory.
    For US:
    https://www.zohoapis.com
    For EU:
    https://www.zohoapis.eu
    For CN:
    https://www.zohoapis.com.cn
    For IN:
    https://www.zohoapis.in
  • api_version - Represents the version of the CRM APIs. The value is v2.
  • current_user_email - The email ID of the current user. You must set this either in the configuration array or ZCRMSDK::RestClient::ZCRMRestClient.current_user_email = "current user email id".

Below is a configuration dictionary with all the keys. 

config_details = { 'client_id' => 'xxxxx', #mandatory
'client_secret' => 'xxxxxx', #mandatory
'redirect_uri' => 'https://www.zoho.com', #mandatory
'api_base_url' => 'https://www.zohoapis.com', #optional, default is https://www.zohoapis.com
'accounts_url' => 'https://accounts.zoho.com', #optional, default is https://accounts.zoho.com
'current_user_email' => 'abc@xyz.com', #mandatory (should be either set in config array or ZCRMSDK::RestClient::ZCRMRestClient.current_user_email = "current user email id" )
'api_version' => 'v2', #optional,default is v2
'sandbox' => 'false', #optional default is sandbox
'application_log_file_path' => "/Users/xxxx/Desktop/log.log", #optional, absolute path of log file
'log_in_console' => 'true', #optional default is false, to log on the console
'persistence_handler_class_path' => 'absolute/path/to/customClass.ruby', #absolute path to the custom db implementation
'persistence_handler_class' =>'classname', #name of the class
'token_persistence_path'=>'relativepath/to/zcrm_oauthtokens.txt', #for file persistence
'db_username' => 'username', #optional, default root
'db_password' => 'password', #optional, default ''
'db_port' => 'port_number', #optional, default 3306
}

Now that you have created and registered your app with Zoho, you must authenticate it. 
Pass the configuration dictionary in the method ZCRMRestClient.init(config) and authenticate your app.

3.c. Generating the tokens

As the V2 Zoho CRM APIs follow the OAuth2.0 protocol, it is mandatory to authorize the OAuth2.0 app before using the SDK functions.
You can generate an access token from a grant token.
You can generate the grant token in two ways based on the type of client.

For Self Client Applications
  • Go to Zoho Developer Console.
  • Select your Self Client.
  • Provide the necessary scopes separated by commas, along with the scope aaaserver.profile.READ.
  • Select the Time Duration from the drop-down. This is the time the grant token is valid for.
  • Provide a description for the scopes. Click GENERATE.
  • Copy the grant token.

For Web-based Applications

It is the responsibility of your client app to generate the grant token for the users trying to login.
Your Application's UI must have the Login with Zoho option to open the grant token URL of Zoho, which would prompt for the user's OAuth2.0 authorization.
Upon the successful login of the user, the grant token will be sent as a parameter to your registered redirect URL.

Generating an access token from the grant token
Use the below code snippet in your main class.

client = ZCRMSDK::OAuthClient::ZohoOAuth.get_client_instance
grant_token = 'grant_token'
client.generate_access_token(grant_token)
Note
  • The code snippet to generate the access token from the grant token is valid only once per grant token. If the grant token expires before you generate the access token, you must generate a new grant token only.
  • Generating access and refresh tokens is a one-time process. After the tokens are generated the first time, the SDK persists them based on the keys defined in the configuration dictionary, and refreshes the access token as and when required.

Step-4: Connect to Zoho CRM through the available methods
Here is a sample to get a specific user's details. You can find the code for this sample in the attachment.


The isTokenGenerated Method

def self.is_token_generate(user)
    tokens = ZCRMSDK::OAuthClient::ZohoOauth.get_persistence_instance.get_oauth_tokens(user)
    unless tokens.nil?
        return true
    end
    rescue Exception => e
        return false 
  end
You need to add this method to check 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.
For more sample codes, refer to our SDK guide.
We hope you found this post useful. Stay tuned for more!

Cheers!




    Access your files securely from anywhere







                            Zoho Developer Community





                                                  Use cases

                                                  Make the most of Zoho Desk with the use cases.

                                                   
                                                    

                                                  eBooks

                                                  Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho Desk.

                                                   
                                                    

                                                  Videos

                                                  Watch comprehensive videos on features and other important topics that will help you master Zoho Desk.

                                                   
                                                    

                                                  Webinar

                                                  Sign up for our webinars and learn the Zoho Desk basics, from customization to automation and more

                                                   
                                                    
                                                  • Desk Community Learning Series


                                                  • Meetups


                                                  • Ask the Experts


                                                  • Kbase


                                                  • Resources


                                                  • Glossary


                                                  • Desk Marketplace


                                                  • MVP Corner




                                                            • Sticky Posts

                                                            • Kaizen #197: Frequently Asked Questions on GraphQL APIs

                                                              🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.
                                                            • Kaizen #198: Using Client Script for Custom Validation in Blueprint

                                                              Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.
                                                            • Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

                                                              Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs
                                                            • Kaizen #193: Creating different fields in Zoho CRM through API

                                                              🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.
                                                            • Client Script | Update - Introducing Commands in Client Script!

                                                              Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands


                                                            Manage your brands on social media



                                                                  Zoho TeamInbox Resources



                                                                      Zoho CRM Plus Resources

                                                                        Zoho Books Resources


                                                                          Zoho Subscriptions Resources

                                                                            Zoho Projects Resources


                                                                              Zoho Sprints Resources


                                                                                Qntrl Resources


                                                                                  Zoho Creator Resources



                                                                                      Zoho CRM Resources

                                                                                      • CRM Community Learning Series

                                                                                        CRM Community Learning Series


                                                                                      • Kaizen

                                                                                        Kaizen

                                                                                      • Functions

                                                                                        Functions

                                                                                      • Meetups

                                                                                        Meetups

                                                                                      • Kbase

                                                                                        Kbase

                                                                                      • Resources

                                                                                        Resources

                                                                                      • Digest

                                                                                        Digest

                                                                                      • CRM Marketplace

                                                                                        CRM Marketplace

                                                                                      • MVP Corner

                                                                                        MVP Corner






                                                                                          Design. Discuss. Deliver.

                                                                                          Create visually engaging stories with Zoho Show.

                                                                                          Get Started Now


                                                                                            Zoho Show Resources


                                                                                              Zoho Writer Writer

                                                                                              Get Started. Write Away!

                                                                                              Writer is a powerful online word processor, designed for collaborative work.

                                                                                                Zoho CRM コンテンツ








                                                                                                  Nederlandse Hulpbronnen


                                                                                                      ご検討中の方




                                                                                                            • Recent Topics

                                                                                                            • Zoho Social - Post Footer Templates

                                                                                                              As a content creator I often want to include some information at the end of most posts. It would be great if there was an option to add pre-written footers, similar to the Hashtag Groups at the end of posts. For example, if there is an offer I'm running
                                                                                                            • Zoho Expense - The ability to add detail to a Trip during booking

                                                                                                              As an admin, I would like the ability to add more detail to the approved Trips. At present a requestor can add flights, accommodation details and suggest their preferences. It would be great if the exact details of the trip could be added either by the
                                                                                                            • Simplified Call Logging

                                                                                                              Our organization would like to start logging calls in our CRM; however, with 13 fields that can't be removed, our team is finding it extremely cumbersome. For our use case, we only need to record that a call happened theirfor would only need the following
                                                                                                            • Help Center IFrame Issue

                                                                                                              I have had a working Help Center on my website using an iframe for a while. But now for some reason the sign in page gets a refused to connect error. Can someone please help. If I go to the url manually it works correclty
                                                                                                            • Staff rules

                                                                                                              Hi! Do you people know what are the default staff rules when a new booking is created? We have two staff members in my team (me as the admin, and my employee). As we share the same services, I'm wondering how Zoho will pick the staff for new apointments.
                                                                                                            • Comment Templates

                                                                                                              Is it possible to add a template option for comments? We have some agents in the process who's responses require a pre-formatted layout. It would be incredibly handy to have a template for them where they can insert the template and then add their responses
                                                                                                            • [ZohoDesk] Improve Status View with a new editeble kanban view

                                                                                                              A kanban view with more information about the ticket and the contact who created the ticket would be valueble. I would like to edit the fields with the ones i like to see at one glance. Like in CRM where you can edit the canvas view, i would like to edit
                                                                                                            • Adding Markdown text using Zoho Desk API into the Knowledge Base

                                                                                                              Hi Zoho Community members, We currently maintain the documentation of out company in its website. This documentation is written in markdown text format and we would like to add it in Zoho Knowledge Base. Do you know if there is REST API functionality
                                                                                                            • An Exclusive Session for Zoho Desk Users: AI in Zoho Desk

                                                                                                              A Zoho Community Learning Initiative Hello everyone! This is an announcement for Zoho Desk users and anyone exploring Zoho Desk. With every nook and corner buzzing, "AI's here, AI's there," it's the right time for us to take a closer look at how the AI
                                                                                                            • Shared values: From classroom lessons to teaching moments in customer service

                                                                                                              While the world observes Teachers’ Day on October 5, in India, we celebrate a month earlier, on September 5, to mark the birth anniversary of Dr. Sarvepalli Radhakrishnan, a great teacher, renowned scholar, educationist, and advocate for empowerment.
                                                                                                            • Export to excel stored amounts as text instead of numbers or accounting

                                                                                                              Good Afternoon, We have a quarterly billing report that we generate from our Requests. It exports to excel. However if we need to add a formula (something as simple as a sum of the column), it doesn't read the dollar amounts because the export stores
                                                                                                            • Auto Capitalize First Letter of Words

                                                                                                              Hi I am completely new to ZOHO and am trying to build a database. How can i make it when a address is entered into a form field like this: main st it automatically changes is to show: Main St Thank You
                                                                                                            • Follow-up emails via Workflow Automation not staying in the same thread

                                                                                                              Dear Zoho Support Team, I am currently using Workflow Automation in Zoho Campaigns to send follow-up emails. In my test case, I noticed the following behavior: All emails in the automation have the same subject line. If the follow-up email is sent within
                                                                                                            • Update application by uploading an updated DS file

                                                                                                              Is it possible? I have been working with AI on my desktop improving my application, and I have to keep copy pasting stuff... Would it be possible to import the DS file on top of an existing application to update the app accordingly?
                                                                                                            • Send / Send & Close keyboard shortcuts

                                                                                                              Hello! My team is so close to using Zoho Desk with just the keyboard. Keyboard shortcuts really help us to be more efficient -- saving a second or two over thousands of tickets adds up quickly. It seems like the keyboard shortcuts in Desk are only for
                                                                                                            • Image Upload Field | Zoho Canvas

                                                                                                              I'm working on making a custom view for one of our team's modules. It's an image upload field (Placement Photo) that would allow our sales reps to upload a picture of the house their working on. However, I don't see that field as a opinion when building
                                                                                                            • Create a list of customers who participated in specific Zoho Backstage events and send them an email via Zoho CRM

                                                                                                              How to create a list of customers who participated in specific Zoho Backstage events and send them an email via Zoho CRM? I was able to do a view in CRM based on customer that registered to an event, but I don't seems to be able to include the filter
                                                                                                            • Custom Button Disappearing in mobile view | Zoho CRM Canvas

                                                                                                              I'm working in Zoho CRM Canvas to create a custom view for our sales team. One of the features I'm adding is a custom button that opens the leads address in another tab. I've had no issue with this in the desktop view, but in the mobile view the button
                                                                                                            • Zoho Desk blank page

                                                                                                              1. Click Access zoho desk on https://www.zoho.com/desk/ 2. It redirects to https://desk.zoho.com/agent?action=CreatePortal and the page is blank. Edge browser Version 131.0.2903.112 (Official build) (arm64) on MacOS
                                                                                                            • Clearing Fields using MACROS?

                                                                                                              How would I go about clearing a follow-up field date from my deals? Currently I cannot set the new value as an empty box.
                                                                                                            • I hate the new user UI with the bar on the left

                                                                                                              How can I reverse this?
                                                                                                            • Office 365 and CRM mail integration: permission required

                                                                                                              Has anyone run into this weird problem? My email server is Office 365. When I try to configure Zoho CRM to use this server, a Microsoft popup window opens requesting user and password. After entering that, I get a message in the Microsoft window saying
                                                                                                            • Field Not Updating in FSM Script - Service and Parts module.

                                                                                                              Dear Team, I am reaching out regarding a script I have implemented in Zoho FSM to automate the calculation of the End of Service date based on the End of Sale date in the Service and Parts module. Overview of the script: Fetches the End_of_Sale__C and
                                                                                                            • Question regarding import of previous deals...

                                                                                                              Good afternoon, I'm working on importing some older deal records from an external sheet into the CRM; however, when I manually click "Add New Deal" and enter the pertinent information, the deal isn't appearing when I look at the "Deals" bar on the account's
                                                                                                            • Client Script also planned for Zoho Desk?

                                                                                                              Hello there, I modified something in Zoho CRM the other day and was amazed at the possibilities offered by the "Client Script" feature in conjunction with the ZDK. You can lock any fields on the screen, edit them, you can react to various events (field
                                                                                                            • One person/cell phone to manage multiple accounts

                                                                                                              Hi. I have a personal Free account to keep my own domain/emails. Now I need to create a Business account to my company's own domain, but I have only one mobile phone number I use to everything. How do I do to manage this? Can I manage a Free domain and
                                                                                                            • Tracking KPIs, Goals etc in People

                                                                                                              How are Zoho People users tracking employee targets in People? For example, my marketing assistant has a target of "Collect 10 new customer testimonials every month". I want to record attainment for this target on a monthly basis, then add it to their
                                                                                                            • Zoho Desk: Ticket Owner Agents vs Teams

                                                                                                              Hi Zoho, We would like to explore the possibility of hiding the ‘Agents’ section within the Ticket Owner dropdown, so that we can fully utilise the ‘Teams’ dropdown when assigning tickets. This request comes from the fact that only certain agents and
                                                                                                            • CRM limit reached: only 2 subforms can be created

                                                                                                              we recently stumbled upon a limit of 2 subforms per module. while we found a workaround on this occasion, only 2 subforms can be quite limiting in an enterprise setting. @Ishwarya SG I've read about imminent increase of other components (e.
                                                                                                            • Can not Use Attachment Button on Android Widget

                                                                                                              this always pops up when I touch the attach button on android widget. going to settings, there is no storage permission to be enabled. if I open the app, and access the attach feature there, I can access my storage and upload normally.
                                                                                                            • How do I filter contacts by account parameters?

                                                                                                              Need to filter a contact view according to account parameter, eg account type. Without this filter users are overwhelmed with irrelevant contacts. Workaround is to create a custom 'Contact Type' field but this unbearable duplicity as the information already
                                                                                                            • Can I add Conditional merge tags on my Templates?

                                                                                                              Hi I was wondering if I can use Conditional Mail Merge tags inside my Email templates/Quotes etc within the CRM? In spanish and in our business we use gender and academic degree salutations , ie: Dr., Dra., Sr., Srta., so the beginning of an email / letter
                                                                                                            • Zoho Notebook Sync problem

                                                                                                              I'm facing a problem with syncing of notebook on android app. It's not syncing. Sometimes it syncs after a day or two.  I created some notes on web notebook but it's not syncing on mobile app. Please help!!!!
                                                                                                            • Kaizen #190 - Queries in Custom Related Lists

                                                                                                              Hello everyone! Welcome back to another week of Kaizen! This week, we will discuss yet another interesting enhancement to Queries. As you all know, Queries allow you to dynamically retrieve data from CRM as well as third-party services directly within
                                                                                                            • Custom Fonts in Zoho CRM Template Builder

                                                                                                              Hi, I am currently creating a new template for our quotes using the Zoho CRM template builder. However, I noticed that there is no option to add custom fonts to the template builder. It would greatly enhance the flexibility and branding capabilities if
                                                                                                            • Announcing new features in Trident for Mac (1.24.0)

                                                                                                              Hello everyone! Trident for macOS (v.1.24.0) is here with interesting features and thoughtful enhancements to redefine the way you plan and manage your calendar events. Here's a quick look at what's new. Create calendar events from emails. In addition
                                                                                                            • Need Easy Way to Update Item Prices in Bulk

                                                                                                              Hello Everyone, In Zoho Books, updating selling prices is taking too much time. Right now we have to either edit items one by one or do Excel export/import. It will be very useful if Zoho gives a simple option to: Select multiple items and update prices
                                                                                                            • Vendor Master Enhancements for Faster Purchase Entry

                                                                                                              I’d like to suggest a few features that will improve accuracy and speed during purchase voucher entry: Automated Item Tax Preference in Vendor Master Add an option to define item tax preference in the vendor master. Once set, this preference should automatically
                                                                                                            • Mass Mail Statistics - Number of unsent emails

                                                                                                              How do I find out which emails were not sent?
                                                                                                            • Button to add product to cart

                                                                                                              Is there a way to have a button on a page, that when clicked, will add Qty 1 of a product to the cart?
                                                                                                            • Next Page