Widgets Overview
Overview of widgets, including methods for creating and
adding widgets. Use widgets to analyze and display data in a dashboard
or report in Cortex XSOAR
Widgets are visual components that enable
you to analyze data internally or externally from Cortex XSOAR,
in different formats such as graphs, pie charts, text from information,
etc.
Cortex XSOAR comes with a number of out-of-the-box
system widgets, such as
Today’s New Incidents
, Late
Incidents
, and Saved by Dbot,
etc. You can edit these widgets, when creating or editing a dashboard
or report. - Widgets Library: Create a widget using the widget builder in theWidgets Librarywhich is available for all users.
- From an Incident: Create the widget from the incident page and then add it to a dashboard or a report.
- From an Indicator: Create the widget from the indicators page then add it to a dashboard or a report.
You can also add a custom widget
in the War Room, so you can easily view the incident in a
widget format, such as severity in a bar chart.
If you have a significant number of widgets, performance
may be affected. You should try to keep widgets simple (no scripts)
and refresh times higher than 1 minute whenever possible.
The Widget Builder
In the Widgets Library, you create a widget through 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 which eliminates 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.
You can create the following types of widgets through the widget
builder:
- Incidents: Widgets relating to incidents, such as active incidents by type, incidents by phase, late incidents, etc.
- Indicators: Widgets relating to indicators, such as indicators by type, indicators activity, bad indicators, etc.
- Script: Automation driven widget. Although you can create complex widgets using the widget builder, you can also create dynamic widgets using automation scripts, such as calculating the percentage of incidents that DBot closed. The automation script can also pull information from the Cortex XSOAR API.Before creating a script based widget, you need to create a script in the Automation page and then select the script in the widget builder. The script must have thewidgettag assigned, otherwise it does not appear when selecting the script in the widget builder.In the Widget builder, although you cannot manipulate the data (no data appears in the operations tab) you can define the arguments for the script and change the color, layout, legends, etc.For automation script examples, see Create a Custom Widget Using an Automation Script.
- War Room Entries: Widgets relating to the number of War Room entries, including number of entries according to owner, etc.
- SOAR Metrics: Widgets relating to automations, playbooks, integrations, such as troubleshooting, how long it runs, number of runs for API, errors, etc.
- Upload: You can upload a JSON file to create a static widget, which displays relatively straightforward information, such as grouping incidents severity by type, active incidents by type, and so on.
Widget Creation
You can create the following types of widgets:
Widget | 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. |
When you Create a Widget using the Widget Builder you add the information
according to the following tabs (you do not need to complete every
tab, apart from Query):
- Query: Queries a specific data type, defines the data query and the time frame to return. For example, to see all incidents that are not closed, not archived, and are not jobs, type the following information:-status:closed and -status:archived and -category:job
- Operations: The Operations tab enables you to do complex data manipulation, similar to scripting. You can configure the data according to groups and fields (including custom calculations on fields), create filters, transformers, etc. You can select how to calculate the data according to the following options:ParameterDescriptionCountCounts the total value of the field. For example, to see the total number of incidents in your system. You can then group by type, severity, etc.AverageCounts the total value of the field. For example, to see the total number of incidents in your system. You can then group by type, severity, etc.SumCounts 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.MinCalculates the minimum numeric value of the data. For example, you may want to see the minimum number of fetched events.MaxCalculates the maximum numeric value of the data. For example, you may want to see the maximum number of fetched events.When you select one of the widget data types, such as an incident type widget, relevant data for that widget is retrieved. For example, when selecting the incident type, in theGroup byfield all relevant data relating to incidents is retrieved, such as type, owner, created by, etc.When selecting one of the options (apart fromCount) you can choose one of the relevant fields from the dropdown list. If you want to create advanced calculations on fields, selectCustom Calculations on fields.Custom calculations on fieldsCustom calculations on fields enable you to create more complex calculations on incident fields or between incident fields. When you select Custom Calculations on fields and start typing, the custom calculation modal suggests fields, based on the selected widget data type. For example, if you select an incident type widget, the custom calculation modal suggests incident fields to add. If you select an indicator type widget, the custom calculation modal suggests indicator fields to add. These fields are automatically validated.
Instead of using the modal suggestions, you can add your own custom fields (provided they exist) according to the widget data type, by adding 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 the following:{now}-remediationsla.dueDateTo 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 the following:remidationsla.startDate-detectionsla.startDateTo see remediations (less 10 minutes), typeremdiationsla.dueDate-10.GroupingYou can further manipulate the 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, you have 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.
Limiting 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.
- Visuals: You can change how the widget appears, by adding names for vertical and horizontal axis, define the format, show the legend, reference line, etc.
