JavaScript Software Development Kit

JS APIs are JS functions to include various ServiceDesk Plus Cloud functionalities in the custom widget you create.

Add this JavaScript file to all the HTML/widget pages to access the JavaScript APIs from the application: https://sdpondemand.manageengine.com/scripts/v1/widget/sdpclientsdk.min.js.

The JS file must be loaded into every widget page where you want to invoke the APIs. Use the following syntax to add the JS file to the widget pages:

Syntax:

JavaScript API  

While developing a custom widget, you can use JS API functions to invoke calls to your widget or any third-party application. This page documents the various functions that you can use to build your custom widget and its use cases.

General Functions for Custom Widgets 

SDP.init() 

Initializes the JS SDK and defines utility functions by establishing the connection between the product and the custom widget. This function acts as foundational to establish a connection between the custom widget and other JS APIs to make them visible to users. Other JS APIs will be defined only when the initialization is completed.

Returns:

Promise - Resolved with API Success or Rejected with API Failure

Syntax:  

SDP.init().then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.invokeUrl(options) 

Fetch data from integrated third-party applications. The function is mapped under various option params such as URL, method, headers, params, payload, file-id (not supported for probe-based integrations), connection pathway (probe or connection link). You can invoke 3rd party URLs directly or by using connections/probes. By default, 3rd party URLs are invoked directly if no connection or probe is set.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with API Success or Rejected with API Failure.

Syntax: 

SDP.invokeUrl(options).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

To use the variable directly in the invoke URL, refer here.

Manage Custom Widgets iFrame

SDP.openWidget(options) 

Opens a new widget as a pop-up within the custom widget.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.openWidget(options).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.closeWidget() 

Closes the pop-up where the custom widget is loaded. This API is functional only if a widget is opened in a pop-up window, such as menu widget or a widget opened using the SDP.openWidget API.

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.closeWidget().catch(function(response) {
	console.log(response);
});

SDP.closeWidget() call’s successful execution closes the widget popup in the window. Hence success callback is not needed for this API.

Sample:

SDP.resizeWidget(options) 

Resize the custom widget popup as needed. The maximum widget size allowed is 1200X800 pixels.

This API is functional only if a widget is opened in a pop-up window, such as menu widget or a widget opened using the SDP.openWidget API.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.resizeWidget(options).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

Add/Edit/Delete Service Desk Data

SDP.get(options) 

Fetch the widget data such as URLs, or any input data in the custom widget from the server. You can also perform a cross portal call from the custom widget using this function. Note that only SDP V3 APIs can be invoked using this function.

Example: Access a request present in the IT Portal using its URL to the HR Portal.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with API Success or Rejected with API Failure. Refer API documentation for success/failure response formats.

Syntax:

SDP.get(options).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.add(options)

Add data to the server from the custom widget.  You can also perform a cross portal call from the custom widget using this function. Note that only SDP V3 APIs can be invoked using this function.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with API Success or Rejected with API Failure. Refer API documentation for success/failure response formats.

Syntax:

SDP.add(options).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.edit(options) 

Edit data in the server from the custom widget by mentioning the entity ID. You can also perform a cross portal call from the custom widget using this function. Note that only SDP V3 APIs can be invoked using this function.

You can also perform bulk-editing using this function.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with API Success or Rejected with API Failure. Refer API documentation for success/failure response formats.

Syntax:

SDP.edit(options).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.del(options) 

Delete data in the server from the custom widget by mentioning the entity ID.  You can also perform a cross portal call from the custom widget using this function. Note that only SDP V3 APIs can be invoked using this function.

Currently, you can use this function to delete only custom module entities in ServiceDesk Plus Cloud. 

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with API Success or Rejected with API Failure. Refer API documentation for success/failure response formats.

Syntax:

SDP.del(options).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.refreshPage()

Refreshes the page where the widget is loaded. Note that only the page body is loaded, the application header remains untouched.

Example: If the API is called from the right panel widget in a request, the request details page completely reloads.

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.refreshPage();

SDP.refreshPage() call reloads the page which in turn unloads the widget from window. Hence callback is not needed for this API.

SDP.showIndicator(options)

Displays the indicator on the application window after an operation is completed.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure. Success response will be received when the user clicks the action button.

Syntax:

SDP.showIndicator(options).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.hideIndicator(indicator_type) 

Hides the displayed indicator.

Parameters:

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax: 

SDP.hideIndicator(indicator_type).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.showAlert(options)

Displays an alert box when an action is performed in the widget.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure. Success response will be received when the user clicks the action button.

Syntax:

SDP.showAlert(options).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.showConfirm(options)

Displays a confirm dialog box when an action is performed in the widget.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure. Success response will be received when the user clicks the action button and contains the index of the action button.

Syntax:

SDP.showConfirm(options).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

Manage Variables/Connection/Probes in Custom Widget 

SDP.getVariables() 

Fetches all the variables associated with the custom widget.

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.getVariables().then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.getVariable(key) 

Fetches the details of a specified variable from the widget.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.getVariable(key).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.setVariable(key, value) 

Update the value of a variable associated with the widget.

This function is especially useful in Configuration Widgets since they do not have a configuration page in the UI where the variable value can be updated. 

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.setVariable(key, value).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.getTempVariables()

Fetches all temporary variables relevant to the custom widget stored in browser where the ServiceDesk Plus Cloud window is opened.

Temporary variables are used to store values for a limited time, such as until the window reloads.

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.getTempVariables().then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.getTempVariable(key)

Fetches the specified temporary variable.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.getTempVariable(key).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.setTempVariable(key,value)

Set a temporary variable and specify a value to it.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.setTempVariable(key, value).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.getConnections() 

Fetches the details of all successfully installed connections that are associated with the widget.

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.getConnections().then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.getConnection(connectionLinkName)

Fetches the details of a specific connection that is associated with the widget.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.getConnection(connectionLinkName).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.authorizeConnection(connectionLinkName) 

Authorizes the widget's connection by generating a token to the DRE (Deluge Runtime Environment) server. By default, users with permissible roles can authorize connections from the Setup. However, any user can use this JS API to authorize a widget's connection if they don't have access to Setup.

To fetch the post-authorization status, use an event listener to confirm if the authorization is complete

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.authorizeConnection(connectionLinkName).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.revokeConnection(connectionLinkName)

Revokes the widget's connection.

To fetch the status post revoking the connection, use an event listener to confirm if the revoke was complete.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.revokeConnection(connectionLinkName).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.getProbeDetails() 

Fetches the details of the probe that is currently configured with the widget. If no probe is configured for the custom widget, the promise will be rejected.

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.getProbeDetails().then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.setProbeId(probeId)

Associates the probe with the custom widget.

Parameters:

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.setProbeId(probeId).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

APIs exclusive to Add/Edit Request/Problem/Change/Release Form

SDP.showWidget() 

Displays the widgets that are hidden by default in the request/problem/change/release form right panel. You can call this API as per your requirements.

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.showWidget().then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.hideWidget() 

Hides the widgets that are displayed in the right panel of the request/problem/change/release form. You can call this API as per your requirements.

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.hideWidget().then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.setBadgeCount(count) 

Displays the provided count as a badge near the widget name displayed on the request/change form. This count corresponds to a certain value that is used to notify the users, such as available entities or number of options that can be selected.

Parameters:

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.setBadgeCount(count).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.getValueFromForm(field) 

Fetches a field value from the request/change form.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.getValueFromForm(field).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

SDP.setValueInForm(field, value)  

Sets a field value in the request/change form.

Parameters:

* Mandatory parameter

Returns:

Promise - Resolved with Success or Rejected with Failure.

Syntax:

SDP.setValueInForm(field, value).then(function(response) {
	console.log(response);
}).catch(function(response) {
	console.log(response);
});

Sample:

Fetch Custom Widget/User Details  

SDP.getCurrentInstance();

Fetches the details of the instance where the custom widget is loaded.

Returns:

Object – Returns instance details object.

Syntax:

var instanceDetails = SDP.getCurrentInstance();

Sample Response:

{

   appdisplayname: "IT Desk"

   appid: "15459854"

   appname: "itdesk"

}

SDP.getCurrentUserId(); 

Fetches the logged-in user ID.

Returns:

String – Returns user Id as a string.

Syntax:

var userId = SDP.getCurrentUserId();

Sample Response:

"100000000000032197"

SDP.getCurrentUserType();

Fetches the logged-in user type (requester/technician). Note that this function does not fetch roles.

Returns:

String – Returns user type as a string.

Syntax:

var userType = SDP.getCurrentUserType();

Sample Response:

"Technician"

SDP.getCurrentUserName();

Fetches the logged-in user name.

Returns:

String – Returns user name as a string.

Syntax:

var userName = SDP.getCurrentUserName();

Sample Response:

"John Doe"

SDP.getCurrentUserEmail();

Fetches the email address of the current user.

Returns:

String – Returns user email as a string.

Syntax:

var userEmail = SDP.getCurrentUserEmail();

Sample Response:

"johndoe@somecompany.com"

SDP.getWidgetInfo();

Fetches the current widget info.

Returns:

Object – Returns the widget info object.

Syntax:

var widgetInfo = SDP.getWidgetInfo();

Sample Response:

{
    "id": "120747000002587069",

    "name": "Custom Widget",

    "description": "",

    "custom_widget": {

        "id": "120747000002587067"

    }

}

SDP.getWidgetMeta();

Fetches the widget meta passed to the widget.

Returns:

Object – Returns the widget meta-object.

Syntax:

var widgetMeta = SDP.getWidgetMeta();

Sample Response:

{

    "module": "header",

    "instance": {

        "appid": "709641411",

        "appname": "widgetdev",

        "appdisplayname": "Widget Development"

    },

    "personalization": {

        "time_zone": "Asia/Kolkata",

        "time_format": "MMM d, yyyy hh:mm a",

        "date_format": "MMM d, yyyy"

    },

    "userLanguage": "en",

    "userLocale": "en_US",

    "userType": "Technician",

    "userId": "120747000000232217",

    "userName": "Widget Development",

    "userEmail": "widget_dev@sdpdev.onmicrosoft.com",

    "isSDAdmin": true,

    "widget": {

        "id": "120747000002587069",

        "name": "Custom Widget",

        "description": "",

        "custom_widget": {

            "id": "120747000002587067"

        }

    }

}

SDP.getWidgetInvokedLocation();

Fetches the location of the current widget.

Returns:

String – Returns the widget location.

Syntax:

var location = SDP.getWidgetInvokedLocation();

Sample Response:

“webtab”

SDP.getDataPassedByparent();

Fetches the data passed from the parent widget to the child widget by the user when the child widget is opened as a pop-up. The data fetched will be passed only after the SDP.openWidget() is called.

Returns:

Object – Returns the data object passed by the parent widget.

Syntax:

var data = SDP.getDataPassedByparent();

Sample:

{

mode: "new_user"

}

SDP.getParentLocation();

Fetches the location of the parent widget that has called the child widget.

Returns:

String – Returns the parent widget location.

Syntax:

var parentLocation = SDP.getParentLocation();

Sample Response:

“webtab”

SDP.getParentWidgetInfo();

Fetches the details of the parent widget which has called the child widget.

Returns:

Object – Returns the parent widget info object.

Syntax:

var parentInfo = SDP.getParentWidgetInfo();

Sample Response:

{

  "id":"100000000000032273",

  "name":"Sample Widget",

  "description":"Sample Widget",

  "custom_widget":{

   "id":"100000000000032271"

  }

}

Event Listeners 

Event Listeners are functions that are called when a specific event occurs. They are initialized when the widget is loaded. The following event listeners are invoked to all widgets in ServiceDesk Plus Cloud when the DRE connection is authorized or revoked: