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
Zoho Desk: No Incoming email
Is Zoho Desk services down? No incoming email reflect to desk tickets.Zoho CRM - Widgets | Update #3 : Introducing SDK V1.5 along with new ZDK Methods and ZRC Support
Hello everyone! Widgets in Zoho CRM just got a big upgrade! With the release of SDK v1.5, developers can now create more immersive widget experiences. This update elevates Widget development with new ZDK methods for easier interactivity and ZRC supportUnusual activity detected, account blocked
I am unable to send emails and am getting the error "Outgoing blocked: Unusual activity detected. To unblock your account, please and submit a request. Learn more.". I am unsure as to why this is happening since all my activity is legitimate, mainly confirmationUnable to Send Emails – Outgoing Mail Blocked (Error 554 5.1.8)
Description: Hello Zoho Support Team, I am facing an issue with my Zoho Mail account ( admin@osamarahmani.tech ). Whenever I try to send an email, I get the following error: 554 5.1.8 Email Outgoing Blocked I would like to clarify that I have not doneIssue connecting Zoho Mail to Thunderbird (IMAP/SMTP authentication error)
Dear Zoho Support, I am trying to configure my Zoho Mail account on Thunderbird, but I keep getting authentication errors. Account: info@baktradingtn.com Domain: baktradingtn.com Settings used: IMAP: imap.zoho.com, Port 993, SSL/TLS, Normal Password SMTP:Payment issue with Mail Lite plan – personal NIF not accepted as payment info
Hello, I have already contacted Zoho Support by email regarding this, but since I haven’t received any reply yet, I’m sharing it here as well to see if the community can help. I’m facing a payment issue for my Mail Lite plan. I have a personal accountCustomer payment alerts in Zoho Cliq
For businesses that depend on cash flow, payment updates are essential for operational decision-making and go beyond simple accounting entries. The sales team needs to be notified when invoices are cleared so that upcoming orders can be released. In contrast,Figma in Zoho Creator
Hi Team, I’m creating a form using Figma and would like to know how to add workflows like scheduling, custom validation, and other logic to it. Can anyone help me understand how to set this up for a Figma-based Creator UI form?Not receiving Gmail confirmation email to send emails as Zoho account from Gmail
Hello! I'm having an issue with the "Send mail as" option on Gmail. I am not receiving the confirmation email on my Zoho Mail account. A few days ago, it worked, then it stopped, and now when I try to fix it, I simply don't receive the confirmation emailRestore lost Invoice!
Some time ago I tried to Upgrade from Invoice to Books. I not upgraded and staid n Invoice. Now i tried again and first i deleted the old trial of books. But now all is gone, PLEASE HELP!! i have no backup and i have to have at least 7 years data retention by law.Zoho Desk Down
Not loadinglookup and integrated forms
I might be misunderstanding things but I wanted to integrate our zoho crm contacts into creator. I imagined that when I used the integration it would mirror into creator. It did brilliant. BUT We have a ticket form in creator that we want to use a lookupPartially receive PO without partial Bill?
Most of our inventory is pre-paid. Let's say we purchase 30 pieces of 3 different items for a total of 90 pieces. It is common for our supplier to send us the items as they are ready. So we will receive 30 pieces at a time. How can I partially receive2 users editing the same record - loose changes
Hello, I'm very new to Zoho so apology if this has been addressed somewhere i can't find. I have noticed the following: If we have 2 users put an inventory item in edit mode at the same time: say user1 click on edit and user2 while user1 is still in edit,How to get the Dashboard page to be the first page when you open the app
So when it opens on a tablet or phone it opens on the welcome page, thanks.How I set default email addresses for Sales Orders and Invoices
I have customers that have different departments that handle Sales Orders and Invoices. How can i set a default email for Sales Orders that's different than the default email for Invoices? Is there a way I can automate this using the Contact Persons DepartmentsFormula fields not refreshing until page is reloaded
I need help/advice about the formula fields and how I can refresh the information in real-time. We have two formula fields on our deals page which show calculated prices: One formula is in a subform which calculates the subform total + 1 other field amountHow can I setup Zoho MCP with Chat GPT
I can set up custom connections with Chat GPT but I cat an error when I try to set it up. The error is: "This MCP server can't be used by ChatGPT to search information because it doesn't implement our specification: search action not found" Thoughts?API ZOHO CRM Picket list with wrong values
I am using Zoho API v.8. with python to create records in a custom module named "Veranstaltung" in this custom module I've got a picket list called "Email_Template" with 28 Values. I've added 8 new values yesterday, but if I try to use on of those valuesGroup Emails
I have synced Zoho CRM to Campaigns but there are certain email not synced. showing it is Group Emails, but this email ids belongs to different individuals. please provide a solution as i nedd to sync the same.Enable Password Import option in ulaa browser
Dear Ulaa Team, I noticed that the Ulaa Password Manager currently offers an option to export passwords, but not to import them. This limitation poses a challenge for users like me who have stored numerous credentials in browsers like Chrome. Manually"Is Zoho CRM customer" vs "Is linked with Zoho CRM"
Recently while building a Flow, I was setting up a Decision action following a Zoho Invoice Fetch record action. There were 2 choices that I had not seen as something I could manually action in Zoho Invoice: "Is Zoho CRM customer" and "Is linked withClient Script | Update - Introducing ZRC: Simplified HTTP request library
Hello Developers! Are you tired of juggling different methods to make API calls? Are you confused with multiple syntaxes and version restrictions? Have you ever wished for one simple way to make all API calls in CRM? We heard you :) Here comes ZRC (ZohoSelection Filed for Data Export section
Hi FSM Team, I hope you are all doing well. I would like to share an idea for future development based on my experience. Currently, in FSM, we can only download up to 5,000 records at a time. If the development team could add a selection option to chooseWhat if I dont see contacts on the left side list
My CRM does not show the contacts tab. In order to create list this is needed and I cant find it.Comments Vs. Replies
I'm curious as to the difference between a "Reply" and a "Comment" on a ticket. It appears that "Replies" are what's used to determine response time SLA's and there are also used to automatically re-open tickets. I'm just trying to understand the key differences so I can educate both our clientele and our back-end users on which function/feature to use to better improve the ticket lifecycle. If anyone has any insight it would be appreciated. Thanks!Transitioning to API Credits in Zoho Desk
At Zoho Desk, we’re always looking for ways to help keep your business operations running smoothly. This includes empowering teams that rely on APIs for essential integrations, functions and extensions. We’ve reimagined how API usage is measured to giveCan you prevent closing Ulaa window when the last tab is closed (inadvertently)?
Most browsers have started to bring this feature in to prevent closing their windows when the last tab is closed (inadvertently). I hope Ulaa should get this in too.Microsoft Phone Link
Does anyone know if you can use Microsoft Phone Link to make calls through Zoho?Removing Related Modules Lookup Fields Assignment / Relationship
Issue: When creating a related list, I accidently selected module itself creating a circle reference. See attached. Situation: I wish to relating a custom module called "Phone Calls" to Leads and Contacts. Outcome: 1) I either want to remove the thisMultiple email accounts, one phone
Hi, I have my own businesses that use Zoho mail, now I would like to use zoho mail also for a local charity. But I noticed adding a phone number is compulsory for registering an account, and I only have one phone. This means I can not open an account because my phone number is already in use for another account. Can this be fixed? Thanks VincentAttendance | Flexible Working Hours
hi there, we are a small digital business working with flexible working hours and we are having a hard time setting up zoho people for attendance tracking. everyone of us has an individual agreement with the company regarding weekly hours (e.g. 40 hours/week,Seriously - Create multiple contacts for leads, (With Company as lead) Zoho CRM
In Zoho CRM, considering a comapny as a lead, you need us to allow addition of more than one contact. Currently the Lead Section is missing "Add contact" feature which is available in "Accounts". When you know that a particular lead can have multiplecan I link a contacts to multiple accounts
can I link a contacts to multiple accountsFree webinar! Digitize recruitment and onboarding with Zoho Sign and Zoho Recruit
Hello, Tired of being buried in onboarding paperwork? With the integration between Zoho Sign and Zoho Recruit, a powerful applicant tracking system, you can digitize and streamline the entire recruitment and onboarding process, all from one platform.Open Activities view.
I really like the new views for the open and closed activities inside the deals. But when you are in the tab view instead of the column view you can only complete and edit the open activity there isn't the 3 dot option to be able to delete the activPotentially Outdated and Vulnerable Chromium Engine Installed by Ulaa Browser Installer
I just installed Ulaa Browser a few minutes ago. Whats My Browser page shows I am using an outdated Chromium engine meaning I might be vulnerable for security exploits that might have got fixed in the new version.Potentially hardcoded list of Browsers to import from (after Ulaa Setup)
I have just installed Ulaa Browser and found that the list of browser to import data is potentially hardcoded ones rather than looking at the system. I do not have FF, IE and Edge is not my default itself. I would appreciated if Ulaa detected my browsersFrom Layout to Code: Finding Custom Field IDs in Zoho Projects.
Hello everyone! Ever found yourself wondering how to get the API names and IDs of custom fields in Zoho Projects while working on custom functions? Here’s a simple and effective way to do it! This method makes it super easy to locate the right field detailsCan I create multiple Zoho mail accounts?
Hey there I've searched the FAQ for this but didn't find the answer I was looking for. I like to have a different e-mail address for personal stuff, for creating account on websites, and for online banking / e-commerce. Is it allowed to create three accounts for one person on Zoho? I already have one personal e-mail address, can I sign up two more times from the homepage? ThanksNext Page