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
- Go to https://api-console.zoho.com.
- Click ADD CLIENT.
- Choose the Client Type as Self Client, and click CREATE.
- You will receive a client ID and a client secret upon successful registration.
1.b. Web-based Client
- Go to https://api-console.zoho.com.
- Click ADD CLIENT.
- Choose the client as Web based and click CREATE NOW.
- 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.
- Click CREATE.
- 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 '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
Centralize Knowledge. Transform Learning.
All-in-one knowledge management and training platform for your employees and customers.
New to Zoho Recruit?
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Shylaja S
Sticky Posts
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.Kaizen #226: Using ZRC in Client Script
Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In thisKaizen #222 - Client Script Support for Notes Related List
Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore howKaizen #217 - Actions APIs : Tasks
Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.Kaizen #216 - Actions APIs : Email Notifications
Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are
New to Zoho TeamInbox?
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
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
Consolidation of Multi currency
Would like to discuss on the possibility of consolidating the ZOHO companiesLanded Cost Allocation / Custom Duty manual data entry
My client is an import business. They must manually enter the duty for each item with landed cost allocation in Bill. This is because customs duties cannot be allocated based on Quantity, Value, Weight, and Dimensions. Manual data entry is highly time-consumingTerritories Just Don't Work
I have been on chat and screenshare support for the past 3 days and am getting no resolution so hopefully, someone here can help me. I am the Super Admin of my organization. We publish books globally. I want to break down the books into territories soNegative Opening Balance
How can I add Negative Opening balance - meaning a credit balance to a Customer or a debit balance to a vendor? If I go thru Sales-->Customers, and if the opening balance is Rs. 1000 (credit balance), it does not allow me to enter a "minus" sign or mentionSingle-Line Invoicing from Sales Order Despite Multiple SKUs Shipped
We deal mostly with Government Tenders And Lets say we got a tender that needs 125 XYZ Laptops Then we found 95 Laptops with a different SKUs and 30 Laptops with different SKUs We talk with the IT department of the government company and they approve📣📣 Zoho Bookings Schedulathon 2025 is here!
Hey Zoho Bookings fam, We're excited to invite you to our first-ever hackathon: Yes, Zoho Bookings Schedulathon 2025 is live now. This is a virtual event and you can participate anywhere from the world. Businesses should be able to set up meetings fromI want to send out a new newsletter each month
Without rebuilding a whole journey is there a way to create a new newsletter that is sent to an existing journey monthly?Reinstalling Workdrive Truesync client
Hi, I attempted to update to the beta version of TrueSync, but it was unstable and kept crashing, so I need to revert to the stable version. How do I properly reinstall TrueSync on a Windows PC? I couldn't install the 3.15.x version directly over theEvaluating Creator; yesterday fine; today connection times out
Yesterday I spent hours creating a new app, and it worked fine. Today I cannot access creator.zoho.com. Is this common? I'm in the evaluation mode, but I'm thinking I'm going to keep looking. It worked from my home computer, and now I'm checking it from my work computer. My work computer always works just fine, so I shouldn't htink there would be special settings or anything. If there are, how to find out what they could be? Using Chrome on Windows XP The error I get is: The webpage at https://creator.zoho.comPivot Chart seems to show "old" data - how do I make it update?
I wonder how to make a Pivot Chart "update" its data contents. Here is the background: I need to report a subset of data that is so complicated that it is easier to make a calculation and put the result in a "reporting form", and then display the data from that form. So, I get data from the "original form" GRANTS, make some calculations and put the result in the "reporting form" PERIOD. Now I can watch the result in a list called LIST, which works fine. The list LIST shows that form PERIOD containsUpcoming Changes to LinkedIn Parsing in Resume Extractor
Starting 31 July 2025, the Zoho Recruit Resume Extractor will no longer support direct parsing of candidate data from LinkedIn profiles. Why Is This Change Needed? In accordance with LinkedIn’s platform policies, extracting profile data through browserhow to create view in leads module to that will show all leads + converted leads?
is it possible to make custom view that combine all leads + converted leads? how to do thatAvalara Sales Tax integration - AVATAX
Just wondering if anyone else is having troubles with this integration? Seems as though Avalara changed their billing process, unbeknownst to Zoho, and now ALL transactions are counted by Avalara, not just transactions in a taxable jurisdiction. This caused a huge price adjustment billed to us by Avalara within a month of us signing up. And Avalara is not cheap to begin with! Avalara has been great in waiving that increase, but there seems to be no fix. Zoho is aware of the problem, but slowInvalid value passed for description
Dear Sir, When I am entering the purchase bill , the following message showing "Invalid value passed for description" what should I do ? I am attaching screenshot. With Regards, Harish harish@cracku.in 7978841636Zoho Creator - 2024 Release Projection 1
Hello everyone! As we enter 2024, we'd like to extend our warmest wishes for success and prosperity. Your fantastic response to our Product Roadmap page last year has been incredibly motivating. Continuing on this path, we're excited to share a glimpseAutomation Assistance for Zoho Form Integration and Workflow
Hi, We are currently using a Zoho Form to send out our Global Credit Application and would like to automate the process further. Specifically, we’d like the ABN number submitted through the form to automatically populate the GST/VAT Number field in ZohoCOQL does not return queryable value if the result set is empty
See linked video for running code illustration of the problem: https://workdrive.zohoexternal.com/external/d49bb40033b43b288d56fdf843095b7c65b28391d3ec5d09c854f416d853003d Moderation update: We are appending the comment that was removed, to add contextZoho CRMでの商談の管理のしかたについて初歩的な質問です。
先月からZoho CRMを試験的に導入して運用しています。 商談の管理（運用？）の仕方について教えてください。 商談の数が増えてくると、ダッシュボードの「ステージ別進捗状況」にどんどん過去の商談が蓄積されてくると思うのですが、 現在動きのあるものを中心に確認したくなる気がします。 そのあたりについては、どのように運用が一般的なのでしょうか？ アドバイスいただけるととてもありがたいです。 よろしくお願いします。Composite Items & Purchase Orders
The Composite Item is great way to bundle different products and services into a single line and sell it as a single line item in Estimates, Sales Orders and Invoices. However, on the other side - i,e,. Purchasing - this item creates quite a bit of ausing custom function is it possible to update the created by field in Zoho Crm custom module
using custom function is it possible to update the created by field in Zoho Crm custom moduleSlow Sloww Slowwww Responses
Good day, Has anyone been experiencing slow responses from support? Since Thursday I migrated my Whats app to Sales Iq and I had to synch with Social to get the otp they were sending. Apparently What's app can't be automatically added so I reached outYou have exceeded the maximum number of attempts for this action. Please retry doing the same in 30 minutes.
When one of Zoho Books user tries to select a vendor, recording a new bill, these message appears: You have exceeded the maximum number of attempts for this action. Please retry doing the same in 30 minutes. Other user, at the same time, but differentEnable Conversation Context Retention for SalesIQ Answer Bots
Hello Zoho SalesIQ Team, We hope you are doing well. We have noticed that SalesIQ bots currently fail to maintain conversation context in Hebrew. For example, when we follow up on a previous answer or ask for clarification in Hebrew, the bot either providesAutomatic Hebrew Small Talk Setup Without Duplicate Term Errors & Manual Configuration
Dear Zoho SalesIQ Team, Greetings, We would like to request an enhancement to the Small Talk feature in Zoho SalesIQ, specifically for Hebrew language support. Current Challenge: When setting up Small Talk for Hebrew, we encounter multiple issues: SimpleTrouble fetching custom fields from Zoho Booking
I'm following the instructions from here : https://help.zoho.com/portal/en/kb/flow/user-guide/app-specific-documentation/articles/zoho-bookings#1_Problem_with_accessing_custom_fields But I can't get this to work. Here is the result of a test booking :Should I Add Leads in Bigin?
ok, first off I'm new here. I just started using Bigin. I'm debating if it's appropriate to enter leads. by leads I mean a list of contacts that I have not yet reached out to...it's a cold calling list. if I enter them I can track them (I understandZoho Books - Perform a validation check before an invoice is marked as sent or sent
Allow the validation rules to apply to button actions. For example: an invoice could not be sent or marked as sent if it has an empty value in a custom field. (The field could remain blank while it is being worked on.)Flow error "given url is wrong"
when I setup a flow to update a task status, I get an error when it runs that says "given url is wrong."Bigin Android app update: Email filters enhancement, change owner for related records.
Hello, everyone! In the most recent Bigin Android app update, we have introduced additional email filters and an option to change the owner of related records. Email filters: We have now brought in support for 'All Emails' and 'Added from Widgets' filterHow can I get all conversations and comments of a Zoho Desk ticket using ZOHODESK
Hi everyone, Currently, I am developing a Zoho Desk extension, and I am following the guide available at https://www.zoho.com/desk/extensions/guide/#ticket-object. While working with Zoho Desk, I have noticed that I can only retrieve the general informationAI & Zoho Recruit
Hello, I guess we all are using AI in our personal and professional lives. Now, let's imagine. Recruitment is just a succession of stages and steps. For which step would you like to see AI implemented into Zoho Recruit ? I'll start : - Automatic translationwidget url 404'ing
I'm creating a widget for the first time. When I grab the url from the base url section of the widget builder and append /widget.html it 404's Just wrote a very basic test. I have a folder structure app.zip - widget.html --js/app.js /widget.html <!DOCTYPEUnable to Edit Pick-List Items in Custom Project Field(s)
I can edit most fields normally, but if I try to edit - in any way - a Pick List field, I just get this error: To be perfectly clear, I'm trying to edit an existing Pick List field (adding or removing items), not adding a new instance. If I rename it,How to display results from zoho.crm.searchRecords in message window
Hello, I've created a custom function which is linked to a custom button which pulls a date from our contacts module and searches a date field in our quotes module and returns all records matching the date. My issue is, how to I get this to display theDomain Transfer
Hello there! I wanted to know if I can transfer my domain from Zoho to other hosting providers or use a different hosting provider instead of zoho's services.New User - Opening Stock Aging Report
I am setting up new client and am entering Opening Stock - created items and entered quantity/price details. Now the aging report is showing all the opening stock as new. How do I enter the Purchase Dates of these items so that I get accurate InventoryBulk Receive Multiple Purchase Orders
Is there a feature or function that will allow you to bulk receive issued purchase orders? I have about 100 that need to be received from 5 years ago.Manual Invoice
How to create a Manual invoice, I need to enter Amount directly instead of (qty*Rate). our company is a service sectorMerging contacts and or accounts
Hello, In a prior CRM we were able to merge contacts and or accounts. We have turned on the function to stop multiple contacts with the same email, so we can prevent multiple contacts from happening, however, we now have multiple contacts that have theCapture Reason for absence next to Campaign Member Status. Is there a reasonable workaround?
I've reviewed the topics I could find to do with this but still couldn't find anything that satisfies our requirements: We would like to track a *reason* (picklist or text, doesn't matter which) why a Campaign Member (Lead or Contact associated with aNext Page