Articles in this section

Server Scripts & Jobs Overview Using Custom Server Scripts in Processes, Workflows, and Approvals Running Custom Background Tasks with Vtiger Server Jobs Writing Code for Server Scripts and Jobs Helper Method for Server Scripts and Jobs - Debugging Helper Method for Server Scripts and Jobs - HTTP Request Server Scripts Example - Contact Email Validation and Data Enrichment Server Scripts Example - Update Credit Score of a Contact Server Scripts Example - Calculate Organization Outstanding Invoice Amount Server Scripts Example - Set Case SLA by Created Day Server Jobs Example - Importing Daily Leads from a File Server Jobs Example - Update Stocks Weekly in Warehouse System Server Side Scripts & Jobs User Guide

Helper Methods for Server Scripts and Jobs - Vtiger REST API

This article describes the Vtiger REST API helper method for Server Scripts and Jobs.

A

Abdul Sameer

19 Apr, 2024 - Updated 8 months ago

Vtiger REST API Methods

Vtiger Cloud offers REST-friendly API for integration with 3rd-party-applications. To learn more about Vtiger's REST API refer to this document. These helper methods (vtap.macro.ws) enable sending REST API requests to your CRM instance from where code is invoked.

Vtiger’s REST API methods are available for CRM operations like create, update, delete, etc.
No need to pass authentication details. Methods handle it internally.
Parameters required vary depending on the method called.
The parameters expected are similar to REST APIs.
All methods are asynchronous and return a promise, therefore it must be used with await.

Syntax

To make REST API calls to your CRM instance, use vtap.macro.ws library. For example, to call describe API, use vtap.macro.ws.describe.

Example

var describe = await vtap.macro.ws.describe(‘Contacts’);

Notes:

REST API requests can also be invoked using HTTP request methods but by using these, you don’t have to worry about setting the request URL, username and access key.
Making REST API calls to other CRM instances is restricted. You can make REST API calls only to your CRM instance from where the script is triggered.

Available Methods

Describe - vtap.macro.ws.describe

Method to get the module’s description. This expects a single parameter elementType which is the module name for which description is requested.

var describe = await vtap.macro.ws.describe(‘Contacts’);

List Types - vtap.macro.ws.listtypes

Method to get a list of modules by field types. This method expects a single parameter fieldTypeList. If you want to get the list of modules having email or phone-type fields, then pass field types as an array. If you want to get the list of modules by single field type, you can pass the field type as array or string. If you want to get all modules list, you can skip passing this parameter value or pass it as NULL.

var list = await vtap.macro.ws.listtypes([‘email’, ‘phone’]);

Retrieve - vtap.macro.ws.retrieve

Method to fetch a CRM record data. This method expects a single parameter ID which is the record ID in web service format.

var record = await vtap.macro.ws.retrieve(‘4x1234’);

Create - vtap.macro.ws.create

Method to create a record in CRM. This method expects 2 parameters. elementType is the name of the module for which the record needs to be created and element is the record data object.

var response = await vtap.macro.ws.create(‘Contacts’, {
    firstname: ‘Jack’,
    lastname: ‘Daniel’,
    email: ‘jack.d@company.com’,
    mobile: ‘+1-1234-XXXXXXXX’,
    assigned_user_id: ‘19x1’
});

Update - vtap.macro.ws.update

Method to update a record in CRM. This method expects a single parameter element which is a JSON object containing all field values of the record including the record's ID.

var response = await vtap.macro.ws.update({
    id: ‘4x1234’,
    firstname: ‘Jack’,
    lastname: ‘Daniel’,
    email: ‘jack.daniel@company.com’,
    mobile: ‘+1-234-XXX-XXXXXX’,
    assigned_user_id: ‘19x6’
});

Revise - vtap.macro.ws.revise

Method to revise a CRM record data. This method expects a single parameter element which is a JSON object containing the record's ID and field values which need to be updated.

var response = await vtap.macro.ws.revise({
    id: ‘4x1234’,
    secondaryemail: ‘jackd01@mail.com’,
    phone: ‘+1-5612-XXX-XXXXXXX’
});

Delete - vtap.macro.ws.delete

Method to delete a record in CRM. This method expects a single parameter ID which is the ID of the record to be deleted.

var response = await vtap.macro.ws.delete(‘4x1234’);

Query - vtap.macro.ws.query

Method to fetch CRM records using a query string. This method expects a single parameter query i.e. query string.

var result = await vtap.macro.ws.query(“SELECT * FROM Contacts WHERE email != ‘ ’ ORDER BY createdtime DESC LIMIT 10”);

Other REST API methods - vtap.macro.ws.api

Method to invoke other REST APIs which are not listed above. Vtiger’s REST API supports multiple APIs (reference). If you want to use any other API for which the method is not listed above, you can use this.

This method expects 3 parameters

requestMethod - API request type (GET or POST).
API - REST API name (retrieve_related, query_related, add_related, reopen, converlead, etc)
Parameters - Object containing API request parameters

var result = await vtap.macro.ws.api(‘GET’, ‘retrieve_related’, {
    id: ‘6x2345’,
    relatedLabel: ‘Potentials’,
    relatedType: ‘Potentials’
});

Constraints

Like HTTP request methods, rest API methods are also asynchronous. To wait for the promise, use await. Listening for promises using .then() is not supported.
To get the API error, use try-catch. In case parameters are missing or because of other reasons, the API call fails, it will be available as an error in the catch section.

Was this article helpful?

0 out of 0 found this helpful.

Comments 0

Be the first to comment