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.
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.
Initialization
Following are the important parameters that you need to pass before making an API Call. Check Configuration page for mandatory and optional keys.
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 and file 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.
Logger - To log the messages. You can choose the level of logging of messages through Logger.Levels.ALL, 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.
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.
using System;
using Com.Zoho.API.Authenticator;
using Com.Zoho.API.Authenticator.Store;
using Com.Zoho.Crm.API;
using Com.Zoho.Crm.API.Dc;
using Com.Zoho.Crm.API.Logger;
using static Com.Zoho.API.Authenticator.OAuthToken;
using Environment = Com.Zoho.Crm.API.Dc.DataCenter.Environment;
using SDKInitializer = Com.Zoho.Crm.API.Initializer;
namespace Com.Zoho.Crm.Sample.Initializer
{
public class Initialize
{
public static void SDKInitialize()
{
/*
* Create an instance of Logger Class that requires the following
* Level -> Level of the log messages to be logged. Can be configured by typing Levels "." and choose any level from the list displayed.
* FilePath -> Absolute file path, where messages need to be logged.
*/
Logger logger = new Logger.Builder()
.Level(Logger.Levels.ALL)
.FilePath("/Users/Documents/csharp_sdk_log.log")
.Build();
//Create an UserSignature instance that takes user Email as parameter
UserSignature user = new UserSignature("abc@zoho.com");
/*
* Configure the environment
* which is of the pattern Domain.Environment
* Available Domains: USDataCenter, EUDataCenter, INDataCenter, CNDataCenter, AUDataCenter
* Available Environments: PRODUCTION, DEVELOPER, SANDBOX
*/
Environment environment = USDataCenter.PRODUCTION;
/*
* Create a Token instance that requires the following
* clientId -> OAuth client id.
* clientSecret -> OAuth client secret.
* refreshToken -> REFRESH token.
* grantToken -> GRANT token.
* id -> User unique id.
* redirectURL -> OAuth redirect URL.
*/
// if ID (obtained from persistence) is available
Token token = new OAuthToken.Builder()
.ClientId("clientId")
.ClientSecret("clientSecret")
.RefreshToken("refreshToken")
.RedirectURL("redirectURL")
.Build();
/*
* Create an instance of DBStore.
* Host -> DataBase host name. Default "localhost"
* DatabaseName -> DataBase name. Default "zohooauth"
* UserName -> DataBase user name. Default "root"
* Password -> DataBase password. Default ""
* PortNumber -> DataBase port number. Default "3306"
* TableName -> Table Name. Default value "oauthtoken"
*/
//TokenStore tokenstore = new DBStore.Builder().Build();
TokenStore tokenstore = new DBStore.Builder()
.Host("hostName")
.DatabaseName("dataBaseName")
.TableName("tableName")
.UserName("userName")
.Password("password")
.PortNumber("portNumber")
.Build();
// TokenStore tokenstore = new FileStore("absolute_file_path");
/*
* 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 file(s) or refresh the fields using methods from ModuleFieldsHandler(com.zoho.crm.api.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.
*/
SDKConfig config = new SDKConfig.Builder().AutoRefreshFields(false).PickListValidation(false).Build();
string resourcePath = "/Users/user_name/Documents/csharpsdk-application";
/**
* Create an instance of RequestProxy class that takes the following parameters
* Host -> Host
* Port -> Port Number
* User -> User Name
* Password -> Password
* UserDomain -> User Domain
*/
RequestProxy requestProxy = new RequestProxy.Builder()
.Host("proxyHost")
.Port(proxyPort)
.User("proxyUser")
.Password("password")
.UserDomain("userDomain")
.Build();
/*
* The initialize method of Initializer class that takes the following arguments
* User -> UserSignature instance
* Environment -> Environment instance
* Token -> Token instance
* Store -> TokenStore instance
* SDKConfig -> SDKConfig instance
* ResourcePath -> resourcePath -A String
* Logger -> Logger instance
* RequestProxy -> RequestProxy instance
*/
// Set the following in InitializeBuilder
new SDKInitializer.Builder()
.User(user)
.Environment(environment)
.Token(token)
.Store(tokenstore)
.SDKConfig(config)
.ResourcePath(resourcePath)
.Logger(logger)
//.RequestProxy(requestProxy)
.Initialize();
}
}
}