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
Work Order Assignment for Engineers Handling Their Own Requests
I’m setting up FSM for a business where there are multiple engineers, but each engineer handles their own process end-to-end receiving the service request, creating the work order, and completing the field service job. I noticed that I must create anExperience Zoho Show on Mac now!
Work today isn’t tied to a single place, time, or routine. It happens in cafes between meetings, on flights, or late at night when ideas strike. And when ins, your tools need to be ready, wherever you are. That’s why we built the Zoho Show app for Mac.【開催報告】東京 ユーザー交流会 Vol.4 | Zoho CRM 自動化のコツ ・Bookings のビジネス活用シーンとおすすめ機能を紹介
ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 11月28日(金)に新橋で「東京 ユーザー交流会 Vol.4」を開催しました。ご参加くださったユーザーの皆さま、ありがとうございました。ユーザー交流会の年内開催は、今回が最後でした。 この投稿では、当日のセッションの様子や使用した資料を紹介しています。残念ながら当日お越しいただけなかった方も、ぜひチェックしてみてください😊 ユーザー活用事例セッション：関数やクライアントスクリプトまで、CRMをもっと便利に Zoho CRM には、ワークフローやブループリントなど、さまざまな自動化に役立つ標準機能が備わっています。さらに、関数（Deluge）のようにスクリプトを記述して高度な自動化を実現することもできます。Kiosk Button Actions
I need to add an action to a Kiosk Button to loop me back to start the kiosk again and I am not sure what that looks like (function, etc.).Dependent drop-downs... how?
Good day. I have 2 different situations where I need a dependent drop-down field. First is for a subform, where I want to show related fields for a specific customer on the main form. In my case it is a parent whose children make use of our school transportReporting Limitation on Lead–Product Relation in Zoho CRM
I noticed that Zoho CRM has a default Products related list under Leads. However, when I try to create a report for Lead–Product association, I’m facing some limitations. To fix this, I’m considering adding a multi-lookup field along with a custom relatedSeries Label in the Legend
My legend reads 'Series 1' and 'Series 2'. From everything I read online, Zoho is supposed to change the data names if it's formatted correctly. I have the proper labels on the top of the columns and the right range selected. I assume it's something inDynamic Signature - Record owner
Hi everyone, I’m using Zoho Writer merge templates from Zoho CRM and have two questions: Owner signature: How can I automatically insert the CRM record owner’s signature in the merged document? I’m not sure where this signature is stored or how to referencePrinting from Zoho Creator hosted on my own server to printers hosted on my clients local network
Hello. Fairly new to Zoho Creator and looking for best options to be able to print from my application hosted on my own server to any printer hosted on my clients own local network. Any advice is welcome. Thank you.Add System Pre-Defined Lookup Field to Subform?
Hi there! New to using Zoho, so this may already exist, but I'm having trouble figuring it out. Is there a way to get the system pre-defined Account Lookup field (in our case, renamed to Company Name), as the starting point for a subform? In our company,Numbered / bullet point List in Zho Cliq
Hi, is there a way to format chat messages in Cliq like this Topic 1 Hey, I finished this project yesterday etc... Topic 2 I am still working on this etc...Cannot Access Subform Display Order in Deluge
As highlighted in this community post, we still have to deal with the significant limitation of not being able to access the user-sorted order of subform rows through Deluge. This creates a major disconnect between the UI capabilities and backend automation,How many groups in Zoho Mail can I make?
I'm currently on the free plan, which has a limit of 10 users. Does that limit includes groups too? If not, what is the limit for groups? Thanks!Feature Suggestion for Zoho Social: Auto-reply to Comments or Keywords
Hi Zoho team, I'd like to suggest a very specific feature that would be extremely helpful for customer engagement: the ability to automatically send a reply to comments on posts — either all comments or those containing specific keywords. For example,Already have Zoho account. Not letting me log in
I already have a Zoho account that is associated with my Google email and my phone number. Even though I'm already logged in to Zoho, when I click on the mail icon to access my email, it takes me to the pricing page. When I click on the free option, itZOHO Mail App Not working
There seems to be an issue with Zoho Mail App today. It is not connecting to server, internet is working fine, tried uninstalling app and reinstalling, loading circle keeps spinning round. Is there an update on the way?facing error 550 5.4.6 while sending emails
Please help me fix this issueAllow Itemization for Recurring Expenses
For whatever reason, one cannot itemize a Recurring Expense. This capability should be added. The use cases to support this are largely the same as what they were to allow for itemization in Expenses. Anything that would need to be itemized for a regularZoho reply to not working. just reply to my self
Hello. i using on my wordpress website a contact form from Wsform. i can set the reply to email there. normally it works. but since i am using your wordpress plugin zoho mail it doesn`t work. its not using the reply to (email from customer). I just canCan't receive any email from other platform
Hello,everyone, i'm just join zoho and create two email accounts for my own business. I was using it to get a verified email from stripe, but can't receive it. and I use my private gmail account to send test email twice, first time show below reply, butYour Incoming has been blocked and the emails will not be fetched in your Zoho account and POP Accounts
Can some on help me regarding our account . thank you so muchZoho Creator integration with Sage 50
Hi, Wondering if anyone has had any experience connecting Zoho to Sage 50 and could share any information on this matter. Thank you.Conditional Email Forwarding
How can I set conditional email forwarding of the users? For example: Mail should be forwarded to a address only if it comes from a particular sender. So, I want such email forwarding, which forwards mails based on particular conditions, like the incomingIncoming emails not appearing in Inbox
Hello, I have an issue with incoming emails sent from my website (domain: h2ostop.si). Emails are visible in the Sent folder, which means they are successfully sent through Zoho SMTP, but they never appear in my Inbox. Nothing arrives in Inbox, Spam,Email Opt Out Question
Has the problem where if a customer is emailed opt out prevents you sending standard emails? For me this feature is simply to stop any email marketing and should not block people from receiving emails via Zoho mobile, which makes no sense.Can No Longer Access Zoho Email Accounts from iPhone or iPad Apple Mail Apps ,.
Keeps asking for password, Says ID or password incorrect. Tried creating a new app specific password. Same result. Is this possibly related to the server maintenance. Have verified all email settings, userid and password. This has worked for years untilLatest update caused issue in using marathi typingzoho
With latest update now marathi typing does Not work in zohonotebook. I preferred zoho over other because it was supporting marathi font without any distortion.. But after new update,keyborad simply does not workLogin verification emails never received.
I can't login to my account. You send a verification email, but it never arrives. This is a common problem, frequently caused by some relay point out there classifying the sender as a spammer. Is there anything I can do to bypass this? Maybe get a textGlobal lists for Multi select
It would be great if I could select a global list to use for a multi select dropdown filed.Yahoo is rejecting e-mails sent from a Zoho server
Diagnostic-Code: 4.7.0 [TSS04] Messages from 136.143.169.51 temporarily deferred due to unexpected volume or user complaints - 4.16.55.1; see https://postmaster.yahooinc.com/error-codes Remote-MTA: dns; mta5.am0.yahoodns.netYahoo blocks e-mail sent from Zoho servers
Getting this for a bunch of Yahoo addresses. Do you know if some of your servers got blacklisted? Diagnostic-Code: 4.7.0 [TSS04] Messages from 136.143.169.51 temporarily deferred due to unexpected volume or user complaints - 4.16.55.1; see https://postmaster.yahooinc.com/error-codesWorking with dates and Function Field
Hello friends! I'm trying to add days to a date, however the field function will always shows 00:00:00 after the resultant date. How can I display only the date, whithout the time? toDate(input.request_date.addDay(input.Prazo_acordado),"MM,d,yyyy") The code above will result something like "11-Feb-2020 00:00:00", but I want to display only "11-Feb-2020"What's New in Zoho Analytics - November 2025
We're thrilled to announce a significant update focused on expanding your data connectivity, enhancing visualization capabilities, and delivering a more powerful, intuitive, and performant analytics experience. Here’s a look at what’s new. Explore What'sUnable to send message;Reason:550 5.4.6 Unusual sending activity detected. Please try after sometime.
Please help my account got blocked automatically, can you help me how to avoid it? Thanks so muchtemporary system errorlouis
J'essaye d'envoyer des mails avec mes 2 adresses mail qe nous avons sur le compte arthur@lepunch.fr et louis@lepunch.fr mais j'ai toujours le message temporaire system error, je reçois les mails mais impossible d'en envoyer a qui que ce soitHow to Cancel/Delete Queued Mail Merge?
Hi. I just tried to do a mail merge before realizing there's a limit on number of sends. I accidentally sent one of my lists twice, and all of those emails are currently queued. Is there any way to cancel or delete a queued mail merge? Would love to beSOLVED: Stopping Multiple Invitations when sync with Google Calendar
I wanted to share this solution as I wasn't able to find it when searching through the Zoho community and via web search. The issue: When requestor books a meeting through Zoho Bookings, the requestor receives a confirmation email from both Bookings andNeed to add a new admin for my domain
Hello Zoho Support, I am the owner of the domain localeistanbul.com. The current super admin account (admin@localeistanbul.com) is not accessible. I do not want to reset or delete the existing account because I need to keep all existing emails. PleasePossible Fraud Site.
Hello. I received a text with the sender's name as zoho, claiming that my account was at risk and that I should sign in at https://verify.zohomails.ru/signin to verify my account. I signed in on the web address above, and a few days later someone hackedZoho mail to Teaminbox
Hello, We're searching for new mail program. Now I'm testing a bit with zoho mail and team inbox. My findings in the research: Pop mail throught zoho mail is almost instant. Any pop or imap via external provider takes a couple minutes to 15 minutes beforeNext Page