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. Provide “aaaserver.profile.READ” scope along with Zoho CRM scopes.
- Copy the grant token that is displayed on the screen.
Note
- 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.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 following code
require 'ZOHOCRMSDK2_0'
class Initialize
def self.initialize()
# Create an instance of Log::SDKLog Class that takes two parameters
#1 -> Level of the log messages to be logged. Can be configured by typing Levels "::" and choose any level from the list displayed.
# 2 -> Absolute file path, where messages need to be logged.
log = ZOHOCRMSDK::SDKLog::Log.initialize(level:Levels::INFO, path:"/Users/user_name/Documents/rubysdk_log.log")
#Create an UserSignature instance that takes user Email as parameter
user_signature = ZOHOCRMSDK::UserSignature.new('abc@zohocorp.com')
# Configure the environment
# which is of the pattern Domain.Environment
# Available Domains: USDataCenter, EUDataCenter, INDataCenter, CNDataCenter, AUDataCenter
# Available Environments: PRODUCTION, DEVELOPER, SANDBOX
environment = ZOHOCRMSDK::DC::USDataCenter.PRODUCTION
#Create a Token instance
#1 -> OAuth client id.
#2 -> OAuth client secret.
#3 -> grant token
#4 -> refresh token
#5 -> OAuth redirect URL.
#6 -> id
token = ZOHOCRMSDK::Authenticator::OAuthToken.new(client_id: "clientId", client_secret:"clientSecret", grant_token:"grant_token", refresh_token:"refresh_token", redirect_url:"redirectURL", id:"id")
#Create an instance of TokenStore.
#1 -> DataBase host name. Default "localhost"
#2 -> DataBase name. Default "zohooauth"
#3 -> DataBase user name. Default "root"
#4 -> DataBase password. Default ""
#5 -> DataBase port number. Default "3306"
tokenstore = ZOHOCRMSDK::Store::DBStore.new(host: "host_name", database_name: "database_name", table_name: "table_name", user_name: "user_name",password: "password", port_number:"port_number")
#tokenstore = ZOHOCRMSDK::Store::FileStore.new("/Users/user_name/Documents/ruby_sdk_token.txt"
# 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 (Util::ModuleFieldsHandler)
#
# pickListValidation
# if true - value for any picklist field will be validated with the available values.
# if false - value for any picklist field will not be validated, resulting in creation of a new value.
#
# open_timeout
# Number of seconds to wait for the connection to open (default 60 seconds)
#
# read_timeout
# Number of seconds to wait for one block to be read (via one read(2) call) (default 60 seconds)
#
# write_timeout
# Number of seconds to wait for one block to be written (via one write(2) call) (default 60 seconds)
#
# keep_alive_timeout
# Seconds to reuse the connection of the previous request(default 2 seconds)
#
sdk_config = ZOHOCRMSDK::SDKConfig.new(auto_refresh_fields: false, pick_list_validation: true, open_timeout: 60, read_timeout: 60, write_timeout: 60, keep_alive_timeout: 2)
resource_path = "/Users/user_name/Documents/rubysdk-application"
# Create an instance of RequestProxy class that takes the following parameters
# 1 -> Host
# 2 -> Port Number
# 3 -> User Name
# 4 -> Password
request_proxy = ZOHOCRMSDK::RequestProxy.new(host:"proxyHost", post:"proxyPort", user_name:"proxyUser", password:"password")
# The 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 -> resourcePath - A String
# 7 -> Log instance (optional)
# 8 -> RequestProxy instance (optional)
#The following is the initialize method
ZOHOCRMSDK::Initializer.initialize(user: user_signature, environment: environment, token: token, store: tokenstore, sdk_config: sdk_config, resources_path: resource_path,log:log,request_proxy: request_proxy)
end
end
You can now access the functionalities of the SDK. Refer to the sample codes to make various API calls through the SDK.