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




                                    Zoho Desk Resources

                                    • Desk Community Learning Series


                                    • Digest


                                    • Functions


                                    • Meetups


                                    • Kbase


                                    • Resources


                                    • Glossary


                                    • Desk Marketplace


                                    • MVP Corner


                                    • Word of the Day



                                        Zoho Marketing Automation


                                                Manage your brands on social media



                                                      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


                                                                                  Zoho Show Resources


                                                                                    Zoho Writer Writer

                                                                                    Get Started. Write Away!

                                                                                    Writer is a powerful online word processor, designed for collaborative work.

                                                                                      Zoho CRM コンテンツ






                                                                                        Nederlandse Hulpbronnen


                                                                                            ご検討中の方





                                                                                                  • Recent Topics

                                                                                                  • How do I get the Text Account name instead of the Reference number?

                                                                                                    Good Morning everyone! I am very new to zoho analytics. I'm trying to create some pivot tables and when I add the Account or Division name it comes up as a reference number. From my research, I need to use a lookup. I'm having a really hard time understanding
                                                                                                  • Custom API - Need to create a string return value, not only MAP

                                                                                                    @Support: When creating a Custom API it only allows a return from a function of MAP type. The service I'm using requires a string return, how can this be achieved?
                                                                                                  • missing video-urgent

                                                                                                    hi..I have a problem regarding zoho meeting. I already record almost 2hrs for my interview session. After end my session, i'm stop the recording. Its happened when i didn't received any meeting recording at my email.But i received recording 7minutes after
                                                                                                  • Duplicate New Ticket Emails

                                                                                                    I am getting two Ticket emails when a ticket is created. The first one goes to me as the Admin helpdesk@ And because I am an Agent as well it also send to helpdesk@, support1@ and support2@ Is there any way to stop this?
                                                                                                  • Ticket Response Email Template

                                                                                                    Is there a way to have an email template automatically selected when I click on Reply for a ticket?
                                                                                                  • Unpublishing Job Post for LinkedIn

                                                                                                    Hi, We have experienced issue with the above. We did unpublish a job in Recruit but it still appear under Job section in our LinkedIn page. It did not remove from LinkedIn as it should be.  Please check and advise. Regards, Snyder 
                                                                                                  • Power of Automation :: Automatically start / pause / stop timer on task status update.

                                                                                                    Hello Everyone, A Custom function is a user-written set of code to achieve a specific requirement. Set the required conditions needed as when to trigger using the Workflow rules (be it Tasks / Project) and associate the custom function to it. Requirement:-
                                                                                                  • Editor limitations to define screen types

                                                                                                    Guys I have noticed that even in version 2.0 of the editor (which is this new one we use) we still have a lot to improve... When I compare to some more global solutions like Wix, Zyro, Go Daddy, Squarespace and Weebly feel that we have some limitations
                                                                                                  • Dúvidas do Zoho Creator

                                                                                                    Pessoal, Estou colocando um tópico para dúvidas do Zoho Creator. Um abraço, Leandro
                                                                                                  • Tropicalize Books

                                                                                                    Books is an incredibly powerful tool that works well in many countries. But I feel that it is a product that is not yet "tropicalized" for Brazil as we speak (this would be like adapting the local reality). We have many strong competitors who do more
                                                                                                  • Automatic Sitemap Generation

                                                                                                    Guys are all right? Doesn't make sense for me to have to generate a map site and upload it... because it's not automatically generated just as it is done in WIX? where the customer doesn’t have to worry about this.
                                                                                                  • SEO improvements with ZIA

                                                                                                    Are you okay? I would like to bring an idea that would be amazing to improve the product that is the possibility of being able to improve the SEO of the pages (this of each page or each article on the blog) through ZIA so that it could create page Summary
                                                                                                  • Automatically updating field(s) of lookup module

                                                                                                    I have a lookup field, which also pulls through the Status field from the linked record. When the lookup is first done, the Status is pulled through - this works perfectly. If that Status is later updated, the lookup field does not update as well. As
                                                                                                  • Initiating a SalesIQ Zobot from a custom button on Zoho Sites

                                                                                                    I have created a Zobot set to initiate on a custom action called "Fast_Answers". On Zoho Sites, I created a code snippet button and set it to on-click run the event called "Fast_Answers". I installed the SalesIQ integration code into the Zoho Sites Page
                                                                                                  • Zoho Desk -> Zoho Analytics : Where is the field for "Layout" ?

                                                                                                    I have many different layouts on my helpdesks and I want to be able to identify the stats for each one, however I can not file the field in the raw data from the Zoho Desk datasource. I thought it might be under "Tickets" but there is nothing. There is
                                                                                                  • Set resolution mandatory field

                                                                                                    Hi,  i have 2 questions:) : - i want to set the resolution field mandatory before close the ticket. Because for now, i can close the ticket without writing how i solve it - how can i setup zoho desk to receive ticket by email(e.g. clients sent email to support@mydomain.com) and it create a ticket in zoho desk
                                                                                                  • Impuesto automatico en cotizaciones

                                                                                                    Buen dia Mi pregunta es como se puede poner alguna operacion para que las cotizaciones me salgan automaticamente con impuestos ya que uno al cargarla al final tienen que añadir el porcentaje de impuesto Saludos
                                                                                                  • Zoho Assist "Agree and Download" Button "Greyed Out" ("Light Blued" Out)

                                                                                                    Anyone else having issue where support clients are unable to click "Agree and Download" to access the client so that we can provide remote support? This is for "on demand" support via accessing the support page and entering the support key and name. This
                                                                                                  • Project Billing with the Staff Hours Method in Zoho Projects

                                                                                                    The Staff Hours Billing Method in Zoho Projects allows you to bill your clients based on the actual time spent by each team member on a project, at the rate set for each user. This is useful for projects where different skill sets are needed and service
                                                                                                  • Creator Subform to CRM Subform

                                                                                                    Hello all, Has anyone successfully written data from a Creator Subform into CRM subform? I have been able to get the rows to populate but none of the data will come through. I'll add my code and the result in CRM. Creator Subform is 'Delivery_Receiving_Hours'.
                                                                                                  • custom fields not populating from deluge script into invoice

                                                                                                    Hello, I've created some Deluge script that is meant to take a few inputted invoice custom fields and calculate a few others. I can see when I execute the function that my inputted custom fields are being passed, yet im still ending up with all "null"
                                                                                                  • tax summation function - getting error

                                                                                                    Hello, I'm trying to create a function that adds all of individual tax rates from a few jurisdictions. I'm getting an error on line 9 - Value is empty and 'get' function cannot be applied. I've checked that I have data in each of the required fields,
                                                                                                  • Backstage / Zoho Books integration

                                                                                                    Hello. We have Zoho One and have slowly started using Backstage. Loving it. Problem is, we have ZERO accounting control over what is sold through this product. When will we be able to connect it to our existing Zoho Books tenant? Thank you very much!
                                                                                                  • Getting list of calendar events over api for zoho mail calendar

                                                                                                    Hi, I am using just Zoho mail without using Zoho CRM. I wanted to get all events booked in my zoho mail calendar through an api at regular intervals. I could find such API support for Zoho CRM calendar but not for zoho mail calendar. Can you kindly let
                                                                                                  • Allocate emails to user in a shared mailbox

                                                                                                    Hi, This might be obvious, but I cannot find the answer. I have 3 shared mailboxes so any team member can see the emails. Is there a way of allocating a specific email to a user so that it is their responsibility to deal with it? Thanks in advance.
                                                                                                  • Introducing Zoho Campaigns' own gateway for SMS campaigns

                                                                                                    We are excited to announce the launch of our SMS Gateway to send SMS through Zoho Campaigns. We have also made a few other changes in our current SMS Campaign model to improve your over all user experience. These updates are planned with an aim to expand
                                                                                                  • Update a lookup field in CRM from Creator using deluge

                                                                                                    I have a Creator form that creates a new account. When it creates the new account in the Accounts Module, I need it to also populate the Parent Account, which is a lookup field coming from the Module Parent Accounts, field Parent Account Name. I have
                                                                                                  • SMS Keyword Tracking in Zoho CRM From Zoho Campaigns

                                                                                                    Is there a way to track SMS leads in campaigns by associating them with specific keywords or codes? Additionally, can these leads be pushed to the CRM while retaining the keyword for tracking and reporting purposes?
                                                                                                  • Projects Multiselect API

                                                                                                    Having troubles setting a mutli select field via API. updateMap = map(); updateMap.put("UDF_MULTI1","picklist_id1,picklist_id2"); updateProjectRes = invokeurl [ url :"https://projects.zoho.com/restapi/portal/XXXX/projects/" + projectID + "/" type :POST
                                                                                                  • Bill quantity received / PO quantity

                                                                                                    PO's are raised & often the quantity received is greater than the PO quantity, so when we receive the bill & adjust the quantity on the bill we get.... Quantity recorded cannot be more than quantity ordered. This necessitates the adjustment of the PO
                                                                                                  • ZOHO BOOKS - RECEIVING MORE ITEMS THAN ORDERED

                                                                                                    Hello, When trying to enter a vendor's bill that contains items with bigger quantity than ordered in the PO (it happens quite often) - The system would not let us save the bill and show this error: "Quantity recorded cannot be more than quantity ordered." 
                                                                                                  • Adding Bluesky channel

                                                                                                    Hello, Is Bluesky (AT protocol) soon added on Social ? Bluesky is being developped and is now open to anyone (no more invitation) Thank you
                                                                                                  • Using Queries with dynamic parameters in Kiosk Studio

                                                                                                    Hi, I'm pretty new when it comes to developing within Zoho (I'm really a .NET developer), as it was just added to my responsibilities. For a new feature in the CRM, I'm trying to develop a Kiosk function to show a list of records (retrieved by the new
                                                                                                  • Unused items should not count into the available number of custom fields

                                                                                                    Hey, I realized that unused Items reduce the number of available custom fields. I can't see a case where that makes sense. Especially in our case where we have two different layouts in Deals with a lot of different fields, this causes problems.
                                                                                                  • Introducing Bot Filtering for Accurate Email Campaign Analytics

                                                                                                    Dear Marketers, We're excited to announce a new feature designed to enhance the accuracy of your email campaign analytics: bot filtering. This feature helps you filter out bot-generated opens and clicks, ensuring your campaign reports reflect genuine
                                                                                                  • Tip 37: Time Log Restriction in Zoho Projects

                                                                                                    Timesheet in Zoho Projects helps you big time in entering log hours for the tasks and issues and approving them. Now, with the new Time Log Restriction option, you can set daily and weekly log hour limits. You can restrict users from entering extra log hours than the permissible limit. The limits are restricted to 24 hours per day and 168 hours per week by default based on business hours. To customize, navigate to Task & Timesheet settings under Portal Configuration in Zoho Projects setup and enable
                                                                                                  • Chart showing schedule

                                                                                                    I want to be able to create a chart for everyday to check and which of which driver is available on the timeframe. Here's my table Name City Day Start Time End Time Driver1 Medicine Hat Monday 11:45 AM 4:45 PM Driver 2 Medicine Hat Tuesday 11:00 AM 7:00
                                                                                                  • Multiple Vendor SKUs

                                                                                                    One of the big concerns we have with ZOHO Inventory is lack of Vendor Skus like many other inventory software packages offer. Being able to have multiple vendor skus for the same product would be HUGE! It would populate the appropriate vendor Sku for
                                                                                                  • In Zoho Projects, is there a way to create a folders template under documents that can be used once a project is created?

                                                                                                    We have a specific folder structure that we would like to use that is standard across every project. Instead of having to create this structure every time a project is created, is there a way to create a template for the folders that can be added?
                                                                                                  • Zoho Payroll in France

                                                                                                    When will Zoho Payroll be available in France ?
                                                                                                  • Next Page