Create a widget in the Widgets Library in and then add the widget to a dashboard or report.
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.
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). NoteWhen creating a widget based on the results of an investigation task, only the following task types are supported for widget aggregation:
|
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. NoteBefore 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 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. |
In the Query step, set the following information:
Parameter | Description | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Widget display format | Select one of the widget format icons. You can see a preview of how the widget appears.
| ||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||
Query | Queries data in the Lucene query syntax form relating to the data source. For example when the data source is incidents and the query is: Or to see all incidents that are not closed, not archived, and are not jobs, use the query: | ||||||||||||||||||||||||||
Date range | The time frame to retrieve data. | ||||||||||||||||||||||||||
Widget name | Type a meaningful name for the widget. |
This step enables data manipulation, similar to scripting. You can configure the data according to groups and fields (including custom calculations on fields).
(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.
(Not relevant for Count) Select one of the fields from the dropdown or create your own custom calculations by selecting Custom calculations on fields.
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
.
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 21. Limit the number of resultsYou 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.
(Optional) Define custom groups (for example, define specific owners in the owner group).
Click Custom ‘Group by’.
In the Create Custom groups window, click Equals (String) to change the operator.
Select a value from the dropdown.
Change the name as required.
If you want to create a second group, click Add custom group.
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 22. Group data into two teamsYou 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.
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.
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.
To change the color, in the preview section, hover next to the legend, click the ellipsis and then click Edit color.
Click Save.
The widget is added to the widgets library.
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.