Kaizen #16 - Python SDK

Hello everyone!

Welcome back to another week of Kaizen!

This week, we will discuss the Python SDK.

What is the Python SDK for Zoho CRM?

Python SDK allows you to create client Python 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 Python Application.

What can you do with the Python SDK?

Exchange data between Zoho CRM and the client application where the CRM entities are modelled 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

Client app must use Python 2.7 or above. You can download Python through https://www.python.org/downloads/
Client app must have python requests installed. Refer to Installation of Python Requests or use the command pip install requests to install them.

How to Start using the Python SDK?

Follow the below steps:

Step-1: Register your application (Self Client or Web-based client)
Step-2: Install the SDK
Step-3: Import the SDK in your project
Step-4: Initialize the SDK
4.a. Choose the token persistence method
4.b. Setup the configuration dictionary
4.c. Generate the tokens
Step-5: 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

You can install the Python SDK through pip. Pip is a tool for dependency management in Python.

Refer to https://pip.pypa.io/en/stable/installing/ to install pip.

To install the SDK, run the below command in your Python IDE.

pip install zcrmsdk

This command installs the Python and creates a package named zcrmsdk in the installation directory of python (Example: '/Library/Python/2.7/site-packages').

Note

You must also have the Python requests installed. Run the command pip install requests to install them.

Step-3: Import the SDK in your project

Use the below statement in your IDE to import the downloaded SDK in your code.

import zcrmsdk

You can also set an alias for the imported SDK module. Run the below command to import the SDK in a custom name.

import zcrmsdk as your_custom_name

Note that you must use this name while referencing to any class in the SDK.

Example:

import zcrmsdk as my_zoho_sdk

my_zoho_sdk.ZCRMRestClient.initialize(config)

Step-4: Initialize the SDK

Initializing the SDK involves the following steps.

Step 4.a - Choosing the token persistence method
Step 4.b - Setting up the configuration dictionary
Step 4.c - Generating the tokens

4.a. Token Persistence

Your application should retain tokens (grant, access, and refresh tokens) to automate the process of data sync between your python application and Zoho CRM.

You can persist (store) the tokens in three ways.

MySQL Persistence (default)
File Persistence
Custom DB Persistence

4.a.1. MySQL Persistence

When you want to store the tokens in the MySQL DB, run the below command to install the necessary package.

pip install mysql-connector

In this case, 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 (The default port is 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).

4.a.2. File Persistence

If you want to store the tokens in a file, you can create a file named zcrm_oauthtokens.pkl and provide the absolute path of the directory containing this file in the below key of the configuration array.

"token_persistence_path": "path_to_the_folder_containing_the pkl_file"

If you do not create this file, the SDK itself creates this file in the path you have specified, and persists the tokens there.

Note: This method is recommended only for self client apps.

4.a.3. Custom DB Persistence

To use custom DB persistence, you must

Implement AbstractBaseClass (AbstractZohoOAuthPersistence from OAuthClient.py), and write a custom implementation of the following functions:
get_oauthtokens(user_email)
save_oauthtokens(oauthtokens)
delete_oauthtokens(user_email)

Include the following keys in the configuration dictionary, along with other mandatory keys.

"persistence_handler_class": "ClassName of the custom implementation",

"persistence_handler_path": "Absolute path of the module (.py file)"

4.b. Configuration dictionary

The below table 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	mysql_username	persistence_handler_class
--	mysql_password	persistence_handler_path
--	mysql_port	--
currentUserEmail	currentUserEmail	currentUserEmail

Optional keys

File Persistence	MySQL Persistence	Custom DB Persistence
applicationLogFilePath	applicationLogFilePath	applicationLogFilePath
sandbox	sandbox	sandbox
access_type	access_type	access_type
accounts_url	accounts_url	accounts_url
apiBaseUrl	apiBaseUrl	apiBaseUrl
apiVersion	apiVersion	apiVersion

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 path to store the OAuth tokens in the file. This key is mandatory if you want to use file persistence. If you include this key, this method takes precedence over other persistence methods.
mysql_username, mysql_password, mysql_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_path - Absolute path of the module (.py file). This key is mandatory if you want to use custom persistence.
applicationLogFilePath - The absolute path to log the exceptions during the usage of the SDK.
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 to offline as the SDK does not support online OAuth client, now.
accounts_url - The domain-specific accounts URL from which you generate the tokens.
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
apiBaseUrl - 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
apiVersion - Represents the version of the CRM APIs. The value is v2.
currentUserEmail - The email ID of the current user. When you do not specify this value, the SDK throws an exception. This key is mandatory in the configuration dictionary for self-client apps.

For web-based apps, set the user Email ID in the current thread as an attribute.

threading.current_thread().setattr('current_user_email','user@email.com')

Below is a configuration dictionary with all the keys.

config = {

"apiBaseUrl":"https://www.zohoapis.com",

"apiVersion":"v2",

"currentUserEmail":"email@gmail.com"

"sandbox":"False"

"applicationLogFilePath":"",

"client_id":"1000.3xxxxxxxxxxxxxxxxxxxxxxxxX0YW",

"client_secret":"29xxxxxxxxxxxxxxxxxxxxxxxxxxxxx7e32",

"redirect_uri":"https://www.abc.com",

"accounts_url":"https://accounts.zoho.com",

"token_persistence_path":"/Users/Zoho/Desktop/PycharmProjects",//For File Persistence

"access_type":"offline",

//Use the below keys for MySQL DB persistence

"mysql_username":"",

"mysql_password":"",

"mysql_port":"3306",

//Use the below keys for custom DB persistence

"persistence_handler_class" : "Custom",

"persistence_handler_path": "/Users/Zoho/Desktop/PythonSDK/CustomPersistance.py"

}

Now that you have created and registered your app with Zoho, you must authenticate it.

Pass the configuration dictionary in the method ZCRMRestClient.initialize(config) and authenticate your app.

4.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 with an access token.

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

Log in to Zoho and 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.

zcrmsdk.ZCRMRestClient.initialize(config)

oauth_client = zcrmsdk.ZohoOAuth.get_client_instance()

grant_token = "paste_grant_token_here"

oauth_tokens = oauth_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-5: Connect to Zoho CRM through the available methods

The below image shows the sample code to get the current user details. You can find the code for this sample in the attachment.

The below image contains the response to the above code.

We hope you found this post useful. Stay tuned for more!

Cheers!

Access your files securely from anywhere

Zoho Developer Community

New to Zoho LandingPage?

Access Zoho LandingPage

Zoho LandingPage Resources

New to Zoho Survey?

Access Zoho Survey

Latest Feature Updates

Explore our Pricing & Plans

Zoho Survey Resources

Android Mobile Surveys

Insurvey Blogs

Insight Blogs

Tips & Tricks

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Bigin?

Signup Now

Access Bigin

Latest Feature Updates

Zoho Desk Resources

Desk Community Learning Series
Digest
Functions
Meetups
Kbase
Resources
Glossary
Desk Marketplace
MVP Corner
Word of the Day

Tout forum

France ZUGs

Zoho SalesIQ Resources

Topic Participants
Shylaja S

Sticky Posts
Kaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provide
Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
Extension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use API
Kaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved
Extension pointers for integrating Zoho CRM with Zoho products #8: Upload and manage Zoho Workdrive folders and files from within Zoho CRM
Keeping records on your customers and business prospects is essential for tracking data, conducting follow-ups, and running a business smoothly. When you use two separate applications, and store relevant data in each, checking and tracking data becomes