Create a widget using the widget builder

Create widgets with the Cortex XSOAR 8 SaaS widget builder.

In the Widgets Library, you create a widget using the widget builder, which enables you to define and configure data, and preview how that widget appears. The widget builder allows you to create complex widgets, eliminating the need to write scripts or upload JSON files (although you have the option to do this). These complex widgets have the same capabilities as if you were creating a script-based widget.

Task 1. Create a new widget

In the Widgets Library of the report or dashboard you are creating or editing, click and select the widget type as follows.

Widget type	Description
Incidents	Use incident data to create widgets related to incidents, for example timestamps, duration, incident types, and any incident field.
Indicators	Use indicator data to create widgets related to indicators, for example timestamps, indicator types, and any indicator field.
SOAR Metrics	Use SOAR metrics data to create widgets related to scripts, playbooks, and integrations, for example executions, durations, and errors.
Tasks	Use tasks data to create widgets related to investigation tasks, for example assignee, playbook name, and duration (manual or automated). Note When creating a widget based on the results of an investigation task, only the following task types are supported for widget aggregation: Manual tasks Tasks that have an assignee Tasks that have a due date Tasks that are in an error state Oversized tasks
Scripts	Use a script to create a widget. Although you can create complex widgets using the widget builder, you can also create dynamic widgets using scripts, such as calculating the percentage of incidents that DBot closed. The script can also pull information from the Cortex XSOAR API. Note Before creating a script based widget, you need to create a script in the Scripts page and then select the script in the widget builder. The script must have the widget tag assigned, otherwise it does not appear when selecting the script in the widget builder. In the widget builder, you cannot manipulate data (no data appears in the Operations tab). However, you can define script arguments and change the color, layout, and legends. For more information, see Create a custom widget using a script.
Threat Intel Reports	Use threat intel data to create widgets related to threat intel reports that have been created, for example reports by type and status.
Upload	Upload a JSON file to create a static widget which displays basic information, such as grouping incidents severity by type and active incidents by type.

Task 2. Define the widget data

In the Query step, set the required information.

Widget display format

Select one of the widget format icons. You can see a preview of how the widget appears.

Widget format	Description
	View data in a timer format. For example, mean time to assignment. In the Visuals tab, you can select the threshold color.
	View data in a number format. In the Visuals tab, you can select the threshold color.
	View data in a bar format.
	View data in a column format.
	View data in a pie format.
	View data in a line graph format.
	View data in a table format. Click the gear icon to edit columns.
	View data in a text format, which can be used as a text summary of the displayed data. You can use {0} to display a query value and {date} to display the date. Markdown is supported.

Data Source

Select the source data to query.

Cortex XSOAR retrieves data relevant for that data source. For example, for Incidents, in the Group by field, all data relating to incidents is retrieved, such as type, owner, and created by.

Widget data source	Description
Incidents	Use incident data to create widgets related to incidents, for example timestamps, duration, incident types, and any incident field.
Indicators	Use indicator data to create widgets related to indicators, for example timestamps, indicator types, and any indicator field.
SOAR Metrics	Use SOAR metrics data to create widgets related to scripts, playbooks, and integrations, for example executions, durations, and errors.
War Room Entries	Use War Room entry data to create widgets, for example number of entries according to owner.
Tasks	Use tasks data to create widgets related to investigation tasks, for example assignee, playbook name, and duration (manual or automated). When creating a widget based on the results of an investigation task, only the following task types are supported for widget aggregation: Manual tasks Tasks that have an assignee Tasks that have a due date Tasks that are in an error state Oversized tasks
Scripts	Use a script to create a widget. Although you can create complex widgets using the widget builder, you can also create dynamic widgets using scripts, such as calculating the percentage of incidents that DBot closed. The script can also pull information from the Cortex XSOAR API. Note Before creating a script based widget, you need to create a script in the Scripts page and then select the script in the widget builder. The script must have the widget tag assigned, otherwise it does not appear when selecting the script in the widget builder. In the widget builder, you cannot manipulate data (no data appears in the Operations tab). However, you can define script arguments and change the color, layout, and legends.
Threat Intel Reports	Use threat intel data to create widgets related to threat intel reports that have been created, for example reports by type and status.
Upload	Upload a JSON file to create a static widget which displays basic information, such as grouping incidents severity by type and active incidents by type.

Task 3. Configure the widget data

This step enables data manipulation, similar to scripting. You can configure the data according to groups and fields (including custom calculations on fields).

1. (Not relevant for tables or text) Click the Operations step, and in the Values section select one of the following calculations to perform on the data (not relevant for Script and War Room Entries data sources).

   Calculation	Description
   Count	Counts the total value of the field. For example, display the total number of incidents in your system. You can then group by type and severity.
   Average	Calculates the average value of the field. For example, display the average number of incidents in your system over the selected time frame. You can then group by type and severity.
   Sum	Counts the value of the field according to a specific value. For example, when you define a metrics widget type, select the execution count, total duration, errors count, or create your own custom calculations.
   Min	Calculates the minimum numeric value of the data. For example, you may want to see the minimum number of fetched events.
   Max	Calculates the maximum numeric value of the data. For example, you may want to see the maximum number of fetched events.

2. (Not relevant for Count) Select one of the fields from the dropdown or create your own custom calculations by selecting Custom calculations on fields.
3. If adding custom calculations, type the calculation as required.

   The custom calculation modal suggests incident fields based on the widget data type, which are automatically validated. You can add your own fields (provided these fields exist), according to the widget data type, by using the CLI name. These fields are not validated.

   You can add mathematical operators (such as +, -, /, *) between fields. Variables using {} are also supported. For example:

   • To see the average time that incidents are late, type {now}-remediationsla.dueDate.
   • To calculate the average time between detection and remediation for phishing incidents (in the phishing generic playbook we set the time detection and remediation SLA timers), type remidationsla.startDate-detectionsla.startDate.
   • To see remediations (less 10 minutes), type remdiationsla.dueDate-10.
4. In the Axis and grouping section Group by field, from the dropdown, select the group you want to add.

   By default, the results are limited to the top 10 most popular results. If you want to change the top most popular to the least popular, change the number, or you want to see the remaining results that are not covered in one group (the Show ‘Others’ checkbox), click the edit button and update as required.

   If you want to add a custom field, ensure the Make data available for search incident type field is checked when editing or creating a new field.

   Example 24. Limit the number of results

   You can limit the amount of results to return, view the most or least popular, and for some fields select the time format. For example, you may want to see the top 10 most popular active incidents active incidents by month.

   

   widget-pop.png
5. (Optional) Define custom groups (for example, define specific owners in the owner group).

   1. Click Custom ‘Group by’.
   2. In the Create Custom groups window, click Equals (String) to change the operator.
   3. Select a value from the dropdown.
   4. Change the name as required.
   5. If you want to create a second group, click Add custom group.
   6. If you want to add a group for all other values that have not been defined, click the Create and display a group for all remaining values checkbox.

   Example 25. Group data into two teams

   You can manipulate data according to one or two groups (two groups are useful for vertical bars and line charts). Within each group, you can group by a bucket. For example, for two teams - Team A and Team B, each one is made up with different team members. You only want to see Team A and Team B and not the individual team members.

   

   widget-group.png
6. In the Second group by field, add the group as required. For example, to see data filtered by owner and severity, select Group By Owner and Second Group by Severity.

Task 4. Define the widget display

1. Click the Visuals step and define how the widget appears.

   Parameter	Description
   Axis name	The name of the axis for both horizontal and vertical.
   Format	Select the format of the table for both horizontal and vertical axis. For example, hours, minutes, days, weeks, etc.
   Reference Line	Whether you want a line showing the average, minimum, maximum, or custom line.
   Show Legend	Whether you want to see the legend in your widget.
   Show also percentage	Displays the percentage when selecting a pie chart.
   Show values on the graph	Add the values on the chart widget.
   Display trend	Compares dates for a particular period in a number widget. For example, this week vs. last week, this year vs. last year, and so on. To change the comparison period, in the Time frame field from the dropdown, select the relevant date.
   Widget color threshold	Select the Widget color threshold in a number or duration widget to highlight the threshold data and define the threshold by selecting the Widget color threshold checkbox. For example, if less than 150 red, 100 yellow, 50 green. To add more thresholds, click Add new threshold. You can change the colors as required.

2. To change the color, in the preview section, hover next to the legend, click the ellipsis and then click Edit color.

Task 5. Save and add the widget to a dashboard or report

1. Click Save.

   The widget is added to the widgets library.
2. Add the widget to the dashboard or report.

   When you add the widget, it automatically uses the date range of the dashboard or report. You can change it by clicking the settings icon and selecting Use widget’s date range. To revert, click the settings icon again and select Use dashboard’s date range.

Create a widget using the widget builder examples

Average time to close incidents

In this example, we want to create a bar chart widget that shows the following:

• The average time it takes to close incidents per day
• Classified according to incident types
• Incidents that occurred during the previous seven days

1. Click the add + button from the Widgets Library.
2. Select Incidents.
3. Enter a name in the Widget name field.
4. Click the Bar graph icon.
5. In the Query tab, define the following:

   Data source: Incidents

   Query: -category:job and -status:Closed

   Date range: Last 7 days
6. In the Operations tab:

   Change Count to Average.

   From the dropdown list, select Custom calculations on fields.

   Type remediationsla.startDate-detectionsla.startDate

   Group by: Date Occurred

   Second Group by: Type

   

   widget-example.png

How many incidents over the last seven days

In this example, we want to view the following data:

• How many incidents occurred in the last 7 days
• Closed vs not closed (pending or active)
• Line chart

1. Click the add + button from the Widgets Library.
2. Select Incidents.
3. Enter a name in the Widget name field.
4. Click the Line graph icon.
5. In the Query tab, define the following:

   Data source: Incidents

   Query: -category:job

   Date range: Last 30 days
6. In the Operations tab, the first group is Date Occurred.
7. In the second group, from the dropdown list, select status.
8. Click Custom Group by to add the following data:

   

   widget-eg.png

Average time for open incidents that are late

In this example, we want to create the following incident type widget:

• The average time for open incidents that are late
• Grouped by 2 groups (group A and group B) and by type
• In a bar chart

1. Click the add + button from the Widgets Library.
2. Select Incidents.
3. Enter a name in the Widget name field.
4. Click the Bar graph icon.
5. In the Query tab, define the following:

   Data source: Incidents

   Query: -status:Closed and category:job

   Date range: Last 30 days
6. In the Operations tab, add the following information:

   1. In the Values section, select Average.
   2. From the dropdown list, click Custom calculations on fields.
   3. Type {now}-remediationsla.dueDate.

      We want to see the average time that incidents are late (from today’s date). We add a variable {now}, so that we do not have to change the date.
   4. In the Group by field, select Owner and then click Custom Group by.
   5. Add the following, using users from your organization.

      

      widget-group.png
   6. In the Second group by field, from the dropdown list, select Type.
   7. Select the checkbox for Create and display a group for all remaining values and then click Save.
7. In the Visuals tab, select the following:

   1. Horizontal options - Axis name: TEAM.
   2. Vertical options - Axis name: REMEDIATION TIME.