Integration Tasks - Node JS

Integration Tasks - Node JS

Getting Started

For starters, the basic difference between Version 1.0 and 2.0 of Zoho APIs is that Field Names are used in the former and API Names are used in the latter.

To get the API Names of modules:

  • Go to Setup > Developer Space > APIs > CRM API > API Names.
  • The API Names of the modules are listed in the API Names tab.



To get the API Names of fields in modules:

  • Go to Setup > Developer Space > APIs > CRM API > API Names.
  • Click on a module name. For example: Leads



  • The API Name tab contains the API Names of fields. These fields are to be used in the code and NOT the names in the Field Label tab.



Get Records

Records, containing information, can be fetched from multiple supported modules of CRM. You can get the records using the zoho.crm.getRecords() task.

Syntax: (using Version 2.0 APIs)

<response>=zoho.crm.getRecords(<module_name>, [<page>],[<perPage>], {<optionalDataMap>}, <connections>);

Params
Description
<response>
The response with the LIST of records matching the fetch criteria.
<module_name>
The name of the module from which the record has to be fetched. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom.
<page> (optional)
To get the list of records based on pages. It is of the NUMBER datatype. Default is 1.
<perPage> (optional)
Used to get the list of records available per page. It is of the NUMBER datatype. Default - 200.
<optionalDataMap>
Used to get the list of records using params other than page and per_page.
<connections>
Displays the connectors associated with the function. Datatype is STRING.

Sample Input
  1. resp = zoho.crm.getRecords("Leads",1,20,{"converted":"true"});
Note
In the above sample, "converted" is an optionalDataMap.

Get Record by ID

Getting a list of records is quite good, but what if you want to fetch details about a specific record. You can use the zoho.crm.getRecordById() task, to get the information about a particular record.

Syntax: (Using Version 2.0 APIs)

<response>=zoho.crm.getRecordById(<module_name>, <record_ID>, <connections>);

Params
Description
<response>
The response which returned as a MAP.
<module_name>
The name of the module from which the record has to be fetched. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom.
<record_ID>
The ID of the record to be fetched. It is of NUMBER datatype.
<connections>
Displays the connectors associated with the function. Datatype is STRING.

Sample Input

  1. resp = zoho.crm.getRecordById("Leads", 2938383000000392001);

Create a record

Set up the functions in a way that records are automatically created based on certain actions. For ex: you can trigger the function to create a record in tasks upon changing the status of a lead. The zoho.crm.create() task is used to create records.

Syntax: (Using Version 2.0 APIs)

<variable>=zoho.crm.create(<module_name>,{<dataMap>}, {<optionalDataMap>}, <connections>);

Params
Description
<response>
The response which is returned as a MAP.
<module_name>
The name of the module from which the record has to be fetched. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom.
<dataMap>
The name of the fields in the module which are to be specified during creation of the record. For ex: {"Last_name":"Zoho CRM"}
<optionalDataMap>
Represents all the data maps other than input JSON.
<connections>
Displays the connectors associated with the function. Datatype is STRING.

Sample Input

  1. data = Map();
  2. data.putAll({"Last_Name":"Bruce Wills", "Company":"Zillum"});
  3. optionalMap = Map();
  4. optionalMap.put("trigger", ["workflow","approval", "blueprint"]); // pass "trigger" as empty [] to not execute workflow
  5. resp = zoho.crm.create("Leads", data, optionalMap);

Sample Response

  1. {"Modified_Time":"2018-03-26T14:33:01+05:30","Modified_By":{"name":"Ben","id":"2938383000000132011"},"Created_Time":"2018-03-26T14:33:01+05:30","id":"2938383000000389001","Created_By":{"name":"Ben","id":"2938383000000132011"}}

Create bulk records

Set up the functions in a way that records are automatically created based on certain actions. For ex: you can trigger the function to create multiple record, in contacts, accounts, tasks, deals, etc, upon changing the converting a lead to a contact. The zoho.crm.bulkCreate() task is used to create records.

Syntax: (Using Version 2.0 APIs)

<variable>=zoho.crm.bulkCreate(<module_name>,[record1, record2]);

Params
Description
<response>
The response which is returned as a MAP.
<module_name>
The name of the module from which the record has to be fetched. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom.
[record1, record2]
The LIST which contain the information about the records to be created.

Sample Input

  1. resp = zoho.crm.bulkCreate("Leads", [{"Last_Name":"Deborah"},{"Last_Name":"James"}], {"trigger":["workflow","blueprint","approval"]});

Update a record

Often, there are times when you would have to update records. Editing the existing information, adding additional information, etc can be done automatically by setting the zoho.crm.update() task, which automatically updates a record based on the programmed scenario.

Syntax: (Using Version 2.0 APIs)

<response>=zoho.crm.update(<module_name>, <record_ID>, <dataMap>, {<optionalDataMap>}, <connections>);

Params
Description
<response>
The response which is returned as a MAP.
<module_name>
The name of the module from which the record has to be fetched. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom.
<record_ID>
The ID of the record to be updated. It is of NUMBER datatype.
<dataMap>
Key. Value pairs with updated record information.
<optionalDataMap>
Represents all the data maps other than input JSON.
<connections>
Displays the connectors associated with the function. Datatype is STRING.

Sample Input

  1. resp = zoho.crm.update("Leads", 2938383000000392001, {"Company":"Zillum Corp"});

Sample Response

  1. {"Modified_Time":"2018-03-26T15:17:39+05:30","Modified_By":{"name":"Ben","id":"2938383000000132011"},"Created_Time":"2018-03-26T14:39:28+05:30","id":"2938383000000392001","Created_By":{"name":"Ben","id":"2938383000000132011"}}

Search a record

Search for specific records by specifying the criteria for the search. The searched records can be used to perform actions anywhere. Searching for a record requires the module name and the search criteria to be specified.

Syntax: (Using Version 2.0 APIs)

<response>=zoho.crm.searchRecords(<module_name>, <criteria>, [<page>],[<perPage>], <connections>);

Params
Description
<response>
The response with the LIST of records matching the fetch criteria.
<module_name>
The name of the module from which the record has to be fetched. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom.
<criteria>
The conditional statement for the search. It is of the following format: (<field>:<condition>:<value>). The <field> stands for the CRM field label name and <value> 
stands for it's respective value. The <condition> may be
  • equals
  • starts_with (STRING)
<page> (optional)
To get the list of records based on pages. It is of the NUMBER datatype. Default - 1.
<perPage> (optional)
Used to get the list of records available per page. It is of the NUMBER datatype. Default - 200.
<connections> (optional)
Displays the connectors associated with the function. Datatype is STRING.

Sample Input

  1. resp = zoho.crm.searchRecords("Leads", "(Company:equals:Zillum)");
Note
  • Search records by PDC is not available in Version 2.0.
  • If a column contains null values, zoho.crm.searchRecords DOES NOT report them in a <> statement.
  • At any given time, a maximum of 200 records can be fetched.

There are various components of CRM which can be used to store information about a particular lead or contact. For example, a lead may contain a list of notes, a couple of deals, calls associated, etc. Searching for a note related to a particular record in a module can be done using the zoho.crm.getRelatedRecords() task.

Syntax: (Using Version 2.0 APIs)

<response>=zoho.crm.getRelatedRecords(<relation_name>, <parent_module_name>, <record_ID>, [<page>],[<perPage>], <connections>);

Params
Description
<response>
The response with the LIST of records matching the fetch criteria.
<relation_name>
The name of the module (also called sub module) from which the record has to be fetched. It is of STRING datatype. Supported modules are: Notes, Quotes, Products, Tasks, Campaigns, Events, Calls.
<parent_module_name>
The name of the module to which the sub module belongs to. For ex: "Notes can belong to a "Leads" parent module. It is of STRING datatype. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom.
<record_ID>
The ID of the parent module record that needs to be fetched. It is of NUMBER datatype.
<page> (optional)
To get the list of records based on pages. It is of the NUMBER datatype. Default - 1.
<perPage> (optional)
Used to get the list of records available per page. It is of the NUMBER datatype. Default - 200.
<connections> (optional)
Displays the connectors associated with the function. Datatype is STRING.

Note

At any given time, a maximum of 200 records can be fetched.

Sample Input

To fetch Campaigns related to a Lead

  1. resp = zoho.crm.getRelatedRecords("Campaigns", "Leads", 2938383000000392001);

To fetch Tasks related to a Lead

  1. resp = zoho.crm.getRelatedRecords("Task", "Leads", 2938383000000392001);

There are various components of CRM which can be used to store information about a particular lead or contact. You can update the records related to a parent record using the zoho.crm.updateRelatedRecord() task.

Syntax: (Using Version 2.0 APIs)

<response>=zoho.crm.updateRelatedRecords(<relation_name>, <record_ID_1>, <parent_module_name>, <record_ID_2>, {<New values as map object>});

Params
Description
<response>
The response with the LIST of records matching the fetch criteria.
<relation_name>
The name of the module (also called sub module) from which the record has to be fetched. It is of STRING datatype. Supported modules are: Notes, Quotes, Products, Tasks, Campaigns, Events, Calls, Emails.
<record_ID_1>
The ID of the record that needs to be updated. It is of NUMBER datatype.
<parent_module_name>
The name of the module to which the sub module belongs to. For ex: "Notes can belong to a "Leads" parent module. It is of STRING datatype. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom.
<record_ID_2>
The ID of the parent module record that needs to be fetched. It is of NUMBER datatype.
<New Values as MAP object>
Key. Value pairs with updated record information. Ex: {"Last_Name": "Updated Name", "Fax": "555-858-3466"}

Sample Input

To update product quantity

  1. resp = zoho.crm._updateRelatedRecords("Products",2938383000000392001, "Leads", 2938383000000392001, {"Product_Quantity":"50"});

Convert Lead

The next step after lead acquirement would be negotiations, where good prospects can be converted from leads to contacts. You can use the zoho.crm.convertLead() task, to get transfer the lead information as a contact record.

Syntax: (Using Version 2.0 APIs)

<response>=zoho.crm.convertLead(<record_ID>, <overwrite>, <notify_lead_owner>, <notify_new_entity_owner>, <account_ID>)

Params
Description
<response>
The response which returned as a MAP.
<record_ID>
The ID of the record to be fetched. It is of NUMBER datatype.
<overwrite>
Used to overwrite the data if the lead was already converted. Datatype is BOOLEAN Should be either true or false.
<notify_lead_owner>
Used to send a notification to the owner of the lead, after conversion. Datatype is BOOLEAN Should be either true or false.
<notify_new_entity_owner>
Used to send a notification to the owner of the new entity(contact), after conversion. Datatype is BOOLEAN Should be either true or false.
<account_ID> (optional)
The ID of the record to be fetched. It is of NUMBER datatype.

Sample Input

  1. resp = zoho.crm.convertLead(7000000037308, { "overwrite": true, "notify_lead_owner": false, "notify_new_entity_owner": true, "Accounts": "7000000037323", "Deals": { "Deal_Name": "Robert", "Closing_Date": "2016-03-30", "Stage": "Closed Won", "Amount": 56.6 } });

Invoke URL

Data doesn't flow within just your CRM. There are times when you require data to be pulled in from other services. You can use the Invoke URL method within the function to achieve data transfer operations.

Syntax: (Using Version 2.0 APIs)

<response>=invokeUrl
[
            url: <expression>
            type: <expression>
            parameters: <expression>
            headers: <expression>
];

Params
Description
<response>
The response which returned as a MAP.
<url>
The endpoint API url of the Zoho service or other third party service you wish to call.
<type>
The HTTP method of the API call. Could be: GET/POST/PUT/PATCH/DELETE.
<parameters>
Used to send params as "form-data". Basically it replaces the dynamic values present in the API with user-specific values.
<headers>
Used to specify request header params. They are mandatory in case connections are not used in invoke Url method.


In case you're using the Sandbox of your CRM, there are some changes in the url of the method. Take a look below.






    • Related Articles

    • Installation - Node JS SDK

      Node JS SDK will be installed and a package named 'zcrmsdk' will be created in the local machine. The package can be added using the following code: var ZCRMRestClient = require('zcrmsdk') Installing the SDK Run the command below to install the Node ...

    • Initialization - Node JS SDK

      Whenever the app is started, the below code snippet is to be called for initialization. var ZCRMRestClient = require('zcrmsdk'); ZCRMRestClient.initialize().then(function() { //do whatever required after initialize }) Generating self-authorized grant ...

    • Configuration - Node JS SDK

      Your OAuth Client details should be given to the SDK as a property file. In the SDK, you need to configure a file named oauth_configuration.properties. Please place the respective values in that file. You can place it under resources folder from ...

    • Node JS SDK - An Overview

      Node JS SDK offers a way to create client node js applications that can be integrated with Zoho CRM. This SDK makes the access and use of necessary CRM APIs easy. In other words, it serves as a wrapper for the REST APIs, making it easier to use the ...

    • Release Notes - Node JS SDK

      ZCRMSDK -VERSION 0.0.15 Install command npm install zcrmsdk@0.0.15 Notes Enhancement: User identifier default value handled in get method. ZCRMSDK -VERSION 0.0.14 Install command npm install zcrmsdk@0.0.14 Notes Issue fix: Default user identifier set ...