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
Translation in zoho bookings
We cant translate zoho booking emails. The general text we can change. But what about text like: ""Here a link to join the meeting online:"" and "Add to Zoho Calendar" and "Add to Google Calendar"? No professional business have mixed languages. Its lookingIs there any way to bill one client in different currencies on different invoices?
I have some customers who have their currency set as USD and most of their billing is done in USD. However, from time to time I have a need to bill them in my base currency GBP for some specific invoices, but there seems to be no way of doing this that I can see. The only workaround that I can see is to create two client records for the same client, one for USD billing and one for GBP billing, but this is not an ideal situation. Is it likely that the (hopefully!) soon to arrive multi-currency supportAPI name for all fields in Zoho Project (Standard or custom)
Hi! I struggle to find easily all API name of all field in Zoho Project to build my API rest with other services. We can find them very fast in CRM but not in PRoject. Could you share a function to get the list of all API Name of any field of an AppZoho Assist not rendering NinjaTrader chart properly
Hi everyone. Just installed and testing Zoho Assist. I want to display my laptop' screen (Windows 11) on a monitor connected to my Mac mini. The laptop is running a stock trading program called NinjaTrader. Basically, when running, this program displaysLink(s) between Notes
Hello Everyone, It would be great if links could be created between notes. Let's say we have 5 Notes A, B, C , D, E. I would like to be able to link Note A to Note B but not in other way, so no link appears in Note B linking to Note A. An so on, linkingFeature Request: Assign Documents to Already Entered Bills, Expenses, Invoices, etc.
Hi Zoho Team, We are regular users of the Documents module in Zoho Books and appreciate its ability to keep financial records well-organized. However, we’ve noticed a limitation: There is no way to attach a document from the "Documents > Files" sectionI don't see any WITHDRAWL transaction at all
Hi I manually imported my bank statement to Zoho books today and I am a complete newbie. I have been reading the knowledgebase but unable to fix this. I only see "Uncategorized 91 DEPOSIT transactions". I don't see any WITHDRAWL transaction at all. Also,Shared inbox unable to see replies
Hi we are a small company me and someone else, we have a shared inbox for our sale@ and contact@ however we have this issue where by if i reply to an email or the other person reply to the email, it does not show it to them and therefore we end up replying404 error at checkout
Our customers are getting a 404 error at checkout. Anyone else with the same problem?FONT Sizing in Notebook
Hi Kishore - What is the status of adding font sizing to the application? I have several things that I have pasted directly into Notebook and the fonts are HUGE! I would like the ability to highlight them and reduce the font to a legible size. NothingCan managers Upload documents to their direct rapports?
Admin employees have the ability to upload documents to employees' files; however, managers do not have add/manage button - is it possible for managers to upload their direct reports' documents, such as absence documents or 121 documents. Is there somethingLeave balance display for next year
Is there a way to not have a rollover or not limit the leave balance depending on the date. For example an employee has 10 days leave balance and wants to apply for January leave in December. They cant because the rollover doesnt show the leave balancePlease add an “Auto-Apply Unused Credits” toggle
Hello — please add a simple org-level option to automatically apply unused credits (credit notes, excess payments, retainers) to new invoices and/or bills. An ON/OFF toggle with choices “invoices”, “bills”, or “both” would save lots of manual work forZoho Books not working/loading
Hi! I haven't been able to access/load Zoho Books for the past hours. I get a time out (and it is not due to my internet connection). Could you please check this asap? Thank you!Custom Fields with Data Types for Expense and Payments Received in Zoho Books
Hi all, We are glad to present to you, the option to create Custom Fields for the Expense and Payments received modules in Zoho Books. This also comes with an icing on top of it - Yes, the custom fields can now be created with different data types. Types like Text, Number, Decimal, Amount, Auto Number and Check Box are supported as of now. Rush to the gear icon at the top right corner, select 'More Settings', choose 'Preferences' in the left pane. Click the Expense/Payment preferences where you canZoho Cliq - Incident alert (Server outage - IN DC) | August 28
We've received server down alerts and are currently investigating the issue (IN DC) to find the root cause. Our team is actively working to restore normal operations at the earliest. Status: Under investigation Start time: 09:44:21 AM IST Affected location:How can I see content of system generated mails from zBooks?
System generated mails for offers or invices appear in the mail tab of the designated customer. How can I view the content? It also doesn't appear in zMail sent folder.Narrative 10: Assignment Rules - Streamlining Ticket Management
Behind the scenes of a successful ticketing system: BTS Series Narrative 10: Assignment Rules - Streamlining Ticket Management In the complex world of customer support, a flood of incoming tickets can hit the help desk in seconds. Businesses must do moreCustom form - Duplicate Value Present
I am new to Zoho People. I create a new form on Zoho People quite simple. A date (by default the current date) and a radio button with 3 options (Yes, No, Not applicable) I defined the date as ‘No duplicate’ as only one entry by date is allowed. I added:Zoho API connection issues
Hi, Today at around 1930 GMT our application started experiencing intermittent timeouts from the Zoho API. These intermittent timeouts are not enabling our app to work properly. The API connection was working just fine before. HTTPSConnectionPool(host='www.zohoapis.com',Query Regarding our Partnership between AIC-JKLU and Zoho
Dear Zoho Team, I am writing to raise a concern on behalf of AIC-JKLU, one of Zoho’s incubator partners. Recently, our startups have been facing difficulties while trying to get themselves onboarded on Zoho through our dedicated partner link. Unfortunately,Getting events in the future
Hi I am trying to get events in the future by calling this API Endpoint https://www.zohoapis.eu/crm/v8/Events?fields=Event_Title,Created_By,Created_Time,Start_DateTime But that gives me all events in the database. How do I make a query that returns allCreated Date/Invalid Fields
Since Saturday we have suddenly had issues with our webhooks and data retrieval from CRM. Specifically how Created Date is handled. It appears there was some sort of change within CRM that broke a lot of our code that has been in place for several years.Revenue Management: #9 Revenue Recognition in Media & Publishing
Media & Publishing industry has evolved in recent times. It offers subscriptions, bundles digital and print access, runs sponsored content, and sometimes even sells ad spaces. If you run a media or publishing business, you will always get into a situationZoho CRM Community Digest - July 2025 | Part 2
Hello, Everyone! We’re closing out July with a can’t-miss highlight: Zoholics Europe 2025! Happening from September to October, it’s your chance to level up your CRM skills, covering everything from automation and CPQ to dashboards and advanced workflows.How can I trigger a flow action only once while updating contact?
Hi, we have a trigger to merge&mail file when the field YYY is filled out. For this acion I used "Create or update module entry". But unfortunately we get tens of email on a day with this merged file, because the contact is being regularly updated. TheCopy a Record Template from one Form to another
I have a Creator application with several forms. I developed a record template for one of the reports/forms but want to use most of it for another of the form/report combinations in the application. Is there a way to copy the template (code or otherwise) to another form?Tip of the Week #70 – Create common team signatures for your shared inboxes
Did you know that a small detail, such as an email signature, can make a big difference in how your brand is perceived? One simple yet smart way to enhance your team’s communication is by creating common team signatures for your shared inboxes. InsteadEnhanced data export features: XLSX format, custom character encoding, and selective record export
Greetings all, Here are a few enhancements related to exporting CRM data, including the ability to export data in XLSX file format now. The Export feature under Data Administration now offers new options that expand its flexibility and enable users toTip #42 – How to manage data security with Privacy Settings – 'Insider Insights'
Data privacy is a cornerstone of trust in remote support. Through Privacy Settings in Zoho Assist, you can set up how data is gathered, stored, and handled in your organization. These settings ensure compliance, data protection for sensitive details,Ticketbai! en el Pais Vasco
Hola a todos, En enero de 2.022 se va a implantar en el país vasco un nuevo sistema de facturación, denominado ticketbai!, ¿hay alguna previsión de realizar las adaptaciones en zoho books o zoho invoices? Ignoro la cantidad de clientes que tienen estasZoho CRM mobile app feature update: home page widgets, field tooltips and user image upload
Hello everyone! Your business doesn't pause when you're on the move, and neither should your CRM. That's why in our latest update, we've introduced a few new features to make your mobile CRM experience smoother and more efficient. Let's take a quick lookZoho CRM Plain Text Template: Line Breaks and Formatting Issue
Hello, I'm following the instructions to create email templates in Zoho CRM, but I'm having a problem with the plain text version. https://help.zoho.com/portal/en/kb/zoho-sign/integrations/zoho-apps/zoho-crm/articles/zoho-crm-email-templates#Steps_to_create_a_custom_email_templateOptimizing Task Handling: Auto-Remove Recurrence for cancelled Tasks.
Hello Everyone, A Custom function is a user-written set of code to achieve a specific requirement. Set the required conditions needed as when to trigger using the Workflow rules (be it Tasks / Project) and associate the custom function to it. Requirement:Create, collaborate, and manage agreements with Zoho Sign
Agreements drive business. We launched Zoho Sign in 2017 as a simple digital signature tool to sign agreements from anywhere, at any time. Over the years, we've learned that most agreements go through last-minute changes before they're signed. Our usershiding a topic from all but one segment (or list)
My organization sends out a number of newsletters using Zoho Campaigns. One of those newsletters is for volunteers. In order to become a volunteer, a person has to first go through our volunteer orientation (training). After that, they can receive newslettersHow do I set up this automation correctly?
When contacts enter my Subscribers list, I want it to reference a custom field to see if it is empty. Then I want it to do two things: If empty: Assign a tag based on a different custom field. If that custom field is empty, assign a different tag. IfFunction #62: Display associated Quote on Invoice details screen
Hello everyone! Today, we are sharing a Related List script that makes it easy to view and access the quote from which an invoice was created right from the invoice details screen. This Related List displays the Quote number and Amount, allowing you toDesk x CRM Integration
Howdy! We currently use SalesIQ but we are considering moving across to Desk as it seems to have more functionality that we want. One of the pulls is the ability for our customers to self serve. But, I might be getting over excited and not actually needIssue with Save & Share Link – Works for Others but Not Creator
I’ve enabled the "Save and Share" feature in Zoho Forms, and it works correctly for all users accessing the public link—except for me (the form creator). Issue Details: When I save and share the link, recipients see a “no permission” error. The form isNext Page