Custom Widget Specifications

Custom Widget Specifications

The package directory of your custom widget includes a plugin-manifest.json file. This file contains the configuration details of your custom widget. While some keys included in this file are optional, others are mandatory.

Use the following pointers to provide values for the keys:
(* indicates mandatory parameters)
Service*: The Zoho product for which your custom widget is created. While creating a custom widget for ServiceDesk Plus MSP Cloud, the service key will be auto-populated in the manifest as "service": "SDP".

Type*: Type is set as Personal by default. It indicates that the widget details are uploaded to an instance via API. Users are advised not to modify Type in any circumstances.

Widgets*: An JSON array of the details for your custom widget item. You must add at least 1 widget item in a custom widget package. You can add a maximum of 3 widget items. Each widget item is required to have the following set of properties.

  1. Name*: Name of the widget item (max of 100 characters).
  2. Description*: A brief explanation for your widget item.
  3. Path_url*: URL path defined for the widget items. Path URL identifies the pages to be embedded when the widget is loaded. The path_URL can either be absolute or relative to the 'app' folder within the package directory.
    1. Relative URL - Relative URL defines the path of a file to be loaded from the app folder. Construct the path_url relative to app folder to render the widget page in the product.
    2. For example, If you have the widget.html inside the app folder, provide path_url as /app/widget.html.
    3. Absolute URL - Absolute URLs are used to render hosted pages inside a custom widget. For example, you can directly mention the hosted domain URL of your knowledge base to fetch solution articles into ServiceDesk Plus MSP Cloud via custom widgets.
  4. Icons: Optional key using which you can provide icons for your widget items. By default, the icon contains letters pertaining to the name of the widget item. 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. The icon URL can either be absolute or relative to the 'app' folder within the package directory. Icons can be rendered to appear depending on the application theme or static.
  5. Themed Icons - The icon will be rendered dynamically as dark or light, based on the application theme. Currently, this is applicable only for the web tab icons. Users can upload different icons for different themes.  A sample of relative url to be appended for the dark and light icons is constructed as follows: "30x30": {"dark": "/app/[icon-name].png","light": "/app/[icon-name].png"}.
  6. Fixed Icons - The icon will appear static, as uploaded by the user. A sample of relative url to be appended is constructed as follows: "30x30":"/app/[icon-name].jpg".

Info
When themed icons are in use, only light icon will be rendered in widget locations other than web tabs. If no light icon is found, only the text will be rendered. 

Note that only PNG, JPG, or JPEG file formats are supported.  
  1. locations*: Defines the location in ServiceDesk Plus MSP Cloud where custom widgets can be rendered. You must provide at least 1 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 the widget, edit the dashboard and click Customize to select the custom widget from the list of available widgets.
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.menu"
Added as a custom menu option in the toolbar of the request details page. Custom menu widgets are only enabled. To add the custom widget to custom menu, select the widget as the custom menu action.
"request.detail.subtab"
Added as a sub-tab in request details page.
"request.detail.rightpanel"
Added to the right panel in the request details page.
Add/Edit Request Form
"request.form.rightpanel"
Added as a dynamic widget to the right panel in the request form. By default, this custom widget is displayed only if specified by the user.
You can configure the widget visibility using JS APIs.
Change Details page
"change.detail.menu"
Added as a custom menu option in the toolbar of the change details page. Custom menu widgets are only enabled. To add the custom widget to the custom menu, select the widget as the custom menu action.
"change.detail.subtab"
Added as a sub-tab in change details page
"change.detail.rightpanel"
Added to the right panel in the change details page.
"change.stage.detail.subtab"
Added as a sub-tab to any change stage in the change details page. You can select the change stages where the widget must be displayed from Setup > Developer Space > Custom Widgets after installing the widget package.
Add/Edit Change Form
change.form.rightpanel
Added as a dynamic widget to the right panel in the change form. By default, this custom widget is displayed only if specified by the user.
Problem details page
"problem.detail.menu"
Added as a custom menu in the toolbar of the problem details page. Custom menu widgets are only enabled. To add the custom widget to the custom menu, select the widget as the custom menu action.
 
"problem.detail.rightpanel"
Added to the right panel on the problem details page.
 
"problem.detail.subtab"
Added as a sub-tab on the problem details page.
Release details page
"release.detail.menu"
Added as a custom menu in the toolbar of the release details page. Custom menu widgets are only enabled. To add the custom widget to the custom menu, select the widget as the custom menu action.
"release.detail.subtab"
Added as a sub-tab on the release details page.
"release.detail.rightpanel"
Added to the right panel on the release details page.  
 
"release.stage.detail.subtab"
Added as a sub-tab to any release stage in the release details page. You can select the release stages where the widget must be displayed from Setup > Developer Space > Custom Widgets after installing the widget package.
Project details page
"project.detail.menu"
Added as a custom menu in the toolbar of the project details page. Custom menu widgets are only enabled. To add the custom widget to custom menu, select the widget as the custom menu action.
Asset details page
"asset.detail.menu"
Added as a custom menu in the toolbar of the asset details page. Custom menu widgets are only enabled. To add the custom widget to custom menu, select the widget as the custom menu action.
"asset.detail.subtab"
Added as a sub-tab on the asset details page. You can select the product types for which the widget must be displayed from Setup > Developer Space > Custom Widgets after installing the widget package.
"asset.detail.rightpanel"
Added to the right panel on the asset details page.  You can select the product types for which the widget must be displayed from Setup > Developer Space > Custom Widgets after installing the widget package.
Purchase order details page
"purchaseorder.detail.menu"
Added as a custom menu in the toolbar of the purchase order details page. Custom menu widgets are only enabled. To add the custom widget to custom menu, select the widget as the custom menu action.
Contract details page
"contract.detail.menu"
Added as a custom menu in the toolbar of the contract details page. Custom menu widgets are only enabled. To add the custom widget to custom menu, select the widget as the custom menu action.
Setup
"configuration"
Configuration widgets are crude widgets that are not published to users and are accessible only to Administrators. Configuration widgets mainly serve as an alternative to the default UI configurations. Users can use configuration widgets to fetch the widget configurations in their own UI.

To access the widget,
  1. Go to Setup > Developer Space > Custom Widgets.
  1. Click the configuration widget name. The configuration widget opens in a pop-up window.
Info
The widget or widget item must be specified in at least one other location to enable the configuration widget.
 
 

 Additional Configurations   

Apart from the above-mentioned specifications, you can also configure optional configurations such as connections or variables to your custom widget to enhance its capabilities in the plugin-manifest file. The scope of the additional configurations is either limited to the widget item level or applicable globally for all widget items.

Refer to the sample file for more details.

Configuration Pop-Up

Use config_popup_required key to specify if you want to display the configurations on a pop-up screen to the user after the widget package is saved. This is a one-time action.

Enter the key values as:
  1. true - display configuration pop-up.
  2. false - do not display configuration pop-up.
The details displayed on the pop-up depend on the presence of configuration widgets. If no configuration widget is enabled, the default widget configuration pop-up will be displayed where you can update the connection or variable details instantly from this pop-up.

Info
The widget configuration pop-up will be opened only if a connection or variable is present and enabled in the manifest.  
Default Widget Configuration pop-up

If a configuration widget is enabled, the widget will be displayed on the pop-up menu instead of the default configuration page. If multiple configuration widgets are added from one widget package, the config_popup_required key value will be ignored even if its value is set as 'true'.

Info
Scope: This configuration is globally scoped.

CSP Domains

This following key defines the list of sites from which you want to load third-party assets such as JavaScript, CSS, and so on. If you need to load any third-party scripts, CSS, or other files, you need to add them to the 'connect-src' list.
  1. "cspDomains": {
  2.     "connect-src": [""]
  3.   },
Info
 Scope: This configuration is globally scoped. 

Permissions

The following permissions are allowed by default:
  1. "permissions":[
  2. "allow-forms",
  3. "allow-scripts",
  4. "allow-same-origin",
  5. "allow-popups",
  6. ]
Additionally, you can include the allow-downloads permission in the plugin-manifest.json file.

Refer here to learn more about sandbox permissions.
Info
Scope: This configuration is globally scoped. 

Display Widget Header

Use show_widget_header_in_dashboard key to specify if you want to display the widget item name as the widget header on the dashboard. This key can be used only if the widget location is configured as Dashboard. Provide a key value by using the below pointers:
  1. true - If the header must be displayed for the corresponding widget item in dashboard.
  2. false - If the header must be hidden for the corresponding widget item in dashboard.
Info
Scope: This configuration is specific to each widget item. If a custom widget package has multiple widget items, you can set this key unique to each widget item. 
 

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 the connection in the widget package. Note that you can add up to 5 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 Setup > Developer Space > Connections and copy the JSON code snippet from the connection details page.

You can set the "userAccess" as "true" to allow users to authorize connections individually in the plugin-manifest file. 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:

  1. "connections": [
  2. {
  3. "connectionLinkName": "zohotest",
  4. "connectionName": "Zoho",
  5. "serviceName": "zlabs_integration",
  6. "userAccess": true,
  7. "isUserDefinedService": false,
  8. "sharedBy": "709641411",
  9. "scope": [
  10. "SDPOnDemand.requests.ALL"
  11. ]
  12. }
Info
Scope: This configuration is globally scoped. Connections are configured for all custom widget items.
Info
When a custom widget is deleted, the associated connections will also be deleted.  

Configure Variables

Variables are entities that store key values and are scoped to a particular component, in this case - custom widgets. You can create up to 5 variables for a custom widget to hold user-specific values. Variables can hold only string values.
Info
You can convert JSON array or JSON objects as strings and save them as variables.
Variables contain 3 parameters:
  1. Key - Defines the variable name. This is a mandatory parameter. Maximum characters allowed - 100.
  2. Value - Defines the value held by the variable. You can define the variable value in the widget package, if needed. Maximum characters allowed - 500.
  3. Secure - Defines if the variable value should be encrypted in the database.
    1. true: If the values entered should be encrypted
    2. false: If the values need not be encrypted.
Variables can be used as dollar variables ${variable_key} while making API calls to third-party applications. Dollar variables are automatically parsed by the server. If the user has stored a JSON object to a variable key, each stored JSON property value can be directly used in API calls using dollar variables in the syntax of ${variable_key.property)
For better understanding, refer to the illustration below:
  1. "variables":
  2. [
  3. {
  4. {
  5. "key" : "url",
  6. "secure" : false
  7. },
  8. {
  9. "key" : "configuration",
  10. "secure" : false
  11. "value": {"domain":ADManager Plus","probeid":"#45","token":"25","probe":true"}
  12. }
  13. ]
In this illustration, you can fetch the variables in JS APIs in a function as follows:
  1. SDP.invokeURL({
  2. url: "${url}/RestAPI/SearchUser",
  3. method: "post",
  4. params : {AuthToken:"${configuration.token}"},
  5. is_probe_connection : true
  6. })
The url variable is fetched directly as ${url}.

The configuration variable has several JSON objects stored as keys - domain, probeid, token, and probe. The key value of token is fetched using ${configuration.token}.
Info
Scope: This configuration is globally scoped. Variables are configured for all custom widget items.
Info
 When a custom widget is deleted, the associated variables will also be deleted.  

Configure Modules

Users can create custom modules along with custom widgets in ServiceDesk Plus MSP Cloud.

The admin configurations are dependent on the custom widget and so the custom module details can be updated/deleted only via the custom widget. However, data can be populated and managed in the custom module widgets using JS API, API, or from the application.

The display name, display name plural, and API name of the custom module are unique in the application. Therefore, ensure you add unique values to the respective fields in the plugin-manifest file as well.
While configuring custom modules in the plugin-manifest file, ensure that the custom module name and field names are prefixed with the right API prefix names as shown below:

 
Prefix
Example
Custom module name
cm_
"cm_webtab"
Text fields
txt_
"txt_employee_name"
Numeric fields
num_
"num_ID"
Date fields
date_
"date_created_date"
Lookup fields
ref_
"ref_vendor"
Decimal/Currency/Percent fields
dbl_
"dbl_cost"
Decision Boxes
bool_
"bool_resources"
 
You can configure the following keys for custom modules in plugin_manifest file:
  1. Use display_type key to specify the type of custom module to be created:
    1. web_tab - Web tabs are accessible from the navigation pane
    2. custom_configuration - Custom configurations that are accessible only from Setup.
    3. hidden - Hidden modules are not accessible from the UI and are managed only via API/JS API calls.
Info
Web tabs and custom configurations are already functional in ServiceDesk Plus for all users. However, hidden modules are unique to custom widgets and cannot be created by users otherwise.  

 If display_type is not specified, the custom module will be hidden by default. 


  1. Use import_enabled key to allow users to import data to the custom module. Provide the key value by using the below pointers:
    1. true - Data can be imported to the custom module.
    2. false - Default value; data cannot be imported to the custom module.
Info
 For hidden modules, import_enabled key will be set as "false". This cannot be modified. 
  1. Use report_enabled key to allow users to generate reports from the data populated in the custom module. Provide the key value by using the below pointers:
    1. true - Reports can be generated from the custom module.
    2. false - Default value; reports cannot be generated from the custom module.
  2. Use allow_all_technicians key to allow all technicians to access the custom module. Provide the key value by using the below pointers:
    1. true - All technicians can access the custom module. Default value for web tabs and hidden modules.
    2. false - The custom module is accessible to users depending on the users' role permissions. Default value for custom configurations.
An illustration of modules configured in the plugin-manifest file:
  1. "modules":[{
  2. "display_name": "TechVsAuthtokenMap",
  3. "display_name_plural": "TechVsAuthtokenMap",
  4. "name": "cm_techvsauthtokenmap",
  5. "fields": [
  6. {
  7. "field_type": "Single Line",
  8. "field_key": "txt_idone",
  9. "name": "ID",
  10. "constraints": {
  11. "unique": "true"
  12. }
  13. },
  14. {
  15. "field_type": "Single Line",
  16. "field_key": "txt_authtoken",
  17. "encrypted": true,
  18. "name": "AuthToken"
  19. },
  20. {
  21. "field_type": "Single Line",
  22. "field_key": "txt_usernameadmp",
  23. "name": "ADManager Plus User Name"
  24. },
  25. {
  26. "field_type": "Single Line",
  27. "field_key": "txt_useridadmp",
  28. "name": "ADManager Plus User Id"
  29. },
  30. {
  31. "field_type": "Single Line",
  32. "field_key": "txt_usernamesdp",
  33. "name": "SDP-OD User Name"
  34. },
  35. {
  36. "field_type": "Single Line",
  37. "field_key": "txt_domain",
  38. "name": "Domain"
  39. }
  40. ],
  41. "configurations": {
  42. "display_type": "hidden",
  43. "import_enabled": "false",
  44. "report_enabled": "true",
  45. "allow_all_technicians": "true"
  46. }
  47. }]
Custom modules created by custom widgets are indicated with under Setup > Developer Space > Custom Modules.


Info
 Scope: This configuration is specific to each widget item. If a custom widget package has multiple widget items, the user can configure custom modules uniquely for each widget item. 
Info
 When a custom widget is deleted, the associated custom modules will also be deleted.  

What is the purpose of extra configurations in custom widgets when the same are available in ServiceDesk Plus MSP Cloud already?

ServiceDesk Plus MSP Cloud offers functionalities such as probes, connections, global variables, and custom modules by itself. The same features are also packaged in Custom Widgets to allow easy accessibility to users. Administrators can pack all the features in one page within the application so users can avoid navigating through several pages and access all functionalities from a single widget.

 

Sample plugin-manifest.json file   

  1. {
  2.     "service": "SDP",
  3.     "type": "personal",
  4.     "modules": [
  5.         {
  6.             "display_name": "TeamViewer_session",
  7.             "display_name_plural": "TeamViewer_sessions",
  8.             "name": "cm_teamviewerSession",
  9.             "fields": [
  10.                 {
  11.                     "field_type": "Single Line",
  12.                     "field_key": "txt_request_id",
  13.                     "name": "request_id"
  14.                 },
  15.                 {
  16.                     "field_type": "Single Line",
  17.                     "field_key": "txt_technician_id",
  18.                     "name": "technician_id"
  19.                 },
  20.                 {
  21.                     "field_type": "Single Line",
  22.                     "field_key": "txt_session_code",
  23.                     "name": "session_code",
  24.                     "constraints": {
  25.                         "unique": "true"
  26.                     }
  27.                 },
  28.                 {
  29.                     "field_type": "Single Line",
  30.                     "field_key": "txt_requester_name",
  31.                     "name": "requester_name"
  32.                 },
  33.                 {
  34.                     "field_type": "Single Line",
  35.                     "field_key": "txt_requester_id",
  36.                     "name": "requester_id"
  37.                 },
  38.                 {
  39.                     "field_type": "Date/Time Field",
  40.                     "field_key": "date_created_at",
  41.                     "name": "created_at"
  42.                 },
  43.                 {
  44.                     "field_type": "Date/Time Field",
  45.                     "field_key": "date_valid_till",
  46.                     "name": "valid_till"
  47.                 },
  48.                 {
  49.                     "field_type": "Single Line",
  50.                     "field_key": "txt_session_type",
  51.                     "name": "session_type"
  52.                 },
  53.                 {
  54.                     "field_type": "Single Line",
  55.                     "field_key": "txt_is_report_enabled",
  56.                     "name": "is_report_enabled",
  57.                     "default_value": "true"
  58.                 },
  59.                 {
  60.                     "field_type": "Single Line",
  61.                     "field_key": "txt_state",
  62.                     "name": "state",
  63.                     "default_value": "Open"
  64.                 }
  65.             ],
  66.             "configurations": {
  67.                 "display_type": "hidden"
  68.             }
  69.         },
  70.         {
  71.             "display_name": "TeamViewer_connection",
  72.             "display_name_plural": "TeamViewer_connections",
  73.             "name": "cm_teamviewerConnection",
  74.             "fields": [
  75.                 {
  76.                     "field_type": "Single Line",
  77.                     "field_key": "txt_session_code",
  78.                     "name": "session_code"
  79.                 },
  80.                 {
  81.                     "field_type": "Single Line",
  82.                     "field_key": "txt_supporter_name",
  83.                     "name": "supporter_name"
  84.                 },
  85.                 {
  86.                     "field_type": "Date/Time Field",
  87.                     "field_key": "date_start_date",
  88.                     "name": "start_date"
  89.                 },
  90.                 {
  91.                     "field_type": "Date/Time Field",
  92.                     "field_key": "date_end_date",
  93.                     "name": "end_date"
  94.                 },
  95.                 {
  96.                     "field_type": "Multi Line",
  97.                     "field_key": "txt_connection_notes",
  98.                     "name": "connection_notes"
  99.                 }
  100.             ],
  101.             "configurations": {
  102.                 "display_type": "hidden"
  103.             }
  104.         }
  105.     ],
  106.     "widgets": [
  107.         {
  108.             "name": "TeamViewer",
  109.             "description": "A widget that allows technicians to gain remote access to devices across different platforms.",
  110.             "path_url": "/app/tv_widget.html",
  111.             "icons": {
  112.                 "30x30": "/app/img/TV_icon.png"
  113.             },
  114.             "locations": [
  115.                 "request.detail.rightpanel"
  116.             ]
  117.         }
  118.     ],
  119.     "connections": [
  120.         {
  121.             "connectionLinkName": "Teamviewer",
  122.             "connectionName": "Teamviewer",
  123.             "serviceName": "teamviewer",
  124.             "userAccess": true,
  125.             "isUserDefinedService": false,
  126.             "sharedBy": "709641411"
  127.         }
  128.     ],
  129.     "config_popup_required": false
  130. }

    • Related Articles

    • Develop Custom Widget Package

      Command Line Interface (CLI) is used to create and package custom widgets. ZET command is the CLI used to package custom widgets for ServiceDesk Plus MSP Cloud. Pre-requisites: In order to create your own custom widgets for ServiceDesk Plus MSP ...

    • Validate and Pack Widget

      Execute the following command to validate your custom widget: $ zet validate Your custom widget needs to follow the widget specifications. Running the 'zet validate' command will identify violations of the specifications if any. An illustration on ...

    • Add Custom Widget

      Add Custom Widget to ServiceDesk Plus MSP Cloud Role Required: SDAdmin Go to Setup > Developer Space > Custom Widgets and click New Custom Widget. Follow the steps mentioned below to configure your own custom widget. Provide a name and description to ...

    • 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" ...

    • Manage Variables/Connection 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) ...