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

• name*: Name of the widget item (max of 100 characters).
• description*: A brief explanation for your widget item.
• 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.
  • 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.
    For example, If you have the widget.html inside the app folder, provide path_url as /app/widget.html.
  • 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 Cloud via custom widgets.
• 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.
  • 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"}.
  • 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".

• locations*: Defines the location in ServiceDesk Plus 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:

(hover over the JSON keys to preview the custom widget's display location in the application. Note that the images are placeholders used for illustrative purposes only.)

Additional Configurations:

Apart from the above-mentioned specifications, you can also configure optional configurations such as probe, 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:

• true - display configuration popup screen.
• false - do not display configuration popup screen.

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 probe, connection, or variable details instantly from this popup.

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'.

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.

"cspDomains": {
    "connect-src": [""]
  },

Permissions:

The following permissions are allowed by default:

"permissions":[
"allow-forms",
"allow-scripts",
"allow-same-origin",
"allow-popups",
]

Refer here to learn more about sandbox permissions.

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:

• true - If the header must be displayed for the corresponding widget item in Dashboard.
• false - If the header must be hidden for the corresponding widget item in Dashboard.

Configure Probe:

Probe is an application used to integrate custom widgets with On-Premise applications. Install the probe in the same network as the On-Premise products and the corresponding probe should be configured/associated with the custom widget. A custom widget can be configured or associated with only one probe.

Use probe_config_required key to specify if probe configuration is required for the custom widget. The probe_config_required key is only used to enable probe configuration from the UI. Even if the key is disabled, you can still configure probes using JS APIs.

Provide the key value as follows:

• true - Probe selection is required in UI.
• false- Probe selection is not required in UI.

After you upload the widget package to ServiceDesk Plus Cloud, you can configure the probe values from the custom widgets list view.

Click here to know more about probes.

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 Admin > 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"

"connections": [
{
"connectionLinkName": "zohotest",
"connectionName": "Zoho",
"serviceName": "zlabs_integration",
"userAccess": true,
"isUserDefinedService": false,
"sharedBy": "709641411",
"scope": [
"SDPOnDemand.requests.ALL"
]
}
]

An illustration of connections configured in the plugin-manifest file

Click here to know more about connections.

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.

Variables contain 3 parameters:

• Key* - Defines the variable name. This is a mandatory parameter. Maximum characters allowed - 100.
• Value - Defines the value held by the variable. You can define the variable value in the widget package, if needed. Maximum characters allowed - 500.
• Secure - Defines if the variable value should be encrypted in the database.
  • true: If the values entered should be encrypted
  • 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:

"variables": 
[
	{
	{
	"key" : "url",
	"secure" : false
	},
	{
	"key" : "configuration",
	"secure" : false
	"value": {"domain":ADManager Plus","probeid":"#45","token":"25","probe":true"}
	}
]

 In this illustration, you can fetch the variables in JS APIs in a function as follows:

SDP.invokeURL({
	url: "${url}/RestAPI/SearchUser",
	method: "post",
	params : {AuthToken:"${configuration.token}"},
	is_probe_connection : true
})

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}.

Configure Modules: 

Users can create custom modules along with custom widgets in ServiceDesk Plus 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:

You can configure the following keys for custom modules in plugin manifest file:

• Use display_type key to specify the type of custom module to be created:
  • web_tab - Web tabs are accessible from the navigation pane
  • custom_configuration - Custom configurations that are accessible only from Setup.
  • hidden - Hidden modules are not accessible from the UI and are managed only via API/JS API calls.

• Use import_enabled key to allow users to import data to the custom module. Provide the key value by using the below pointers:
  • true - Data can be imported to the custom module.
  • false - Default value; data cannot be imported to the custom module. 

• 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:
  • true - Reports can be generated from the custom module.
  • false - Default value; reports cannot be generated from the custom module.

• Use allow_all_technicians key to allow all technicians to access the custom module. Provide the key value by using the below pointers:
  • true - All technicians can access the custom module. Default value for web tabs and hidden modules.
  • false - The custom module is accessible to users depending on the users' role permissions. Default value for custom configurations.

"modules":[{
	"display_name": "TechVsAuthtokenMap",
	"display_name_plural": "TechVsAuthtokenMap",
	"name": "cm_techvsauthtokenmap",
	"fields": [
	{
	"field_type": "Single Line",
	"field_key": "txt_idone",
	"name": "ID",
	"constraints": {
	"unique": "true"
	}
	},
	{
	"field_type": "Single Line",
	"field_key": "txt_authtoken",
	"encrypted": true,
	"name": "AuthToken"
	},
	{
	"field_type": "Single Line",
	"field_key": "txt_usernameadmp",
	"name": "ADManager Plus User Name"
	},
	{
	"field_type": "Single Line",
	"field_key": "txt_useridadmp",
	"name": "ADManager Plus User Id"
	},
	{
	"field_type": "Single Line",
	"field_key": "txt_usernamesdp",
	"name": "SDP-OD User Name"
	},
	{
	"field_type": "Single Line",
	"field_key": "txt_domain",
	"name": "Domain"
	}
	],
	"configurations": {
	"display_type": "hidden",
	"import_enabled": "false",
	"report_enabled": "true",
	"allow_all_technicians": "true"
	}
}]

An illustration of modules configured in the plugin-manifest file

Custom modules created by custom widgets are indicated with icon under Setup > Developer Space > Custom Modules.

Click here to learn more about custom modules.

Sample plugin-manifest.json file  

{
    "service": "SDP",
    "type": "personal",
    "modules": [
        {
            "display_name": "TeamViewer_session",
            "display_name_plural": "TeamViewer_sessions",
            "name": "cm_teamviewerSession",
            "fields": [
                {
                    "field_type": "Single Line",
                    "field_key": "txt_request_id",
                    "name": "request_id"
                },
                {
                    "field_type": "Single Line",
                    "field_key": "txt_technician_id",
                    "name": "technician_id"
                },
                {
                    "field_type": "Single Line",
                    "field_key": "txt_session_code",
                    "name": "session_code",
                    "constraints": {
                        "unique": "true"
                    }
                },
                {
                    "field_type": "Single Line",
                    "field_key": "txt_requester_name",
                    "name": "requester_name"
                },
                {
                    "field_type": "Single Line",
                    "field_key": "txt_requester_id",
                    "name": "requester_id"
                },
                {
                    "field_type": "Date/Time Field",
                    "field_key": "date_created_at",
                    "name": "created_at"
                },
                {
                    "field_type": "Date/Time Field",
                    "field_key": "date_valid_till",
                    "name": "valid_till"
                },
                {
                    "field_type": "Single Line",
                    "field_key": "txt_session_type",
                    "name": "session_type"
                },
                {
                    "field_type": "Single Line",
                    "field_key": "txt_is_report_enabled",
                    "name": "is_report_enabled",
                    "default_value": "true"
                },
                {
                    "field_type": "Single Line",
                    "field_key": "txt_state",
                    "name": "state",
                    "default_value": "Open"
                }
            ],
            "configurations": {
                "display_type": "hidden"
            }
        },
        {
            "display_name": "TeamViewer_connection",
            "display_name_plural": "TeamViewer_connections",
            "name": "cm_teamviewerConnection",
            "fields": [
                {
                    "field_type": "Single Line",
                    "field_key": "txt_session_code",
                    "name": "session_code"
                },
                {
                    "field_type": "Single Line",
                    "field_key": "txt_supporter_name",
                    "name": "supporter_name"
                },
                {
                    "field_type": "Date/Time Field",
                    "field_key": "date_start_date",
                    "name": "start_date"
                },
                {
                    "field_type": "Date/Time Field",
                    "field_key": "date_end_date",
                    "name": "end_date"
                },
                {
                    "field_type": "Multi Line",
                    "field_key": "txt_connection_notes",
                    "name": "connection_notes"
                }
            ],
            "configurations": {
                "display_type": "hidden"
            }
        }
    ],
    "widgets": [
        {
            "name": "TeamViewer",
            "description": "A widget that allows technicians to gain remote access to devices across different platforms.",
            "path_url": "/app/tv_widget.html",
            "icons": {
                "30x30": "/app/img/TV_icon.png"
            },
            "locations": [
                "request.detail.rightpanel"
            ]
        }
    ],
    "connections": [
        {
            "connectionLinkName": "Teamviewer",
            "connectionName": "Teamviewer",
            "serviceName": "teamviewer",
            "userAccess": true,
            "isUserDefinedService": false,
            "sharedBy": "709641411"
        }
    ],
    "config_popup_required": false
}