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
How can I sync from Zoho Projects into an existing Zoho Sprints project?
Hi I have managed to integrate Zoho Projects with Zoho Sprints and I can see that the integration works as a project was created in Zoho Sprints. But, what I would like to do is to sync into an existing Zoho Sprints project. Is there a way to make thatCan we generate APK and IOS app?
Dears, I want to know the availability to develop the app on zoho and after that .. generate the APK or IOS app and after that I added them to play store or IOS store.. Is it possible to do this .. I want not to use zoho app or let my customers use it. thanksZoho Subform Workflows onAdd of Row
Suppose I have a form with attached workflows onLoad. If I use the form as a subform, will it inherit the workflows or do I need to create new ones onAdd of row?Super Admin removal
I brought a sub, and I gave the Super admin rights to a person who is no longer with us, so I need to change, and I need to make myself the Super adminBetter Notes Commenting
Hi, I'd like to suggest better collaboration tools for NOTES. The current notes section for Accounts, Contacts and Deals is not ideally suitable for any degree of communication or collaboration. When responding to a note, there is no ability to leaveExporting Templates
I have just spent 2 hours creating a project template for a Netsuite configuration, and want to share it with other Zoho Projects users - who have a different account. Is there any way to do this?Power of Automation:: Streamline Associated Teams based on the Task Owner update.
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:No Response from Zoho Support in 8 Days - Typical?
I have a couple of issues I'm trying to work through. Initially, I was getting support from support@zohofsm.com, but I have not received a response in 8 days (11 on another question). Is this typical? Can I pay for support? For context, I am not spammingAdd QUOTE OWNER profile image to a Quote Template
I can add their email address.. phone number, DOB. I need to add a users profile picture so when they assign a template to a quote they own it adds their picture to the cover page. I've tried hacking a solution together but there has to be an easier way.Zoho Connections Desk API relative URL PATTERN_NOT_MATCHED
While i am trying to do this: async function fetchTicketsFromDesk(timeFilter = 'current_month') { try { const response = await ZOHO.CRM.CONNECTION.invoke("desk_connection", { url: "/api/v1/tickets", method: "GET", }); const data = response.details ? JSON.parse(response.details)Zoho CRM - Custom Views for Portal Users
I'm looking for an option to customise custom views for portal users in CRM. It would be great if "portal user" was a permission on custom views.【参加無料】10/17(金) 東京 ユーザ交流会 Vol.3 参加登録 受付開始！
ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 10/17(金)に、東京・新橋で「東京 ユーザー交流会 Vol.3」を開催します！ 今回のユーザー事例セッションのテーマは、「Zoho Flowを活用した他社の決済サービスとの連携事例」です。 さらに、Zoho Flowに限らず、Analytics や Campaigns などの多彩なZohoサービスの活用方法について、豊富なご経験をもとにご紹介いただきます。 また、Zoho社員セッションでは、Zoho CRMを活用して日々の営業業務を効率化する具体的な事例をお話しします。業界を問わず、幅広い方にご参考いただける内容となっています！Zoho Meeting Plug compatibility with newer versions of Outlook
Documentation states that the zoho meeting plug in for outlook is only compatible with versions up to Outlook 2019 What is available to users of more up to date versions of outlook/office 365?Introducing Zoho's own SMS gateway
We're thrilled to announce the launch of our own SMS gateway feature within Zoho Marketing Automation! This new feature enables seamless SMS campaign management alongside your email marketing initiatives, providing a more integrated and efficient wayEmbedding in Desk articles
We would like to embed documents in our Desk articles. When we use an iframe for the embed, we get scrollbars and a frame border. Neither of those is acceptable. I've spoken with the Desk Support team about what we want and they tell me that it cannotZoho CRM button to download images from image upload field
Hello, I am trying to create a button in Zoho CRM that I can place in my record details view for each record and use it to download all images in the image upload fields. I tried deluge, client scripts and even with a widget, but feel lost, could notMass Update Contacts In Zoho Campaigns
Is there a way to mass update contacts in zoho campaigns? I want to be able to change the content of a field for a few hundred contacts, and can't go through all of them individually.report showing assignment type
Hi, We've created a number of workflows to allow us to auto assign tickets to agents based on keywords and other criteria. I'm struggling to create a report that would show me what is the percentage of tickets that are assigned automatically via workflowsOption to Disable Knowledge Base Section in Feedback Widget Popup Hello Zoho Desk Team
Hello Zoho Desk Team, How are you? We are actively using Zoho Desk and would like to make more use of the Feedback Widget. One of the ways we implement it is through the popup option. At the moment, the popup always displays the Knowledge Base section,Placeholders in Ticket Templates
We should be able to use placeholders in ticket templates. When we create a new ticket, our description field is shown to the client in the email they receive. It would be very handy to be able to personalize that description field in our ticket templates to pull in the name of the client that the ticket is for. Using them in the subject field as well, so we can auto populate Account Names, etc.when the record is created the tag want to Show as Opportunity how i achive this using Deluge Script
In the quotation i have the work flow schedule for create opportunity record in the module , on that time the quotation tag select as opportunity created. How i achive this using Deluge Script . this like i want to Do tag1 = Map(); tag1.put("name","NurturingDelete a channel
I need delete a channel in tickets.Subtasks don't update parent task's times
Hi there: I've recently upgraded to premium and check that subtasks completion % don't update the proportional completion of the parent tasks related to it. We've been challenging with the problem of having to update twice or sometimes 3 times the completion of the related tasks. I've seen posts similar to this, of 3 years old. Is there any roadmap for making this happen in a future release? Thanx César Ratto Lima, Perú.IMAP Server not responding.
Trying to connect a phone via IMAP and getting "imap.zoho.com not responding." Is the server down, for maintenance or otherwise? I've tried this on two different devices and got the same error on both.Tip #44 – Get Deeper Insights with Zoho Assist’s Custom Reports – ‘Insider Insights’
In today’s fast-paced IT environment, having a clear view of your remote support activities is more important than ever. Zoho Assist’s Custom Reports feature gives IT teams the ability to generate tailored reports that provide actionable insights andIssue with SalesIQ Visitor Identification on WordPress
Hi Zoho Support Team, I need some help with an issue on my WordPress website. My goal is to automatically identify logged-in WordPress users in Zoho SalesIQ, so I can see their name and email in the visitor list. Currently, my logged-in users are stillMessage "...does not support more than 100 distinct values..." WHY????
I get this message on one of my reports: Sorry, Zoho Reports currently does not support more than 100 distinct values in columns. 'Account Name * Sum(Amount),Count(Amount Tier)' contains more than 100 distinct values. Possibly, you can apply filter to reduce the number of distinct values in 'Account Name' or drop the 'Account Name' field in Rows. I want to list all ACCOUNT NAMES (about 500) with SALES BY ACCOUNT. What is blocking this?Let's Talk Recruit: Super-charge hiring with Zoho Recruit add-ons
Welcome back to our Let’s Talk Recruit series! This time, we’re diving into something that might seem like a small upgrade but has a huge impact on recruiter productivity: Zoho Recruit add-ons. Think about how much of your day is spent in your inbox orVendor Signatures Needed for Purchase Orders
Hello everyone, We have a unique requirement that necessitates that Vendors & Suppliers formally acknowledge our Purchase Orders upon receipt. I was hoping that there would be an option to do so in Zoho Books, but that does not appear to be the case.Store "Sign in with Google/Microsoft/GitHub etc." details
Quite often now, users are using a sign-in provider like Google or Microsoft to sign into various apps and services. It would be great if Vault could remember which providers you use for each website and sign you in with that provider instead of a usernameTip of the Week #72– Assign thread ownership to avoid confusion.
When teams handle a large volume of emails, managing threads becomes important to stay organized. Without a clear system, duplicate replies, missed follow-ups, or confusion over responsibilities can happen. Thread assignment solves this by designatingUnarchive tickets
How can I manually unarchive tickets?Optimize your Knowledge Base for enhanced accessibility by adding alt tags for images
Let's learn why alt tags are crucial for your articles. You can add alternative tags (alt tags) and alternative text (alt text) to the images you share on your community forums or when embedding them in articles. Alt tags refer to the HTML attribute,FSM trying again
have not linked FSM yet to the rest of out Zoho suit. It certainly looks like the apointment and service part is more manageable for our staff. The question is that our engineers multi task examples 1. deliver products to customers not fitted 2. ServiceFeature Request: Conditional Field Mandatoriness Based on Display Status
Hello Zoho Creator Team, I would like to suggest an enhancement to improve the flexibility of form validations. Currently, when we need a field to be mandatory only if it's displayed on the form, the only option is to: Set the field as not mandatory inData Migration Strategies for Moving to a Cloud Solution
Hi everyone, I’ve been working on moving some of our critical systems, including CRM and project data, to a Zoho cloud solution, and one of the biggest challenges I’ve encountered is data migration. Transferring large volumes of data while keeping itCommerce Order as Invoice instead of Sales Order?
I need a purchase made on my Commerce Site to result in an Invoice for services instead of a Sales Order that will be pushed to Books. My customers don't pay until I after I add some details to their transaction. Can I change the settings to make thisHow to set different item selling prices for Zoho Commerce and Zoho Books
Item selling prices for Zoho Commerce and Zoho Books are in sync. If we update the Item selling price in Books, the same will happen in commerce and vice versa. I need a separate commerce selling price for online users and a separate books selling priceHow to report 'Response violation' OR 'Resolution violation'
Hi, I want to report on SLA Violation Type. I grouped my tickets on this column. It seems I only get 'Response and Resolution Violation' or 'Not Violated'. The former seems to be given to a ticket if only the Response Time was violated. I would expectEnable Keyword-Based Bot Activation in SalesIQ Without Scripts
Hello team, We’d like to highlight an important limitation in Zoho SalesIQ Zobot. Current situation: In the no-code builder, bots can only be activated based on visitor attributes (country, page, campaign, CRM, etc.). If we want a bot to activate whenNext Page