Initializing the Application
To access the CRM services through the SDK, you must first authenticate your client app.
Generating the grant token
For a Single User
The developer console has an option to generate grant token for a user directly. This option may be handy when your app is going to use only one CRM user's credentials for all its operations or for your development testing.
- Login to your Zoho account.
- Visit https://api-console.zoho.com
- Click Self Client option of the client for which you wish to authorize.
- Enter one or more (comma-separated) valid Zoho CRM scopes that you wish to authorize in the "Scope" field and choose the time of expiry.
- Copy the grant token that is displayed on the screen.
- The generated grant token is valid only for the stipulated time you chose while generating it. Hence, the access and refresh tokens should be generated within that time.
- The OAuth client registration and grant token generation must be done in the same Zoho account's (meaning - login) developer console.
For Multiple Users
For multiple users, it is the responsibility of your client app to generate the grant token from the users trying to login.
- Your Application's UI must have a "Login with Zoho" option to open the grant token URL of Zoho, which would prompt for the user's Zoho login credentials.
- Upon successful login of the user, the grant token will be sent as a param to your registered redirect URL.
The access and refresh tokens are environment-specific and domain-specific. When you handle various environments and domains such as Production, Sandbox, or Developer and IN, CN, US, EU, or AU, respectively, you must use the access token and refresh token generated only in those respective environments and domains. The SDK throws an error, otherwise.
For example, if you generate the tokens for your Sandbox environment in the CN domain, you must use only those tokens for that domain and environment. You cannot use the tokens generated for a different environment or a domain.
You must pass the following details to the SDK and initialize it before you can make API calls.
UserSignature - The email ID of the user that is making the API calls. The tokens are also specific to this user.
Environment - The environment such as Production, Developer, or Sandbox from which you want to make API calls. This instance also takes the domain (data center) in which the tokens are generated. The format is USDataCenter.PRODUCTION(), EUDataCenter.SANDBOX() and so on.
Token - The grant or refresh token. The token must be specific to the user that makes the call, and specific to the org and the environment the token was generated in.
Besides the token, the token instance also takes the client ID, client secret, and the redirect URI as its parameters.
Tokenstore - The token persistence method. The possible methods are DB persistence, File persistence and Custom persistence. For file persistence, you must specify the absolute file path to the file where you want to store the tokens. For DB persistence, you must specify the host, database name, user name, password and the port at which the server runs. For Custom persistence, you must provide the instance of the class that implements TokenStore (Abstract Base Class) and overrides the methods
Logger - To log the messages. You can choose the level of logging of messages through Logger.Levels, and provide the absolute file path to the file where you want the SDK to write the messages in.
SDKConfig - The class that contains the values of autoRefresh and pickListValidation fields.
resourcePath - The absolute directory path to store user-specific files containing information about the fields of a module.
RequestProxy - An instance containing the proxy details of the request.
Initialization of the SDK happens through the Initializer class. This class contains instances of the current user, environment, token, tokenstore, and logger.
Initializing the SDK does not generate an access token. An access token is generated only when you make an API call.
Initialize the SDK using the following code.
from zcrmsdk.src.com.zoho.crm.api.user_signature import UserSignature from zcrmsdk.src.com.zoho.crm.api.dc import USDataCenter from zcrmsdk.src.com.zoho.api.authenticator.store import DBStore, FileStore from zcrmsdk.src.com.zoho.api.logger import Logger from zcrmsdk.src.com.zoho.crm.api.initializer import Initializer from zcrmsdk.src.com.zoho.api.authenticator.oauth_token import OAuthToken, TokenType from zcrmsdk.src.com.zoho.crm.api.sdk_config import SDKConfig from zcrmsdk.src.com.zoho.crm.api.request_proxy import RequestProxy class SDKInitializer(object): @staticmethod def initialize(): """ Create an instance of Logger Class that takes two parameters 1 -> Level of the log messages to be logged. Can be configured by typing Logger.Levels "." and choose any level from the list displayed. 2 -> Absolute file path, where messages need to be logged. """ logger = Logger.get_instance(level=Logger.Levels.INFO, file_path='/Users/user_name/Documents/python_sdk_log.log') # Create an UserSignature instance that takes user Email as parameter user = UserSignature(email@example.com') """ Configure the environment which is of the pattern Domain.Environment Available Domains: USDataCenter, EUDataCenter, INDataCenter, CNDataCenter, AUDataCenter Available Environments: PRODUCTION(), DEVELOPER(), SANDBOX() """ environment = USDataCenter.PRODUCTION() """ Create a Token instance that takes the following parameters 1 -> OAuth client id. 2 -> OAuth client secret. 3 -> REFRESH/GRANT token. 4 -> token type. 5 -> OAuth redirect URL. """ token = OAuthToken(client_id='clientId', client_secret='clientSecret', token='REFRESH/ GRANT Token', token_type=TokenType.REFRESH / TokenType.GRANT, redirect_url='redirectURL') """ Create an instance of TokenStore 1 -> Absolute file path of the file to persist tokens """ store = FileStore(file_path='/Users/username/Documents/python_sdk_tokens.txt') """ Create an instance of TokenStore 1 -> DataBase host name. Default value "localhost" 2 -> DataBase name. Default value "zohooauth" 3 -> DataBase user name. Default value "root" 4 -> DataBase password. Default value "" 5 -> DataBase port number. Default value "3306" """ store = DBStore() store = DBStore(host='host_name', database_name='database_name', user_name='user_name', password='password',port_number='port_number') """ auto_refresh_fields if True - all the modules' fields will be auto-refreshed in the background, every hour. if False - the fields will not be auto-refreshed in the background. The user can manually delete the file(s) or refresh the fields using methods from ModuleFieldsHandler(zcrmsdk/src/com/zoho/crm/api/util/module_fields_handler.py) pick_list_validation A boolean field that validates user input for a pick list field and allows or disallows the addition of a new value to the list. if True - the SDK validates the input. If the value does not exist in the pick list, the SDK throws an error. if False - the SDK does not validate the input and makes the API request with the user’s input to the pick list """ config = SDKConfig(auto_refresh_fields=True, pick_list_validation=False) """ The path containing the absolute directory path (in the key resource_path) to store user-specific files containing information about fields in modules. """ resource_path = '/Users/user_name/Documents/python-app' """ Create an instance of RequestProxy class that takes the following parameters 1 -> Host 2 -> Port Number 3 -> User Name. Default value is None 4 -> Password. Default value is None """ request_proxy = RequestProxy(host='proxyHost', port=8080) request_proxy = RequestProxy(host='proxyHost', port=8080, user='userName', password='password') """ Call the static initialize method of Initializer class that takes the following arguments 1 -> UserSignature instance 2 -> Environment instance 3 -> Token instance 4 -> TokenStore instance 5 -> SDKConfig instance 6 -> resource_path 7 -> Logger instance. Default value is None 8 -> RequestProxy instance. Default value is None """ Initializer.initialize(user=user, environment=environment, token=token, store=store, sdk_config=config, resource_path=resource_path, logger=logger, proxy=request_proxy) SDKInitializer.initialize()