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
Error: Invalid Element gst_no, Invalid Element gst_treatment, Invalid Element place_of_contact
so i am creating a new contact post request and i want add gst infomation when amount is above 50000 and if pass gst info in request body then i get this errors > Error: Invalid Element gst_no, Invalid Element gst_treatment, Invalid Element place_of_contactAdd multiple Billing Addresses under one GST number
My client owns multiple businesses in various locations but they all come under one GST. Is there a way to add multiple billing addresses for the same GST? Managing this by adding multiple Shipping addresses is not an option. The client wants the GSTZoho Mail API - Upload Attachment
https://www.zoho.com/mail/help/api/post-upload-attachments.html I followed the steps from the API documentation and wrote a backend in JavaScript to send emails. Normal emails are sent without any problems. However, I can’t send emails with attachments.Unable to create custom fields for shipment order
I'm unable to create custom fields for shipment orders, even though the custom fields are set up correctly. A request to the following endpoint: https://www.zohoapis.com/inventory/v1/settings/preferences/customfields?organization_id=${ZOHO_ORGANIZATION_ID}&entity=shipment_orderKaizen #202 - Answering Your Questions | Testing and Using REST APIs in Widgets
Hello Developers! Welcome back to a fresh week of Kaizen! Thank you for your active participation in sharing feedback and queries for the 200th milestone. This week, we will look at the following queries related to widget: Widget Testing Using REST APIIntroducing the 'Send as Email' option on the Zoho Desk iOS mobile app
Hello everyone! In the latest version(v2.10.2) of the Zoho Desk iOS app, we have brought in support for the 'Send as Email' option while creating a ticket. This feature enables you to reach out to the customers by sending outbound emails. The emails areZoho Forms Not Loading on Website – DNS Resolution Error
Dear Zoho Support Team, User ID : 20069458731 We are experiencing an issue with the Zoho Form embedded on our website (https://vitel.com.tr/satis-destek-formu/). The form is not loading, and the following error message appears in the browser: “forms.zohopublic.euData backup retention question/
My zohocrm subscription gives me 2 full data backups per month. I have a scheduled backup configured to run twice a month. I just went to download my backup and i can't find it, it ran about 9 days ago... From what i can tell with google zoho only keepsBasic Apple Watch App
Sometimes I leave my phone behind. I will get push notifications that tickets are updated etc.. It would be nice to at least view them and do a few basic functions. reassign. public reply. private comment.Look and Feel Uniformity
Someone needs to go through the mobile app and match the look and feel of the web version. For example, it is global standard to highlight private notes as yellow background hue. Desk does that on web, but not on mobile. Mobile also has an odd blue iconManaging two books in Zoho Books
is it possible to effectively manage two separate books within Zoho Books? My organization is considering handling accounting for two distinct subsidiaries, and we would like to understand the best way to achieve this within the Zoho Books.Display All Custom Buttons Without Dropdown on Record Page
In my org's workflow we usually want to do some kind of quick action off of an individual record - i.e. of an individual contact, or individual deal. What we have always found a hindrance is the location of all custom buttons being in the drop down onZoho Sales Team - Extremely Slow Response Times
Hi everyone, Has anyone else experienced unusually slow response times from Zoho’s sales team? I sent an email last night, and it’s been nearly 24 hours with no reply. While I understand delays can happen, this seems longer than expected for a sales inquiry.Yodlee Bank Feeds
I'm well aware of the many bank feed issues out there that haven't been resolved, but I'm looking for information on Rules in relation to bank feeds. U.S based, Bank of America user and prior to Yodlee all of my banking feeds and Rules worked seamlessly.Unable to create custom function
Unable to create custom function - Please check the screenshot for the details HERE IS THE FUNCTION!! try { // 1. Fetch the details of the approved Bill using its ID billDetails = zoho.books.getRecordById("Bills", organization.get("organization_id"),Need a feature which can validate PAN from Income Tax Portal
Hello Zoho, We need a feature which can help us validate PAN which is being entered in AR/AP Profiles to check if it is valid and display the name as per Income Tax so as to get rid of incorrect PAN into the systems. Please do the needful ThanksPAN - Aadhar Link Status
Can Zohobooks also get latest PAN-Aadhar Linking Status from Income Tax Portal ?Canvas translation
We want to offer our CRM system to our users in English and Dutch. However, it seems that text in our deal Canvas isn't available for translation through the translation file. The same applies to the field tooltips. They don't appear in the translationAre Cadences visible to anyone with Cadence permission?
When setting up a new Cadence is it possible to restrict its use to a specific user? How can I prevent users from making modifications to existing Cadences?Show my cost or profit while creating estimate
Hi, While creating estimate it becomes very important to know exact profit or purchased price of the products at one side just for our reference so we can decide whether we can offer better disc or not .Issue on Upload API and href image URL
Here is my Full API Code , URL : URL: https://desk.zoho.com/api/v1/uploads/659563000000193003/content Headers* Authorization: 'Zoho-oauthtoken 1000.ed5ce2836bf5ba9b946f5ec9************88e73ff4883a3e9c58ffeb7870' orgId: 7586***** RESPONSE{ "errorCode":Issue when downloading a Mail Merged Zoho Writer Document as .docx
Hi, We are using within Zoho CRM mailmerge to create documents. This results in a Zoho Writer document. When we try to download as a Microsoft Docx file we get following error: "Word experienced an error trying to open the file. Try these suggestions.【Zoho CRM】ケイデンス機能のアップデート
ユーザーの皆さま、こんにちは。コミュニティチームの中野です。 今回は「Zoho CRM アップデート情報」の中から、ケイデンス機能のアップデートをご紹介します。 ケイデンス機能の2つの強化されたことで、適用と解除のタイミングをより柔軟に管理できるようになり、 よりタイムリーで的確なコミュニケーションが実現できるようになりました。 目次： 1. ケイデンスの再開／最初からのやり直し 2. ケイデンスからのデータ解除タイミングの設定 1. ケイデンスの再開／最初からのやり直し 手動削除、完了、または適用解除条件が満たされた場合など、以前に適用解除されたデータをケイデンスに再適用できるようになりました。Anyone get the OpenAI API to work in Zoho Meeting?
Has anyone been able to get the OpenAI API to work in generating meeting summaries? I have been trying, but I get an error that says "OpenAI key notes request rate exceeded. Please try again later or upgrade your open AI account." I contacted Zoho supportPush Notifications Customization
There is no way to customize the notifications we get. I would like to be able to get notifications based on if they are assigned directly to me, my team, my department, or perhaps tickets that match a specific criteria (a contact or account is a VIPAnnouncing Early Access to the next generation of Zoho Desk UI
Customer service is one of the categories where efficiency and quality of service have to run in parallel, and your team's experience with their helpdesk goes a long way ensuring these aspects are uncompromised. Introducing DOT Design for Zoho Desk -Editing the record in report
I have a use-case as below- User creates a assessment record by filling some fields. User assigns that record to portal user by using Assigned To dropdown (Assigned To is Users field in form with choices as customers). I have set the record owner of formCan we have Bills of Material Module ?
Can we have Bills of Material Module ?Main Ticket Page Customization
We do not love the ticket list page (right after clicking Tickets menu item) would like options to customize it.Agent Collision Missing from Mobile App
Please add Agent Collision capabilities to the mobile app.Zia Sentiment and Functionality on Mobile
Please add Zia sentiment and generative responses to the mobile app. It would be nice to see the ticket sentiment and generate a response back to a user using Zia on my iPhoneView Account Attachments on iOS
Please allow us to view account attachments on the mobile iOS app!How do I run a PnL by Sales Person?
I am trying to run a PnL by sales person but am not seeing the option do so. All I need to know (per salesperson) is revenue, cost of goods, gross profit.View Contracts and Support Plans on Mobile
We would like to be able to see contracts and support plans from the mobile app on iOS!Loan repayment Entry
While receiving loan, i does following steps in My Zoho books. 1. Create "Loan & Advance " Account as Parent Account under Long Term Liabilities. 2. Create another account For Example "Mr. ABC's Loan as Child account under the parent account. Now: InQuotes module send email reverted back into 2022??
Our Zoho CRM PLUS quotes, sales orders, invoice modules is showing us an email composer from 2022. We cannot send emails and its been a real pain. I tried clicking the new version over there but it doesnt seem to do anything. Any help is welcome. thWorkflow Condition - how do check that a date / time value is in the past?
Hello, I'm got a workflow that runs a function when records reach their 'Effective Date / Time', but sometimes records are created after the 'Effective Date / Time' so I have another workflow that checks for records which needs to be processed immediately.Pre filling SignForm field values by URL field alias's in Zoho Sign
Hi, Does anyone know if it's possible to pre fill the field values of the SignForm by using field alias's like you can in Zoho forms? To be more specific, I want to be able to change the SignForm URL to include some information like this: Before : https://sign.zoho.eu/signform?form_link=234b4d535f495623920c288fc8538cb9e6db03bbfd44499b63f3e5c48daf78f44bc47f333e2f5072cc1ee74b7332fe18b25c93fab10cb6243278d49c67eacbf30bbe5b6e1cc8c6b2#/How to Split Payout in Zoho Books (Without Using Journal?)
Hi, I'm trying to properly record payouts in Zoho Books. The issue is that each payout is a combination of sales and expenses (fees). When I try to categorise the payout transaction from the Banking tab, I can only split the transaction using income-typePayment Schedule
Please add the ability to create a payment schedule. The other options, like retainer invoices or two invoices, do not work for the customer. We invoice a client and need to be able to show them everything they owe in one invoice, and when each paymentNext Page