Custom Widgets

Custom Widgets bring external services inside ServiceDesk Plus to extend the application's capabilities. They enable you to access third-party applications and web pages from within ServiceDesk Plus. Widgets are embeddable UI components that you can create by using a custom widget package.

You can configure custom widgets to be accessible from the following location:

• Dashboards
• Web Tab
• Request details
• Change details
• Asset details
• Release details
• Custom module details

Create Custom Widget Package 

A custom widget package is a bundle of configuration files and resource files such as html, png, js, or css files that are required to create a custom widget. This helps in embedding third-party applications and extending the functionality of ServiceDesk Plus.

To create a custom widget package,

• Develop an app package using resource files.
• Create a plugin-manifest.json file.
• Compress the app package and plugin-manifest.json file into a zip file.
• Upload the zip file on the custom widget page.

(or)

To create and modify the custom widget using a built-in editor,

In New Custom Widget, select Start building a new widget step by step. After adding the widget, go to the widget details to modify the widget. To learn more, click here.

The following document explains the procedure to create an app package and a plugin-manifest.json file.

 

Develop App Package 

Create a resource file for a widget in the app folder. Generate a URL directing to the landing page of the widget item. Enter this URL while configuring the path URL in the plugin-manifest.json file.

You can use Util functions to establish connection between ServiceDesk Plus and the custom widget. Using Util functions, you can add data to the application server from the custom widget or fetch widget data such as URLs or any data from the custom widget.

Create Plugin-Manifest.JSON File 

The plugin-manifest.json file contains configuration details of the custom widget. Some keys included in this file are optional, while others are mandatory.

Use the following pointers to provide values for the keys:

• Widgets*: A JSON array containing details of custom widget items. You must add at least one widget item in a custom widget package. You can add a maximum of four widget items. Each widget item is required to have the following set of properties.
  • name*: Name of the widget item (max of 100 characters).
  • description: A brief explanation of the widget item.
  • path url*: The URL path of the widget item. Sample format: ("/app/index.html")

 

• PropertyJSON: Contains properties of the custom widget item.
  • white_list: Enter the domain URL pathway to make an API call. Sample format: ("api.zoom.us")
  • visible_to: Restrict the availability of custom widgets to users based on roles.
  • icons: An optional key to provide icons for your widget items. By default, an icon is generated based on the widget item name. You can upload an icon of up to 30x30 pixels in size by entering the icon URL as the value for the 30X30 key in the plugin manifest file. Icons are rendered dynamically as dark or light based on the application theme.
  • Themed Icons: You can provide different icons for different themes. The URL for themed icons should include a "dark" or a "light" version. Sample format: "icons": {"dark": "/app/[icon-name].png", "light": "/app/[icon-name].png"}.
• Locations*: Define the location in ServiceDesk Plus where custom widgets can be rendered. You must provide at least one location of your widget item. Currently, you can configure custom widgets in the following locations:

 

Location	JSON Key Format	Description
Web Tab	"webtab"	The custom widget is added as a web tab in the navigation pane.
Home	"dashboard" (for Technicians and Requesters)	Custom widgets are embedded on the dashboard. Dashboard widgets can only be enabled. To add a widget, click New > New Widget on the dashboard.
		If the custom widget is enabled for requesters, the dashboard widget can be embedded on the requester portal home page. To add a widget to the requester portal, customize the Requester Home Page and add the widget from the list of canned widgets.
Request Details Page	"request.detail.tab"	Added as a tab in the request details page.
	"request.detail.rightpanel"	Added to the right panel in the request details page.
Change Details Page	"change.detail.tab"	Added as a tab in the change details page.
	"change.detail.rightpanel"	Added to the right panel in the change details page.
Release Details Page	"release.detail.tab"	Added as a tab on the release details page.
	"release.detail.rightpanel"	Added to the right panel in the release details page.
Asset Details Page	"asset.detail.tab"	Added as a tab on the asset details page.
	"asset.detail.rightpanel"	Added to the right panel in the asset details page.
Custom Module Details Page	"cm_{modulename}.detail.tab"	Added as a tab on the custom module details page.
	"cm_{modulename}.detail.rightpanel"	Added to the right panel in the custom module details page

 

Additional Configurations 

Additional configurations such as Connections or Modules enhance the capabilities of custom widgets. The scope of additional configurations is either limited to the widget item level or applicable globally for all widget items.

Configure Connections: 

Connections allow you to integrate custom widgets with third-party APIs. You can access third-party applications from a custom widget by configuring connections in the widget package. You can add up to four connections to a custom widget.

To configure connections in the plug-in manifest file, you can copy the connection details as a JSON string directly after the connection is created. Go to Admin > Developer Space > Connections and copy the JSON code snippet from the connection details page.

• To allow users to authorize connections in the plugin-manifest file, set the "userAccess" as "true".

• To restrict authorization only to the SDAdmin who installed the custom widget, set "userAcess" as "false"

 

 An illustration of connections configured in the plugin-manifest file:

 

Configure Modules: 

Modules allow you to collect and store additional data. Data can be populated and managed in the custom module widgets using JS APIs, APIs, or from the application. Custom module details can be updated/deleted only via the custom widget.

The display name, display plural name, and API name of the custom module are unique in the application. Add unique values to the respective fields in the plugin-manifest file.

 

An illustration of modules configured in the plugin-manifest file:

 

Sample plugin-manifest.json file