Widget Library

FortiSOAR contains a "Widget Library" that 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.

The feature is introduced as a "BETA" feature with more enhancements being planned to be added in the subsequent releases to make the Widget Library more robust and comprehensive.

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 the Widget Library, due to missing permissions on the Widgets module. Administrators require to assign appropriate permissions to users according to the operations using the Widget Library.

Widget Store

Use the Widget Store to easily view, search, and install, upgrade, and uninstall widgets that are part of the FortiSOAR OOB widget library.

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

To install a widget, you must be assigned a role that has a minimum of Create, Update, and Read access on the Widgets module.
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.
To uninstall a widget, you must be assigned a role that has a minimum of Read and Delete access on the Widgets module.
To view the widgets listings in the Widget Store and to use the widgets as part of FortiSOAR pages you must be assigned a role that has a minimum of Read access on the Widgets module.

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.

To access the Widget library, you must ensure that update.cybersponse.com is reachable from your FortiSOAR instance.

To open to the widget store, on the FortiSOAR left navigation, click Widget Library. On the Widget Library page, click the Widget Store tab. The Widget Store page appears as shown in the following image:

Widget Store page

You can search for a widget using the Search Widgets field.

Each widget that is part of the Widget Store has a brief description of the widget, the feature list for the widget. It contains 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.

To install a widget, click Install Widget. Once you install a widget you can add a widget to FortiSOAR pages, such as reports, view panel, etc., based on the widget configuration specified.

Widget Library - Installed tab

To edit a widget to suit your requirements, click Edit Widget, which opens the code editor interface. For details on editing widgets, see Editing an existing widget.

To clone a widget, for example in cases where you want to enhance an existing widget without impacting the original one, click the Clone button. Then in the Clone Widget dialog enter the title for the cloned widget and click Save. This opens the widget in the code editor interface, where you can choose to make changes to the cloned widget or close the widget. The cloned widget gets saved in the Draft State.

To create a new custom widget, click Create Widget, which opens a code editor interface. For details on creating widgets, see Creating Widgets.

To upload a custom widget (.tgz) that you have already created, click 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.

To uninstall an installed widget click Uninstall Widget or to delete a widget (which is uninstalled), click Delete Widget. Clicking either of the buttons displays a Confirmation dialog, on which you click Confirm to uninstall or delete the widget. FortiSOAR displays the Success message and the installed widget number decreases by 1.

Editing an existing widget

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

On the FortiSOAR left-navigation, click Widget Library.
On the Installed tab, click the widget you want to edit, and the click Edit Widget.
This displays the code editor interface for the selected widget. The code editor interface contains the following folders: Widget Meta, Widget Files, and Widget Assets. For the description of the contents of these folders and files, see the Directory structure and contents for widgets.

You can also perform the following operations:
- To export the widget as a .tgz file, 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 Widget button.
- To preview the changes made to the widget before you publish the widget, and to the view how the widget will appear on the pages specified, click the Preview button. Based on the configurations specified in the widget, you require to add the inputs such as title of the widget, the module on whose records data the widget is configured, etc, and then click Save.
Edit the existing widget as required, and click Save Changes.
The widget gets saved in the Draft state.
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.
Once you have completed making the changes, click Publish Widget.
This will publish the widget and enable you to use this widget on the pages as specified in the widget configuration.
Clicking Revert To Last Saved clears any changes made to the widget code since the last Save event.

Creating Widgets

To create a custom widget, do the following:

On the FortiSOAR left-navigation, click Widget Library.
Click Create Widget.
This displays the code editor interface with the contents of the default "Hello World v1.0.0" widget.
The code editor interface contains the following folders: Widget Meta, Widget Files, and Widget Assets. For the description of the contents of these folders and files, see the Directory structure and contents for widgets.
Edit the custom widget as required; details on editing widgets are present in the Editing an existing widget section. Once you have completing editing the widget, click Save Changes.
The widget gets saved in the Draft state.
Once you have completed making the changes, click Publish Widget.
This will publish the widget and enable you to use this widget on the pages as specified in the widget configuration.

Directory structure and contents for widgets

widgetname folder
--+ Widget Meta
---+ info.json
--+ Widget Files
---+ html
----+ view.html
----+ edit.html
---+ js
----+ viewController.js
----+ editController.js
--+ Widget Assets

Widget Meta

The Widget Meta folder contains the info.json file. 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 panel, etc., in which you can add and display the widget. For example:

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

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

Widget Files

The Widget Files folder contains two subfolders, the html folder containing view.html and edit.html files and the js folder containing viewController.js and editController.js files These files are used to define and stylize the widget.

The view.html and viewController.js defines the output of the widget, i.e., how the widget will be displayed on the specified FortiSOAR pages. The edit.html and editController.js defines the settings of the widget.

Widget Assets

Use the "Widget Assets" folder to create or import external assets that can be used in widgets, which enables you to create complex widgets and expands the capabilities of the "Widget Library." The Widget Assets folder can contain subfolders or files. You can create or import files such as, external JS files (external libraries), image files, etc. directly in the Widget Assets folder or in their respective subfolders under the Widget Assets folder.

You can perform various actions such as creating or importing files or folders in the Widgets Assets folder. Action buttons are present only at the “Widget Assets” level and you perform the following actions at the "Widgets Assets" level:

Create File - Creates a file in the Widgets Assets folder or in the selected folder, i.e., this action creates a file in the Widgets Assets folder, or if you have selected a folder in Widgets Assets, then this action creates the file in the selected folder. All the actions work in the similar way.
Create Folder - Creates a folder in the Widgets Assets folder or in the selected folder.
Import File - Imports a file to the Widgets Assets folder or in the selected folder.
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.

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 Widget Assets – Use the widget assets to upload or create external JS libraries that can be leveraged to build widgets. You can also create your own library. To use an uploaded or created JS library, select the respective file and click copy_ path icon and then include the path in the "src" of the script tag in edit.html or view.html according to your requirement.

Widget Assets - copy_path icon

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

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