NodeJs in Custom Function

Custom functions help simplify complex, multi-step actions through program scripts that you can write and execute. Here are a few sample custom functions in NodeJs that you can use in your organization.

Currently, Node.js custom functions are supported only in the US and IN data centers.
A maximum of 10 custom functions can be created in total for both Java and Node.js.

To know where custom functions are used in ServiceDesk Plus Cloud, click here.

Java code explained:

module.exports = async function(context, simpleObj) {
// NodeJs code
}

The above is the sample function present when creating a new custom function.

module.exports = async function(context, simpleObj) { 

 

NodeJs method parameters:

Users can write any logic in NodeJs only using this method. Other methods can be called inside the method. The method has 2 parameters:

 

simpleObj :

Custom functions can be used in many areas in ServiceDesk Plus Cloud. When the custom function is used in Business Rules or Triggers of the Request module, then the current request's JSON will be passed to the Custom function as input. You can fetch the data using the following syntax:

var requestObj = simpleObj.getParameter("requestObj"); 

If you are configuring a change trigger, then you will have data under 'changeObj' instead of 'requestObj'.

Similarly while executing a function, you will also get 'context' from ServiceDesk Plus Cloud, which will contain common details like App account id.

To get the value of 'context' use the following snippet.

simpleObj.getParameter("context"); 

The following table contains the properties of each type of custom function.

Function Type

Input Parameters for Function

Expected output type from Function

Requests:

Trigger (or) Life cycle (or) Timer Actions

 

  • requestObj

    1. requestObj can be fetched by simpleObj.getParameter("requestObj") inside 'runner' method.

    2. requestObj contains the request data of the currently processed trigger. The structure will be aligned with our v3 API structure.
      e.g.
      {
      “subject” : “New Issue”,
      “priority” : {
      “name” : “High”
      },
      ...}

  • context

    1. context can be fetched by simpleObj.getParameter("requestObj") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

      3. initialObj: Present only if the trigger is executed upon request edit and contains the initial request.

      4. modifiedFields: Present only if the trigger is executed upon request edit and contains the fields whose values are changed.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
},
“intialObj” : {
“subject” : “New Issue”,
“priority” : {
“name” : “Low”
},
“modifiedField : [“priority”]
}

No need to return any data

 

Requests:

Business Rule Actions

 

You need to return a requestObj which is of datatype Map.

Note: the data returned in this object will be saved in the request. The best practice would be to get the requestObj from input and update only the required fields, instead of constructing a new object.

Syntax:

return requestObj;

Requests:

Business Rule (or) Abort Timer Conditions (or) Workflow Actions

 

You need to return a Boolean. Note: the returned true/false data will be used in condition.

Syntax:

return true;

Requests:

Custom Menu Actions

 

You need to return a JSON object.

Note: the data returned in this object will be notified in popup.

Syntax:

return {"success" : true/false, "message" : "<popup text>"};

Problems:

Trigger (or) Life Cycle (or) Timer Actions

 

  • problemObj

    1. problemObj can be fetched by simpleObj.getParameter("problemObj") inside 'runner' method.

    2. problemObj contains the problem data of the currently processed trigger. The structure will be aligned with our v3 API structure.
      e.g.
      {
      “title : “New Issue”,
      “priority” : {
      “name” : “High”
      },
      ...}

  • context

    1. context can be fetched by simpleObj.getParameter("context") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
}

No need to return any data

Problems:

Abort Timer Conditions (or) Workflow Conditions (or) Workflow Actions

 

You need to return a Boolean. Note: the returned true/false data will be used in condition.

Syntax:

return true;

Problems:

Custom Menu Actions

 

You need to return a JSON object.

Note: the data returned in this object will be notified in popup.

Syntax:

return {"success" : true/false, "message" : "<popup text>"};

Changes:

Abort Timer Conditions (or) Workflow Conditions (or) Workflow Actions

 

  • changeObj

    1. changeObj can be fetched by simpleObj.getParameter("changeObj") inside 'runner' method.

    2. changeObj contains the change data of the currently processed trigger. The structure will be aligned with our v3 API structure.
      e.g.
      {
      “title : “New Issue”,
      “priority” : {
      “name” : “High”
      },
      ...}

  • context

    1. context can be fetched by simpleObj.getParameter("context") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
}

You need to return a Boolean. Note: the returned true/false data will be used in condition.

Syntax:

return true;

Changes:

Trigger (or) Timer Actions

 

No need to return any data

Changes:

Custom Menu Actions

 

You need to return a JSON object.

Note: the data returned in this object will be notified in popup.

Syntax:

return {"success" : true/false, "message" : "<popup text>"};

Projects:

Trigger Actions

 

  • projectObj

    1. projectObj can be fetched by simpleObj.getParameter("projectObj") inside 'runner' method.

    2. projectObj contains the project data of the currently processed trigger. The structure will be aligned with our v3 API structure.
      e.g.
      {
      “title : “New Issue”,
      “priority” : {
      “name” : “High”
      },
      ...}

  • context

    1. context can be fetched by simpleObj.getParameter("context") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
}

No need to return any data

Releases:

Trigger Actions

 

  • releaseObj

    1. releaseObj can be fetched by simpleObj.getParameter("releaseObj") inside 'runner' method.

    2. releaseObj contains the release data of the currently processed trigger. The structure will be aligned with our v3 API structure.
      e.g.
      {
      “title : “New Issue”,
      “priority” : {
      “name” : “High”
      },
      ...}

  • context

    1. context can be fetched by simpleObj.getParameter("context") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
}

 

No need to return any data

Releases:

Custom Menu Actions

 

You need to return a JSON object.

Note: the data returned in this object will be notified in popup.

Syntax:

return {"success" : true/false, "message" : "<popup text>"};

Releases:

Workflow (or) Timer Conditions

 

You need to return a Boolean. Note: the returned true/false data will be used in condition.

Syntax:

return true;

Solutions:

Trigger Actions

 

  • solutionObj

    1. solutionObj can be fetched by simpleObj.getParameter("solutionObj") inside 'runner' method.

    2. solutionObj contains the solution data of the currently processed trigger. The structure will be aligned with our v3 API structure.
      e.g.
      {
      “title : “New Issue”,
      “priority” : {
      “name” : “High”
      },
      ...}

  • context

    1. context can be fetched by simpleObj.getParameter("context") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
}

No need to return any data

Assets:

Workflow Conditions (or) Actions

 

  • assetObj

    1. assetObj can be fetched by simpleObj.getParameter("assetObj") inside 'runner' method.

    2. assetObj contains the asset data of the currently processed trigger. The structure will be aligned with our v3 API structure.
      e.g.
      {
      “title : “New Issue”,
      “priority” : {
      “name” : “High”
      },
      ...}

  • context

    1. context can be fetched by simpleObj.getParameter("context") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
}

You need to return a Boolean. Note: the returned true/false data will be used in condition.

Syntax:

return true;

Assets:

Trigger (or) Life Cycle Actions

 

Return null from the runner method to end the function.

Syntax:

return null; 

Assets:

Custom Menu Actions

 

You need to return a JSON object.

Note: the data returned in this object will be notified in popup.

Syntax:

return {"success" : true/false, "message" : "<popup text>"};

CMDB:

Trigger Actions

 

  • ciObj

    1. ciObj can be fetched by simpleObj.getParameter("ciObj") inside 'runner' method.

    2. ciObj contains the CMDB data of the currently processed trigger. The structure will be aligned with our v3 API structure.
      e.g.
      {
      “title : “New Issue”,
      “priority” : {
      “name” : “High”
      },
      ...}

  • context

    1. context can be fetched by simpleObj.getParameter("context") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
}

No need to return any data

CMDB:

Custom Menu Actions

 

You need to return a JSON object.

Note: the data returned in this object will be notified in popup.

Syntax:

return {"success" : true/false, "message" : "<popup text>"};);

Purchases:

Trigger Actions

 

  • purchaseorderObj

    1. purchaseorderObj can be fetched by simpleObj.getParameter("purchaseorderObj") inside 'runner' method.

    2. purchaseorderObj contains the purchase order data of the currently processed trigger. The structure will be aligned with our v3 API structure.
      e.g.
      {
      “title : “New Issue”,
      “priority” : {
      “name” : “High”
      },
      ...}

  • context

    1. context can be fetched by simpleObj.getParameter("context") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
}

No need to return any data

Contracts:

Trigger Actions

 

  • contractObj

    1. contractObj can be fetched by simpleObj.getParameter("contractObj") inside 'runner' method.

    2. contractObj contains the contract data of the currently processed trigger. The structure will be aligned with our v3 API structure.
      e.g.
      {
      “title : “New Issue”,
      “priority” : {
      “name” : “High”
      },
      ...}

  • context

    1. context can be fetched by simpleObj.getParameter("context") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
}

No need to return any data

Configuration:

Trigger Actions

 

 

 

Scheduled Functions

 

  • context

    1. context can be fetched by simpleObj.getParameter("context") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
}

You need to return a JSON object

Syntax:

return new Map();

Callback Functions

 

  • <form data>

    1. <form data> can be fetched by simpleObj.getParameter("<form data key>") inside 'runner' method.

    2. <form data> contains the data of the param passed from callback function.
      e.g.
      {
      “key" : “value”,
      ...}

  • context

    1. context can be fetched by simpleObj.getParameter("context") inside 'runner' method.

    2. context contains the following details:

      1. instance: Portal in which the custom function is executed.

      2. userInfo: Logged in user details.

Sample Structure

{
“instance” : “itdesk”,
“userInfo” : {“userInfo” : {
“email_id” :
“sampleusername@manageengine.com”,
“type” : “requester/technician”,
Id>”
}

You need to return a JSON object

Syntax:

return new Map();

 

 

Test execution:

In the development phase, you can print the data and see the output from any line using the Save & Execute Script option. You can do it by using the 'context' parameter which is passed to the runner method.

For example, to print "Hello world" you can use

context.log.INFO("Hello world");

Similarly, to print the contents of a request during test execution, you can use

context.log.INFO(simpleObj.getParameter("requestObj")); 

Note: context.log.INFO has no effect in actual execution. It is meant for test execution only.

Making API calls using Connections:

You can make API calls from custom functions using Connections. Click here to learn more.

After creating a Connection, copy the link name. The link name is a unique name generated while creating a connection. Click here to learn more.

Use the connector method below to get the connection object with the connection link name.

var connector = context.getConnection(connectionLinkName);

Once you have created a connection object using the above, you can make HTTP calls using the 'connector.makeRequest' method.

Sample code:

The below sample code illustrates how to make an API call to ServiceDesk Plus v3 API. In this example, we will create a request with the subject "This test request is created from Custom function".

  /**
     * Makes an API call to the specified URL with the provided parameters, headers, and connection link name.
     *
     * @param context Pass the context object from exports method.
     * @param url The URL to which the API call is made.
     * @param method Method for HTTP call. Allowed values are GET, POST, PUT, DELETE.
     * @param input_data The parameters to be sent with the API call, formatted as a JSONObject. Can be null if no parameters are needed.
     * @param connectionLinkName The name of the connection link to use. Can be null if not needed.
     * @return The response body.
     * @throws Exception If an error occurs during the API call.
     */
 
module.exports = async function(context, simpleObj){
    var url = "https://sdpondemand.manageengine.com/api/v3/requests";
    var connectionLinkName = "<connection name>";
    var method = "POST";
    var requestObj = simpleObj.getParameter("requestObj");
    var bodyObj = {"request" : {"subject" : "Mobile Issue"}};      
    var input_data = "input_data=" + encodeURIComponent(JSON.stringify(bodyObj));
 
    var response = await makeSDPv3APIcall(context, url, connectionLinkName, method, input_data);
    context.log.INFO(response);
}
 
function makeSDPv3APIcall(context, url, connectionLinkName, method, input_data) {
    return new Promise(function(resolve, reject){
        var response = '';
        var connector = context.getConnection(connectionLinkName);
        var connReq = connector.makeRequest({
            url: url,
            method: method,
            headers: {
                "accept": "vnd.manageengine.v3+json",
                "content-type": "application/x-www-form-urlencoded"
            }
        }, function(connRes){
            connRes.on("data", function(data){
                response += data.toString();
            });
            connRes.on("end", function(){
                resolve(response);
            });
            connRes.on("error", function (error) {
                resolve(error);
            });
        });
        connReq.write(input_data);                     // Remove this line in GET call
        connReq.end();
    });
}
 
 

 

Sample Functions:

Node.Js Code returns Boolean:

var data = simpleObj.getParameter("requestObj");
const obj = data.priority;
context.log.INFO(obj.name);
if(obj.name == "Low"){
    return true;
}
return false;
 

Node.Js Code returns RequestObject:

var data = simpleObj.getParameter("requestObj");
var priority = { "name": "Low" };
data.priority = priority;
context.log.INFO(data);
return data;