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 ADD CLIENT and choose the client type as Client-based application.
- 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.
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 token. An access token is generated only when you make an API call.
Initialization
You must pass the following details to the SDK and initialize it before you can make API calls.
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 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, scope, and the redirect URI as its parameters.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.
Initialize the SDK using the following code.
class SDKInitializer {
static async initializeSDK() {
/*
* Create an instance of Logger Class that takes parameter
* 1 -> Level of the log messages to be logged. Can be configured by typing Levels "." and choose any level from the list displayed.
*/
let logger = Logger.getInstance(Levels.ALL);
/*
* Configure the environment
* which is of the pattern Domain.Environment
* Available Domains: US, EU, IN, CN, AU
* Available Environments: PRODUCTION(), DEVELOPER(), SANDBOX()
*/
let environment = DataCenter.US.PRODUCTION();
/*
* Create a Token instance
* clientId -> OAuth client id.
* scope -> OAuth client scope.
* redirectURL -> OAuth Redirect URL.
*/
let token = new OAuthBuilder()
.clientId("clientId")
.scope("scope")
.redirectURL("redirectURL")
.build();
/*
* autoRefreshFields
* 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 cache or refresh the fields using methods from ModuleFieldsHandler
*
* cacheStore
* A boolean field that allows or disallows the storage of module field information in cache.
* True - the SDK stores all the modules' field information in cache, and refreshes every hour, if autoRefreshFields is true.
* False - the SDK temporarily stores the modules' field information in a Map.
*
* pickListValidation
* 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.
* True - the SDK validates the input. If the value does not exist in the pick list, the SDK throws an error.
* False - the SDK does not validate the input and makes the API request with the user’s input to the pick list
*
* timeout
* representing the number of milliseconds a request can take before automatically being terminated.
*/
let sdkConfig = new SDKConfigBuilder().autoRefreshFields(true).pickListValidation(false).cacheStore(true).build();
/*
* Call the static initialize method of Initializer class that takes the following arguments
* environment -> Environment instance
* SDKConfig -> SDKConfig instance
* token -> Token instance
* logger -> Logger instance
*/
(await new InitializeBuilder())
.environment(environment)
.token(token)
.SDKConfig(sdkConfig)
.logger(logger)
.initialize();
}
}