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
Retainer Invoice.
Why ZOHO not have facilities to deduct partially advance payment from an invoice.Share saved filters between others
Hi, I am in charge to setup all zoho system in our company. I am preparing saved filters for everybody, but the only one can see its me. How can others see it? ThanksNo practical examples of how survey data is analyzed
There are no examples of analysis with analytics of zoho survey data. Only survey meta data is analyzed, such as number of completes, not actual analysis of responses, such as the % in each gender, cross-tabulations of survey responses. One strange characteristicZoho Creator as LMS and Membership Solution
My client is interested in using Zoho One apps to deploy their membership academy offer. Zoho Creator was an option that came up in my research: Here are the components of the program/offer: 1. Membership portal - individual login credentials for eachAdding Chargebee as a Data Connector
Is it possible to get Chargebee added as a Zoho Analytics data connector?Access Kiosk features on android zoho crm mobile app
Hi, We’re wondering if there’s any option to use the Kiosk functionality in the Zoho CRM mobile app, similar to how it works on iOS. We’ve just discovered Kiosk Studio and it seems to be a very useful tool, but we really need it on Android. Is it perhapsDropbox to Workdrive
Namaste, Trust you all are doing well. Wanted to check how this can be done with Zoho flow. I typically receive dropbox links from my clients. Is there a way where I can provide the link to Zoho flow and it downloads the files from dropbox link to a workDeals by Stages Funnel not showing in correct order
Using the Stage-Probability Mapping for the Deals module we have created a steps our deals will pass through, RFQ, Closed/Lost, Declined/No-Go, Pricing, Submitted, Negotiations, Won. However when I view the Deal By Stages Funnel it does not show in theConfirmation prompt before a custom button action is triggered
Have you ever created a custom button and just hoped that you/your users are prompted first to confirm the action? Well, Zoho knows this concept. For example, in blueprint, whenever we want to advance to the next state by clicking the transition, it isHow to create auto populate field based on custom module in Zoho CRM?
Hello, i'm still new to Zoho CRM and work as administrator in my company. Currently, I'm configuring layout for Quotes Module. So, the idea is, I've created a read-only field in Quotes called "Spec". I want this field automatically filled with SpecificationOffice 365 and CRM mail integration: permission required
Has anyone run into this weird problem? My email server is Office 365. When I try to configure Zoho CRM to use this server, a Microsoft popup window opens requesting user and password. After entering that, I get a message in the Microsoft window sayingDeluge - Can't get phone number SalesIQ
Hey folks, I’m building a custom plug for SalesIQ that’s supposed to register leads into Zoho CRM. The SalesIQ chat is being implemented on WhatsApp, and in my plug I’m using this line: mobile_clean = session.get("phone").get("value"); From what I understand,Zoho Desk - Community
As a regular user of Zoho Cares Community I would really love to see the publish date of articles. For example, when I look at Announcements, it would be very beneficial to see which ones were posted recently, over those which have just and a recent comment.access to quartz for my customers
Hi how can I have access to the application quartz you use for us to send you screen rocording, this feature would be immensely useful for our customers support https://quartz.zoho.com/Issue with Inline Images in Email Reply via Zoho Desk API
Hi, I am attempting to send inline images in an email reply using the Zoho Desk API, but the images are not being displayed inline for the recipient. I have followed this documentation: https://desk.zoho.com/DeskAPIDocument#Uploads https://desk.zoho.com/DeskAPIDocument#Threads#Threads_SendEmailReplyHow to search a value stored in a subform?
Hello, We store serial numbers in subforms but now we would like to be able to search the values to be able to easily find the record with the serial number. I saw that it's not possible to search such values through global search but is it possible to do it an other way? Thank you,Field Dependency Not Working on Detail Page in Zoho Desk
Hi Support Team, I’ve created field dependencies between two fields in Zoho Desk, and they are working correctly on the Create and Edit layouts. However, on the Detail page, the fields are not displaying according to the dependencies I’ve set — they appearHow do the keyword critera work?
Hi, I'm working on automated assignment of tickets based on keywords. How does this feature work? Where does this criteria look for keywords - email address, subject, email body? Can you please clarify this as I want to avoid overlapping with criteriaError: Unsupported content type: text/html;charset=UTF-8 after tryeing to get the token for n8n automation
I am working on ZOHO Desk automation and need to get the ZOHO auth token for n8n I have created the app in ZOHO Desk API, got client id and client secret. Added all data required to get a token in n8n. After I sign in with my ZOHO credentials in ZOHOImproving Collaboration Features in Zoho Portal
Hello Zoho Community, I’ve recently started exploring Zoho services and I’m really impressed with the wide range of features. However, I feel there is still room for improvement in the collaboration area. For example, it would be really helpful if weAutomated Shopify Emails Not Being Delivered
I have an ecommerce store with Shopify. I recently set up my email to be served through Zoho. Since doing this, customers are not receiving some of our automated emails from Shopify itself. Our initial email that confirms their purchase goes through but our Shipping Notification that is automatically sent out upon fulfillment is not going through. Sometimes we get a notice that it's been classified as spam, sometimes nothing. I can send/receive email via Outlook on my desktop and I can send/receiveSend a campaign to one recipient.
Very often I speak to a customer and they say they didn't see my email (maybe it went in Junk, maybe they deleted it). Anyway, I just want to go into the Campaign and send it to one person. You already have a feature very close to this - when sending a Test. While developing a campaign, I can send tests to anyone. Why can't we have this AFTER the campaign has been sent? I know, there's a caveat, and that's in the use of merge tags. Most of the time I only use FNAME, but maybe you could check ifTry FSM again for our business
We already have our customers individual equipment in CRM with serial numbers, install dates, warranty length and importantly next service which is generally 2 years. a month before the service date is due we get get a report and send out service reminders.Issue with Zoho Help Portal – Tickets Missing or Not Answered
Hi, How are you? I think there may be an issue with the Zoho Help Portal. I opened a few tickets directly in the help portal a some time ago but never received any response I also opened ticket 148356451 by email. I did receive a reply to it, but theDUNS & Bradstreet and Credit risk monitoring integration with Zoho books
Small businesses not being paid by bigger clients and clients of all sizes is a huge problem. It will be nice if Zoho develops integration with DUNS & Bradstreet(D&B) and Credit risk monitoring integration with Zoho books. That have small businesses canZoho Forms - Form Rules based on attachment fields
Many businesses use forms to collect documents and images from customers. In many cases, you may want to trigger a notification or other automation based on whether or not an attachment was added. I've noticed that attachment fields do not appear in RulesCan't open draft email for editing
Last night I started composing an email and I let it save in drafts. This morning I want to continue working on the email. It is in my Drafts folder but it will not open. The only option there is to delete it. This is not the first time it has happened. On previous occasions I have just deleted the draft and started afresh, but I really want this one back. Windows 10 with Pale Moon 28.10.0 browser.Open filtered deals from campaign
Do you think a feature like this would be feasible? Say you are seeing campaign "XYZ" in CRM. The campaign has a related list of deals. If you want to see the related deals in a deal view, you should navigate to the Deals module, open the campaign filter,Change scheduling emails time
When sending an individual email there is a great feature to schedule them to send later. I could only use the one time that is suggested. Is there a way to select another time? Regards, GlennZoho CRM: how can I control which contacts to sync with Outlook?
I was just playing around syncing contacts from Zoho to MS Outlook (MS365 account.) The problem is our firm has hundreds of thousands of contacts and I don't want to bury my contacts list in outlook. Any help with this is greatly appreciated.How to overcome limitations in meetings
As a company, one of our deliverables is a meeting between two other companies, where we act as facilitators. So, if we recorded this meeting in Zoho CRM, it should be connected to 2 accounts, 2 contacts, and 1 campaign (a campaign, in our use, is theAdd a 'Log a Call' link to three dot icon in Canvas
Hi, There's a three dot element when creating a canvas called 'More'. I would like to modify this to add a link that says 'Log a Call' in order to quickly record the details of a cellphone call. I'd also like this to be a simple 'contact' selection andSyncing Zoho Forms with Bigin - Embedding issue?
Hello everyone, I created a Zoho Form for a page on my GoDaddy website to collect leads, which then transfers the data to Bigin. However, I'm facing an issue where it doesn't seem to work properly. I've integrated Zoho Forms with Bigin and tried embeddingCan not add fields to a Section
I feel like I'm missing something obvious: I can add new Sections to my form but I can not add fields to the Sections. I've tried fields already on the form as well as dragging and dropping new fields into the Section but nothing will go into it. WhatRecord Logged in User while using CRM lookup field
Is it possible, while using the Zoho CRM lookup field, to automatically use the user account logged into Zoho CRM in a hidden field? I was hoping to add employee accounts to my current plan. But would like a record on the Form submission of who submittedForm Rules for Suburb Categories to alternate landing pages or Making a Fields Contents ALL CAPS
I need to send differentform submissions to two to three different thank-you URLs (for Meta/Google pixels) depending on which suburb a user selects in a form. I have ~400 suburbs split into two categories (A and B, based on business value). Current challenges:Collaps Notes
There are times when long/large notes are added to a record i.e. Accounts or Deals etc. Currently, the full note is displayed in the notes related list section. It would be great if by default only 5 to 10 rows of the note are displayed when the noteZoho Down
I have a drop in my Zoho One services.Runing RPA Agents on Headless Windows 11 Machines
Has anyone tried this? Anything to be aware of regarding screen resolution?Problem for EU users connecting Zoho CRM through Google Ads for Enhanced conversions
Has anyone else experienced this problem when trying to connect Zoho CRM through Google Ads interface to setup enhanced conversions? Did you guys get it fixed somehow? The Problem: The current Google Ads integration is hardcoded to use Zoho's US authenticationNext Page