Custom Widgets

Custom Widgets bring external services inside AssetExplorer Cloud and extend the capabilities of the application. Widgets are embeddable UI components that you can create on your own by using JS Software Development Kit. Custom widgets allow you to access third-party applications and web pages from within AssetExplorer Cloud.

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

Dashboards
Web Tab
Asset custom menu, asset details - right panel, asset details - tab
Configuration Widgets under Setup.

Custom Widgets are available only for Enterprise versions of AssetExplorer Cloud.

Create 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 AssetExplorer Cloud.

Pre-requisites

To create your custom widgets for AssetExplorer Cloud, you are required to download the node.js (versions below 7 are not supported).

Click here to download node.js

You can verify the node by running the following commands from the command prompt:

$ node -v (verifies the version of the node)
$ npm -v (verifies the version of the npm)

An illustration on verifying node installation on macOS terminal

Install ZET CLI

You can install the ZET (Zoho Extension Kit) CLI using the below command:

$ npm install -g zoho-extension-toolkit

Alternatively, you can click here for more details on how to install ZET (Zoho Extension Toolkit).

An illustration on installing ZET on macOS terminal

Run the following ZET command to verify the installation. On executing this command, help content for various support commands will be displayed:

$ zet

An illustration on viewing the help commands for ZET on macOS terminal

Create Custom Widget Package

Create a package with the following command:

$ zet init

Navigate through the list of Zoho services displayed using your up/down arrow keys to select AssetExplorer Cloud and press Enter.

You will be prompted to provide a package name. Type the preferred package name and press Enter.

Package names can contain only alphanumeric characters separated by an underscore.

Include Resources

After providing the package name, a directory will be created with the same name on your system. This directory contains all folders, files, and packages required to configure your custom widget.

By default, the initial directory contains pre-packed folders and files that are key to setting up the custom widget.

An illustration of the initial package directory

Navigate to the package directory and open the app folder. Include the resources of your custom widget into the relevant sub-folders.

You can add resources to your custom widget by specifying the 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 AssetExplorer 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 one 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 of your widget item.
path_url*: URL path defined for the widget item. 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 AssetExplorer 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".

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

Only PNG, JPG, or JPEG file formats are supported.

locations*: Defines the location in AssetExplorer Cloud 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 the widget, edit the dashboard and click Customize to select the custom widget from the list of available widgets.
Home	"dashboard" (for Technicians and Requesters)	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.
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. Click here to learn how to add custom widgets to custom menu.
	"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 Admin > 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 Admin > Developer Space > Custom Widgets after installing the widget package.
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, Go to Setup > Developer Space > Custom Widgets. Click the configuration widget name. The configuration widget opens in a pop-up window. 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 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.

The widget configuration pop-up will be opened only if a probe, connection, or variables are 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'.

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:

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.

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.

Display Custom Widget to Requester

Use show_to_requester key to specify whether to display the custom widget to the requester. Provide the key value by using the below pointers:

true - If the widget must be displayed for requesters.
false - If the widget must be hidden for requesters.

Scope: This configuration is specific to each widget item. If a custom widget package has multiple widget items, the user can configure this key unique to each widget item.

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 AssetExplorer Cloud, you can configure the probe values from the custom widgets list view.

Scope: This configuration is globally scoped. Probes are configured for all custom widget items.

You cannot configure probes for configuration widgets from the application UI.

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":"twitter",
"connectionName":"twitter",
"serviceName":"twitter",
"userAccess":false,
"isUserDefinedService":false
}
],

An illustration of connections configured in the plugin-manifest file

Scope: This configuration is globally scoped. Connections are configured for all custom widget items.

When a custom widget is deleted, the associated connections will also be deleted.

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.

You can convert JSON array or JSON objects as strings and save them as variables.

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

Scope: This configuration is globally scoped. Variables are configured for all custom widget items.

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

The admin configurations are dependent on the custom widget, 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:

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.

Web tabs and custom configurations are already functional in AssetExplorer 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.

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.

For hidden modules, import_enabled key will be set as "false". This cannot be modified.

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.

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.

When a custom widget is deleted, the associated custom modules will also be deleted.

Click here to learn more about custom modules.

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

AssetExplorer 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

{
    "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
}

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 validating ZET installation on macOS terminal

Any violations in widget specifications need to be rectified before uploading the widget package. Note that only a basic validation of the configurations is performed.

Run the below command to create a zip with all the files and folders required for the running of your custom widget:

$ zet pack

An illustration on packing custom widget files on macOS terminal

The zip is present in the 'dist' folder of your package directory. You can upload this zip to the custom widget page in AssetExplorer Cloud.

Add Custom Widget

Role Required: SDAdmin

Go to Setup > Developer Space > Custom Widgets.
Click New Custom Widget.
Follow the steps mentioned below to configure your custom widget.
Provide a name and description to your custom widget.
Select the status of your custom widget.

Enable - Enabled custom widgets will be displayed at their corresponding locations and are accessible for users.
Disable - Disabled custom widgets are not displayed at their locations. They are accessible only to the administrators. Custom Widgets can be disabled during creating to ensure all dependencies are installed successfully. This helps to avoid errors or issues when users access the custom widget.

Upload the zip file that contains the custom widget package. Note that the file size can be 5 MB at the maximum.
Choose where to host your app:

Sigma Server - You can host your custom widget on a server provided by Sigma, an extension development platform from Zoho.
Development Mode - This mode is mainly used for development purposes where the custom widget is hosted on your local machine on port 5000. If you host the custom widget in development mode, run your server locally to complete the setup.

Click Save.

The custom widget will be listed on the list view page.

Run the Server Locally

Before running the server locally, make sure that you have met the following pre-requisites:

Developer Mode is configured as the hosting location in your custom widget.

The server port 5000 is not occupied on your local machine.

Run the following command to start the HTTP server that runs your custom widget locally. This command makes use of the 5000 port of your local machine.

$ zet run

An illustration on running ZET installation on macOS terminal

To verify the successful running of the server, open the given URL in your browser: https://127.0.0.1:5000/

Changes you make in any file under the 'app' folder will reflect in the corresponding custom widget in AssetExplorer Cloud. After the changes are reviewed, you can pack the custom widget using the 'zet pack' command and upload the zip to AssetExplorer Cloud.

Related Articles
Custom Menu
Custom Menu allows you to create customized actions that can be performed on assets, CMDB, and custom modules. You can configure actions for a custom menu by using custom functions and custom widgets, or by invoking a URL. The configured menus can be ...
Report Widgets
You can convert tabular reports that contain charts into widgets that can be added to dashboards. To add report widgets to dashboards, you would first need to enable them from the reports module. Role Required: SDAdmin, SDReport, Technicians with ...
Developer Space
Developer Space contains various modules that can be customized and used across different features in the product. The modules currently available under Developer Space are: Custom Menu Custom Widgets Custom Functions Connections Global Variables ...
Custom Configurations
Custom Configurations, like web tabs, store additional information that cannot be grouped under the pre-defined modules. Unlike web tabs, custom configurations are accessible only via Setup. Why create Custom Configurations instead Web Tabs? The term ...
Custom Functions
Custom functions allow you to manipulate data within AssetExplorer Cloud and external applications. You can use custom functions to configure complex conditions or define multiple actions. For example, data under any module can be changed fully or ...

Custom Widgets

Custom Widgets

Create Widget Package

Install ZET CLI

Create Custom Widget Package

Include Resources

Custom Widget Specifications

Additional Configurations

Configuration Pop-Up

Display Widget Header

Display Custom Widget to Requester

Configure Probe

Configure Connections

Configure Variables

Configure Modules

Validate and Pack Widget

Add Custom Widget

Related Articles

Custom Menu

Report Widgets

Developer Space

Custom Configurations

Custom Functions