Widgets Library

FortiSOAR allows users to edit out-of-the-box (OOB) widgets and build new widgets for custom use cases. FortiSOAR provides many OOB widgets for graphs, charts, utilities, etc., however, there are always customizations and new use cases that are required to meet the user expectations. This feature provides more control to users and allows them to shape the widget based on their available data. For more information on the OOB widgets available in FortiSOAR, see the Dashboards, Templates, and Widgets chapter.

If you have upgraded your instance to FortiSOAR 6.4.1 or later from a version earlier than 6.4.1, then you will not be able to view widgets, due to missing permissions on the Widgets module. Administrators require to assign appropriate permissions to users according to the operations using the widgets.

From release 7.2.0 onwards, you can use the Widget Library or Content Hub to view, search, install, upgrade, and uninstall widgets that are part of the FortiSOAR OOB widget library.

In Release 7.2.0, the Widget Library navigation take you to the Content Hub with the relevant 'Widgets' filter selected for browsing ease.

Permissions required for using Widgets

Following are the permissions that you must be assigned to perform operations on widgets:

To work with widgets, i.e., view the widgets listed in the Content Hub and changes made to the Content Hub, you must be assigned a role that has a minimum of Read access on the Application, Widgets, and Content Hub modules, a minimum of Create, Read, Update permissions on the Solution Packs module.
To install a widget from the Content Hub or to or to upload a widget to the Content Hub you must be assigned a role that has a minimum of Read permission on the Security module.
Apart from the above, to work with widgets, you need appropriate permissions on the Widgets module, such as to install a widget or create a new custom widget, you must be assigned a role that has a minimum of Create, Read, Update permissions on the Widgets module, or to upgrade and configure a widget, you must be assigned a role that has a minimum of Update and Read access on the Widgets module, etc.

Once you create a new widget or edit an existing OOB widget, and you want to display that widget in dashboards, reports, view panel, listings, etc., you also require appropriate permissions to the FortiSOAR page in which you want to display the widget.

You must ensure that repo.fortisoar.fortinet.com is reachable from your FortiSOAR instance. Otherwise, you will see a blank page when you click Content Hub or Widget Library in the left navigation.
In release 7.2.0 update.cybersponse.com has been renamed to https://repo.fortisoar.fortinet.com/. Both these repositories will be available for a while to allow users who are on a release prior to FortiSOAR release 7.2.0 to access connectors and widgets. However, in time, only https://repo.fortisoar.fortinet.com/ will be available.

Viewing Widgets

To view widgets, on the FortiSOAR left navigation, click Content Hub or Widget Library. The Widget Library is filtered to display only widgets, whereas the Content Hub displays all the out-of-the-box reference material and product add-ons such as connectors, widgets, and solution packs. In this chapter the screenshots included are from the Content Hub page; similar screens are displayed in the Widget Library page. On the Content Hub page, from the Filter panel choose Widgets to view the list of all currently available widgets:

Maketplace - Widgets

You can search for a widget using the Search field and sort the widgets alphabetically (A-Z) or by date. Using the Filters panel, you can filter the widgets displayed in all the tabs based on varied criteria. Widgets that are installed appear with a tick on their card, for example, the Access Control widget in the above image. For more information on Content Hub, see the Content Hub chapter.

Working with Widgets

To install a widget, click Content Hub > Discover or Widget Library > Discover. Click on the card of the widget that you want to install to open that widget's popup, and then click Install. Once installed the widgets appear in the Manage tab.

On the Manage tab, you can view the content that is installed, in our example, you can view the installed widgets:
My Content Tab - Installed widgets

You can search for a widget by its name in the Search box and sort the widgets either alphabetically or by date. Similarly, you can filter the installed widgets that have an upgraded version, by selecting Update Available from the drop-down list. On the widget's card, you can also see if any widget that is installed on your system has an upgraded version. For example, if you have installed the Access Control v2.0.0 widget on your system and v2.1.0 is available, you will see an Update Available link, which you can click to open the widget's popup. On the widget's popup, you will see an Update to <version number> button, clicking which upgrades the widget to the newer version.

To upload a custom widget (.tgz) that you have already created, click Upload > Upload Widget. This opens the Upload Widget popup where you can drag-and-drop the .tgz file of the widget or browse to the .tgz file to add the widget in FortiSOAR. If you have an existing version of the widget on your system, then you can click the Replace existing version checkbox to replace this version of the connectors.

To view the details of a widget and to perform actions on the widget, click the card of the widget:
Installed Widgets

The Summary tab contains a brief description of the widget, its compatibility information, information on which FortiSOAR pages, such as dashboards, add forms, etc., on which the widget will be displayed, and an example of the widget usage along with a sample screenshot of the widget. The Contents tab contains the feature list for the widget. You can perform the following actions on the widgets popup:

Edit: To edit a widget to suit your requirements, click Edit, which if you are editing a local widget, opens the code editor interface, or asks you to change the version of the widget; or if you are editing a widget from a repository clones the repository widget and then opens the code editor interface. For details on editing widgets, see Editing an existing widget.
Preview: Some fields of the widget such as its title, the fields based on which the widget content is filtered or grouped, etc are editable based on the configuration of that widget. To such editable fields, click the Preview button.
Export: To export a widget in the .tgz format so that it can be used in another environment, click the Export button. Once the widget is saved as a .tgz file, you can import the same using the Upload > Upload Widget button.
Important: If the Data Import JSON file contains a version of the widget that is not available in the FortiSOAR repository, then the latest available version of that widget gets installed. For example, if you are trying to import the JSON file that contains userAssignments 1.0.0 widget that is not available in the FortiSOAR repository; but, version 1.1.0 is available, then version 1.1.0 of the userAssignments widget gets installed.
Note: If you export a widget from the 'Managed' tab, i.e., an installed widget, and you import that widget, then such widgets get directly installed, i.e., they appear in the Discover tab; however, if you export a widget that has not been published , i.e., from the 'Create' tab, then such widgets are added to the 'Create' tab.
Uninstall: To uninstall an installed widget click Uninstall which displays a Confirmation dialog. Click Confirm on the dialog to uninstall the widget.

You cannot uninstall system widgets such as the Mobile Settings widget or the Task Management widget.

You can add the installed widgets to FortiSOAR pages, such as reports, view panel, etc., based on the widget configuration specified.

Editing an existing widget

To edit a widget from the repository to suit your requirements, do the following:

On the FortiSOAR left-navigation, click Content Hub > Manage or Widget Library > Manage.
On the Manage tab, click the card of the widget that you want to edit to open the widget's popup, and then click Edit. When you click Edit, FortiSOAR displays a confirmation dialog box that lets you choose whether you want to edit this widget or add a new version for the widget:
1. When you click Edit the widget opens in the code editor interface and also gets saved in the Create tab:
  
  The directory structure for widgets is explained in the Directory structure and contents for widgets section.
2. When you click Add Version a Clone Widget dialog appears in which you can enter details such as the title and version of the widget that you want to edit, etc., and then click Create. The widget with the specified version gets saved in the Create tab.
Edit the existing widget as required.
Note: You cannot change the 'Title', 'API identifier', and 'Version' of a widget once it is set.
From version 7.0.2 onwards, you can click the Form View button to edit the info.json file in a Form view, instead of editing the file in the raw JSON format:

Once you have completed making the changes click Save Changes.
You can also perform the following operations on the code editor interface:
- Code Formatting: To lint your code automatically and make the code more human-readable and error-free (programming and programming errors), select the entire code in the editor and click the Format button.
- Full Screen: To get a better working view and make the editor go full-screen, click the Fullscreen button. To exit the full screen, press ESC.
- Export: To export the widget as a .tgz file, click the Export button. You might want to import the exported widget's .tgz file into another system.
- Preview: To preview the widget development progress, at any time during the development, so that it becomes easier to make changes, click the Preview button.
- Delete Widget or Uninstall Widget: To delete a widget that is not installed or uninstall a widget that is installed. Clicking Delete Widget or Uninstall Widget displays a Confirmation dialog, and you can click Confirm to delete or uninstall the widget.
Once you have completed making the changes, click Publish Widget.

Click Publish Only to publish the widget and make it available on the Discover tab for all the users of the system and enables usage of this widget on the pages as specified in the widget configuration. However, a working copy for the same is also maintained in the Create tab.
To delete all existing versions of the widget from your system, select the Delete all existing versions checkbox.
After you have published the widget, you will also see a Revert To Last Publish button on the code editor interface. Clicking Revert To Last Publish clears any changes made to the widget code since the last Publish event.

You can also view the widgets that are currently in development by clicking Content Hub > Create:
Workspace tab - Widgets
To edit a widget, click Edit on that widget's card, which opens the code editor interface. To add a new version for a widget click Add Version, which displays the Clone Widget dialog. To delete a widget, click the Delete icon.

Creating Widgets

Use the Widget Building Wizard to efficiently create new widgets.

To create a new widget, do the following:

On the FortiSOAR left-navigation, click Content Hub > Create or Widget Library > Create.
On the Create tab, click Create > New Widget, which displays the Create New Widget Wizard.

Prior to version 7.0.2, the code editor interface with the contents of the default "Hello World v1.0.0" widget would be displayed.
Click Let's start by defining a widget and to open the About Widget screen where you can provide the metadata of the widget such as the title, version, etc., and then click Create Widget.

Details that you can provide are:
1. In the Title field, enter the title of your widget.
2. In the API Identifier field, enter a name that would be used as a variable in the widget code to reference this widget. The variable that you use here can be alphanumeric; however, it should not contain any special characters and it must not start with a number.
  Also, note that the value that you enter in this field must not match the name of any other widget that is available in the Content Hub. For example, you cannot enter mobilesettingdev in this field, since the Mobile Settings widget is available in the Content Hub.
3. In the Subtitle field, enter the subtitle of your widget.
4. In the Version field, enter the version of the widget in the x.y.z format. For example, 1.0.0.
5. (Optional) In the Publisher field, enter the name of your organization as the publisher of this widget. The publisher of the widget is responsible for maintaining and supporting the widget.
  If you want to keep the widget anonymous, then you can add the "Community" keyword. If this field is left blank, again the widget's publisher is automatically set to "Community".
  Note: Do not enter "Fortinet" in this field.
6. (Optional) In the Description field, enter information for the widget that you are creating. The Description is displayed on the Widget card on the Widget Library listing pages and enables users to understand more about the Widget.
7. (Optional) From the Pages list, select the pages in FortiSOAR such as Dashboard, Listing, Add Form, etc., on which you want to display this widget.
8. (Optional) In the Compatibility field, enter the FortiSOAR version, in the x.y.z format, with which this widget is compatible.
9. Toggle Certified to Yes or No, depending on whether you want to publish the widget as certified or uncertified.
Once you click Create Widget, the widgets open in the code editor interface and you can edit the widget as per your requirements. For details of the directory structure of the code editor interface, see the Directory structure and contents for widgets. Details on editing widgets are present in the Editing an existing widget section.
Once you have completed editing the widget, click Save Changes.
Once you have completed making the changes, click Publish Widget.
Click Publish Only to publish the widget and make it available on the Discover tab for all the users of the system and enables usage of this widget on the pages as specified in the widget configuration. However, a working copy for the same is also maintained in the Create tab.

Directory structure and contents for widgets

widgetname folder
--+ editController.js
--+ edit.html
--+ images
---+ imagefiles
--+ info.json
--+ viewController.js
--+ view.html
--+ Widget Assets
---+ css
---+ html
---+ js

Controller and view files

The controller and view files are used to define and stylize the widget. The view.html and viewController.js define the output of the widget, i.e., how the widget will be displayed on the specified FortiSOAR pages. The edit.html and editController.js define the settings of the widget.

You can also include CDNs (Content Delivery Networks) in edit.html and view.html by using standard link syntax

Images

The images folder contains any image that is associated with the widget. For example, sample screenshots of how the widget will be displayed on FortiSOAR pages.

info.json

The info.json file contains information about the name, title, subtitle that represents a brief description of the widget and the version of the widget. In its metadata section, it contains a comma-separated list of FortiSOAR pages, such as dashboards, view panels, etc., in which you can add and display the widget. For example:

"pages": [
   "Dashboard",
   "View Panel"
  ]

It also contains the following information for the widget:

The certified parameter contains information on whether the widget has been certified by FortiSOAR.
The snapshots parameter contains the path of the screenshots that are part of the widget.
The description parameter contains the feature list of the widget.
The help_online parameter contains the link to the widget documentation added to the help_online parameter.
The compatibility parameter contains a comma-separated list of FortiSOAR versions with which the widget is compatible.

Widget Assets

Use the "Widget Assets" folder to create or import external assets that can be leveraged to build widgets, which enables you to create complex widgets and expands the capabilities of the "Widget Library." You can also create your own library and from version 7.0.2 onwards, you can create new files or folders in the root folder itself. To use an uploaded or created JS library, right-click the respective file, select the Copy Path item, and then include the path in the "src" of the script tag in edit.html or view.html according to your requirement.

The Widget Assets folder, by default, contains the css, html, and js subfolders. You can create or import files such as external JS files (external libraries), image files, etc. directly to any folder or sub-folder.

Actions that can be performed in the code editor interface

You can perform various actions such as creating or importing files or folders in the code editor.

Create File - Creates a file in the root (widgetname) folder or in the folder you have selected. For example, if you have selected the Widgets Assets folder then this action creates the file in the selected folder. All the actions work in a similar way.
Create Folder - Creates a folder in the root folder or in the folder you have selected.
Upload File - Imports a file to the root folder or in the folder you have selected.
Delete File or Folder - Deletes the selected file or folder. If you have selected a folder, and you click the Delete button, then this action will delete all files within the selected folder.
Important: The root folder and the info.json, view.html, edit.html, view.controller.js, and edit.controller.js files cannot be deleted.
Rename or Copy the Path of a File or folder - Right-click a file or folder to rename the file or folder or copy its path.

Code Editor interface

Once you have created or imported the required files you can use them in the widget. You can also edit the imported files in the code editor interface and can perform all the operations such as formatting the code, previewing the code, etc. as described in the Editing an existing widget section.

Using a widget in FortiSOAR pages

To use a FortiSOAR OOB widget or to use a custom widget that you have created, click the FortiSOAR page in which you want to add the widget. Then in the edit view of that page, add and configure the widget.

Let us take the example of the "User Tile" widget, which is used to view the logged-in user's assigned records across multiple modules along with the user's avatar. It also supports the filtering of records. If you want to add this widget to your dashboard, then do the following:

Click Dashboard and to edit an existing dashboard, click the Actions icon (), and then click Edit Dashboard.
Click Add Widget and from the Widget Library section, click User Tile.
Edit the configuration of the widget as per the settings defined in the widget configuration. Details on editing widgets are present in the Editing an existing widget section.
In the case of the "User Tile" widget, you need to provide the widget with a title, then choose the modules for whose records you want to view and you can also define filter criteria for filtering records of the selected module. For example, if you want to display Alerts and Incidents that are assigned to you, whose severity is set to "High" or "Critical", then you can edit the configuration of the User Tile widget as follows:
Click Save and Apply Changes.
The widget will appear in the dashboard as displayed in the following image:

Important: To view the custom widgets that are part of FortiSOAR pages such as Dashboards and Reports you must be assigned a role that has a minimum of Usage access on the Widgets module.