Kaizen #20 - Node JS SDK

Kaizen #20 - Node JS SDK

Hello everyone!
Welcome to another week of Kaizen!
In today's post, we will discuss the Node JS SDK.

What is the Node JS SDK for Zoho CRM?
Node JS SDK allows you to create client Node JS 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.

What can you do with the Node JS SDK?
  • Exchange data between Zoho CRM and the client application where the CRM entities are modelled as functions.
  • 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.
How to start using the Node JS 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 files or dictionary
    4.c. Generate the tokens
  • Step-5: Connect to Zoho CRM through the available functions

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 Node JS SDK through npm package manager. Run the below command.

npm install zcrmsdk

Run the below command to update your SDK to the latest version.

npm install --upgrade zcrmsdk
After the installation, a package named 'zcrmsdk' will be created in the node modules folder in your machine.

Step-3: Import the SDK in your project
Use the below statement in your code to import the downloaded SDK.

var ZCRMRestClient = require('zcrmsdk')

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 oauth and configuration properties files
  • 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 Node JS application and Zoho CRM.

You can choose to persist (store) the tokens in two ways.
      a. MySQL Persistence (default)
      b. Custom DB Persistence

a. MySQL Persistence
When you want to store the tokens in the MySQL DB, include the following keys in the configuration.properties file (discussed in the next section) or the configuration JSON array, along with other mandatory keys.

username=mysql_username
password=mysql_password

Note
When you use MySQL persistence, ensure that
  • MySQL runs in the same machine serving at the mentioned port (by default 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).
b. Custom DB Persistence
To use custom DB persistence, you must write a custom implementation of the following functions:
  • getOAuthTokens() - This method returns the user identifier, access and refresh tokens, and their respective expiry time.
  • saveOAuthTokens(token_obj) - This method saves the access and refresh tokens, their respective expiry time. This method is called when you generate the access token through the grant token or the refresh token.
  • updateOAuthTokens(token_obj) - This method updates the access token and the expiry time every time an access token is refreshed. This method is called when the access token expires.

Include the absolute path of the file that contains the above methods in the following key of the configuration.properties file.

api.tokenmanagement=absolute_path_to _the_custom_implementation

The below images contain a sample of the custom implementation of the above three methods. You can find the code for the same as an attachment to this post.
This implementation of custom persistence creates a token file named zcrm_oauthtokens.txt and this file will contain the below keys with their values.

{"tokens": [{"access_token":"1000.xxxxx","expires_in":1582804396157,"user_identifier":"Patricia.boyle@abc.com","refresh_token":"xxx"}]}
getOAuthTokens()


updateOAuthTokens()


saveOAuthTokens()


Note
  • While updating the tokens, the next execution happens irrespective of the response. So, you must exercise care to handle this in your module.
  • All methods must return a Promise.
4.b. Configuration
You can set the configuration details in property files (oauth_configuration.properties and configuration.properties) or pass the details during run time as JSON key-value pairs.

oauth_configuration.properties
This file must contain the below client details.

[zoho]
crm.iamurl=accounts.zoho.com
crm.clientid=1000.xxxxxxx.6WJ
crm.clientsecret=99xxxxx0e16
crm.redirecturl=https://www.zoho.com

Where,
  • crm.iamurl - The domain-specific accounts URL from which you generate the grant token (authorization code). Possible domains are accounts.zoho.com (US), accounts.zoho.eu (EU), accounts.zoho.in (India), accounts.zoho.com.cn(China), accounts.zoho.com.au (Australia). The default value is accounts.zoho.com.
  • crm.clientid, crm.clientsecret - The client ID and client secret, respectively, you received while registering your application.
  • crm.redirecturl - The redirect URI you specified while registering your client. For self client apps, you can specify a dummy value for this key.
configuration.properties

This file must contain the below details.

[crm]
api.url=www.zohoapis.com
api.user_identifier=p.boyle@abc.com
[customDB]//If you want to use custom DB persistence
api.tokenmanagement=
[mysql]//If you want to use MySQL DB persistence
username=*****
password=*****

Where,
  • api.url - The domain-specific URL from which your app must make API calls to Zoho CRM. Possible URLs are www.zohoapis.com (US), www.zohoapis.eu (EU), www.zohoapis.in (India), www.zohoapis.com.cn(China), www.zohoapis.com.au (Australia). The default value is www.zohoapis.com.
  • api.user_identifier - The email ID of the current user.
  • api.tokenmanagement - The absolute or relative path to the file that contains the token storage mechanism. This key is mandatory for custom DB persistence.
  • username, password - The MySQL username and password, respectively. These keys are mandatory for MySQL DB persistence.
Note
Both these files must be placed under the resources folder of your project.

Config JSON Array
Instead of specifying the configuration details in properties files, you can choose to pass the details to the SDK during run time as JSON key-value pairs, as shown below.

var ZCRMRestClient = require('zcrmsdk');
var configJson={
        "client_id":"{client_id}",//mandatory
        "client_secret":"{client_secret}",//mandatory
        "redirect_uri":"{redirect_url}",//mandatory
        "user_identifier":"{user_identifier}",
        "mysql_username":"{mysql_username}",//optional ,"root" is default value
        "mysql_password":"{mysql_password}",//optional ,"" is default value
        "base_url":"{api_base_url}",//optional ,"www.zohoapis.com" is default value
        "iamurl":"{accounts_url}",//optional ,"accounts.zoho.com" is default value
        "version":"{api_version}",//optional ,"v2" is default value
        "tokenmanagement":"{token_management_module}"//optional ,mysql module is default
}
ZCRMRestClient.initialize(configJson).then(function()
{
//do whatever required after initialize
})

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

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.

ZCRMRestClient.generateAuthTokens(user_identifier,grant_token).then(function(auth_response){
console.log("access token :"+auth_response.access_token);
console.log("refresh token :"+auth_response.refresh_token);
console.log("expires in :"+auth_response.expires_in);
});

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 or the properties file, and refreshes the access token as and when required.

Step-5: Connect to Zoho CRM through the available methods

Here is a sample to insert a lead. You can find the code for this sample in the attachment.



The isTokenGenerated Method

You need to add this method to check if the access token has already been generated or not. It returns a Boolean value.

true - The access token has already been generated. 
false - The access token has not been generated previously, thus, it shifts the control to the code snippet that leads to access token generation.

For more sample codes, refer to REST API samples.


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




    Access your files securely from anywhere

        Zoho Developer Community




            Bootcamp
            Community
            Pricing
            Webinars
            What's New
            Integrations
            Contact Support
            Contact Sales

              Zoho Survey Resources
                Features
                Survey Templates
                Integrations
                Community
                iOS Mobile Surveys
                Pricing
                Android Mobile Surveys
                Insurvey Blogs
                Insight Blogs
                Tips & Tricks





                              Latest Feature Updates


                                  Zoho Desk Resources

                                  • Desk Community Learning Series


                                  • Digest


                                  • Functions


                                  • Meetups


                                  • Kbase


                                  • Resources


                                  • Glossary


                                  • Desk Marketplace


                                  • MVP Corner


                                  • Word of the Day




                                      Zoho Marketing Automation
                                        Zoho SalesIQ Resources


                                              Manage your brands on social media
                                              Access Zoho Social

                                                Zoho Pagesense Resources


                                                    Zoho TeamInbox Resources

                                                      Zoho DataPrep Resources



                                                        Zoho CRM Plus Resources

                                                          Zoho Books Resources


                                                            Zoho Subscriptions Resources

                                                              Zoho Projects Resources


                                                                Zoho Sprints Resources


                                                                  Qntrl Resources


                                                                    Zoho Creator Resources



                                                                        Zoho Campaigns Resources


                                                                          Zoho CRM Resources

                                                                          • CRM Community Learning Series

                                                                            CRM Community Learning Series


                                                                          • Kaizen

                                                                            Kaizen

                                                                          • Functions

                                                                            Functions

                                                                          • Meetups

                                                                            Meetups

                                                                          • Kbase

                                                                            Kbase

                                                                          • Resources

                                                                            Resources

                                                                          • Digest

                                                                            Digest

                                                                          • CRM Marketplace

                                                                            CRM Marketplace

                                                                          • MVP Corner

                                                                            MVP Corner





                                                                              Design. Discuss. Deliver.

                                                                              Create visually engaging stories with Zoho Show.

                                                                              Get Started Now