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
Unable to Edit Pick-List Items in Custom Project Field(s)
I can edit most fields normally, but if I try to edit - in any way - a Pick List field, I just get this error: To be perfectly clear, I'm trying to edit an existing Pick List field (adding or removing items), not adding a new instance. If I rename it,How to display results from zoho.crm.searchRecords in message window
Hello, I've created a custom function which is linked to a custom button which pulls a date from our contacts module and searches a date field in our quotes module and returns all records matching the date. My issue is, how to I get this to display theDomain Transfer
Hello there! I wanted to know if I can transfer my domain from Zoho to other hosting providers or use a different hosting provider instead of zoho's services.New User - Opening Stock Aging Report
I am setting up new client and am entering Opening Stock - created items and entered quantity/price details. Now the aging report is showing all the opening stock as new. How do I enter the Purchase Dates of these items so that I get accurate InventoryBulk Receive Multiple Purchase Orders
Is there a feature or function that will allow you to bulk receive issued purchase orders? I have about 100 that need to be received from 5 years ago.Manual Invoice
How to create a Manual invoice, I need to enter Amount directly instead of (qty*Rate). our company is a service sectorMerging contacts and or accounts
Hello, In a prior CRM we were able to merge contacts and or accounts. We have turned on the function to stop multiple contacts with the same email, so we can prevent multiple contacts from happening, however, we now have multiple contacts that have theCapture Reason for absence next to Campaign Member Status. Is there a reasonable workaround?
I've reviewed the topics I could find to do with this but still couldn't find anything that satisfies our requirements: We would like to track a *reason* (picklist or text, doesn't matter which) why a Campaign Member (Lead or Contact associated with aButton or Links order
Is there a way to re-order the buttons or links that are created?'Pin' notes, so that specific ones are always visible at the top of the 'notes' tab.
It doesn't appear Bigin has the functionality to 'pin' a note to then have it always show at the top of the notes tab section of a record. Often times we have a large number of records, but key information we may want to have easily visible to all atRequest for Subform Support in Zoho CRM Webforms
Hi Team, I hope you're doing well. I would like to bring to your attention that currently, Zoho CRM Webforms do not support Subforms, which limits our ability to send forms that mirror the actual structure used within Zoho CRM. This feature is extremelyMaxima Address on FSM Customer
Im trying to add probably 50 customers from one company but couldn't make it since it has limit..how do i add the limit?View subform entries without viewing a record in Zoho CRM | Kiosk Studio Session #8
In a nutshell Have you ever wanted to take a quick peek at a record's subform? Examples might be invoiced items in an invoice, ordered items in a sales order, or purchased items in a purchase order. Let's say you're viewing your list of invoices in ZohoTransforma tu Inventario: Control Inteligente y Funciones Clave en Zoho Inventory (Spanish Webinar)
¿Tu empresa necesita mayor trazabilidad y control en almacenes? Conoce cómo gestionar tu inventario con eficiencia y automatización... ¡y descubre las sorpresas que trae Zoho Analytics! Participa en nuestro webinar gratuito en español, este 19 de agostoMails are not being sent from custom Deluge function
We are having troubles to implement sending Invoices / Sales_Orders etc. automatically using following deluge script: attachment_template_id = "aaaa"; record_id = "bbbb"; mail_template_id = "cccc"; //NEW aproach fileUrl = "https://www.zohoapis.com/crm/v8/settings/inventory_templates/"Currency transition
We are using Zoho CRM in Curacao, Dutch Caribbean. Our currency is currently the ANG. Curacao will be transition ing from using the ANG (Antillean Guilder) to using the XCG currency (Caribbean Guilder) on March 31st 2025, see: https://www.mcb-bank.com/caribbean-guilder.Notes and Attachments visibility can now be restricted based on profiles
Dear All, We hope you're well! We are here with a quick update about Notes and Attachments profile permissions. In the past, a record's Notes and Attachments were visible by default to all users with record access. However, as notes and attachments canZoho webinar--hard for agencies
So, this is just a dive into our use case, and why we've been disappointed in Zoho webinar. We are a small marketing agency, and we wanted to add webinars to the services we provide, as many of our clients want to learn to use them as part of their contentCelebrating Raksha Bandhan with Zoho Desk: A Bond of Trust, Protection, and Service
Raksha Bandhan, celebrated across India, symbolizes the sacred bond of protection and affection between siblings. “Raksha” means protection, “Bandhan” means bond or knot: together, it represents a knot of care and security. On this occasion, we'd likeCreate project (flow) and assign to person without account (company)
Hi Zoho Support & Community, I'm trying to automate a process using Zoho Flow to create a Zoho Project and link it directly to a Zoho CRM Contact. This reflects our B2C workflow where we primarily deal with individual Contacts, not Companies/Accounts.Banking > Import statements with a csv file
Good morning, I am regularly using the "import statement" option to match my transactions. I've been using csv files produced by my bank online and was able to import my transactions. Until now. Thank you for your help for fixing this ! Alex.Has anyone successfully added Microsoft Graph API Oauth2 as a connection?
I'm having trouble getting Microsoft Graph API created as a connection in zoho crm. Has anyone successfully added Microsoft Graph API Oauth2 as a connection? My issue is not necessarily on the Zoho side, but understanding how to set up the Microsoft sideSyncing Timesheets between Projects and Desk
All users able to see their own timelog entries from all apps in one place, synced immediately. All managers able to view total/all time entries from one place. This is something that has come up for us and multiple clients. Example: we have a clientSpell Check default language
Hello All, Is it possible to set the Spell Check default language? I can't find it in the settings. Thanks a lot! LeventeZoho Backstage 3.0 - Boostez vos événements avec des outils malins
Zoho Backstage vous accompagne dans l’organisation d’événements réussis, avec des outils qui simplifient la planification, optimisent l’exécution et renforcent la connexion avec votre public. La version 2.0 a apporté une nouvelle interface, plus de flexibilitéPortal user activity reporting
Aside from the metrics section in the admin dashboard, is there a way to view/create reports for portal user activity? Im looking for a more granular option to see exactly what users are utilizing the portal. Thanks!Admins to set Agents Picture
Admins should not have to rely on agents to set a nice profile picture for them. Admins get the headshot pictures from HR and should be able to upload and set their picture, not rely on them to: 1) upload a picture at all 2) upload a good picture 3) uploadTime Tracking Reporting and Billing
I wish for the time tracking module to be enhanced further. Currently it is independent of Support Plans and Contracts. Support Plans and Contracts are also mostly separate. We need a better dashboard of this with the ability to natively mark billed orEnhanced Email Signature Folding
We have departmental signatures setup which are great, however, when viewing ticket details, it gets very overwhelming when scrolling though threads and conversations where you scroll past ten different signatures of your own team, then ten signaturesHow to add formatting in zoho.cliq.postToUser(...) message?
In a CRM Deluge function, I'm trying to use the message formatting guidelines given here: https://www.zoho.com/deluge/help/cliq/posting-to-zoho-cliq.html#message-formats My message is: message: #Title text. The result in Cliq is: #Title text. (no largeZia Agents/End of Day Reports
As a manager or owner it would be nice if Zia analyzed today's (or this week's tickets) and gave an end of the day report to management team. - what important tickets were worked on or submitted today? - what agents were unproductive today and answeredProject Cost Tracking
I see there are questions/concerns that Zoho doesn't track costs to a tasks in a project. We are a manufacturer and are in the early stages of tracking costs to project. I would like to expand out the COGS Chart of accounts in Books and record costs viaHow to record if the payment made is return due to transaction failed.
So there is Bill of $2000, and a payments made transaction to clear the bill. The amount is actually deducted from bank account. However, a few days later, I found the bank returned only $1750 cause there are $250 bank service charge for this failed transaction.Help Center Customization UI
The customization screens for the help center needs the UI improved. It looks straight out of 2004. The Zoho Desk normal UI is great. All it takes is uniform fonts and colors across all parts of the tool... I compare this to Zendesk Guide.Este domínio já está associado a esta conta
Fui fazer meu cadastro na zoho e quando digitei meu domínio recebi essa mensagem que meu domínio estava associado a uma conta que eu nem faço idéia de quem seja. Como que faço pra resolver isso? Atenciosamente, Anderson Souza.I need some help in Expenses Per Diem Policy
this is my script written for restricting the PerDiem Components. Say if Lodging and Per Day Allowance both is selected from Per Diem Page then the report should gets auto rejected. When Im trying to executing it says the following error {"code":11,"message":"TheAdding Photos to Dashboards on Zoho Analytics
I am creating a dashboard to showcase data from survey results from focus groups. I am creating a focus group participant profile tab where it is filtered by the name of the participant and showcases information about them using KPI widgets. I am runningWhat is the difference between Retainer invoice and Advance Payments?
Retainer invoice seem like they are just advance payments with extra details. Instead of creating a Sales Order with order details, a retainer is created. It feels like they are a workaround to link advance payments with sales orders. Is there any advantageExporting record notes in bulk
Hi team, Is it possible to bulk export the notes attached to a record? i.e to a CSV file or otherwise. Our use case is exporting all notes for our lead/account/Deal records. We have another system we'd like to import these notes to but I can't seem toField customization
Hi Team Good day! I am a commission agent who sell and purchase goods from vendors, while in purchasing invoices I am not able to deduct the expenses such as commission and other expenses on actual amount. Kindly help me to customize the invoice basedNext Page