Create a Widget Using the Widget Builder - Administrator Guide - 8 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR Administrator Guide

Product
Cortex XSOAR
Version
8
Creation date
2024-09-18
Last date published
2024-10-31
Category
Administrator Guide
Solution
Cloud
Retire_Doc
Retiring
Link_to_new_Doc
/r/Cortex-XSOAR/8/Cortex-XSOAR-Cloud-Documentation
Abstract

Create a widget in the Widgets Library in and then add the widget to a dashboard or report.

Widgets are visual components that populate dashboards and reports with specific data. Although there are various out-of-the-box system widgets available, you can create custom widgets in the Widgets Library. You can also create them from an incident or an indicator.

  1. Create or edit a report or dashboard.

  2. In the Widgets Library click the +button.

  3. From the drop-down, select one of the data type widgets, such as Incidents.

    The relevant data is fetched into the data type. For example, when creating an incident type widget, the results are fetched. You can see a preview of the widget on the right hand side.

  4. From the Quick chart definitions window, in the Query tab, define the widget data.

    1. Add the following information:

      Parameter

      Description

      Widget type

      Select one of the widget types, by clicking on one of the graphics, such as pie chart, line chart, etc.

      Widget Name

      Type a meaningful name for the widget.

      Data source

      The type of data to query.

      • Incidents

      • Indicators

      • SOAR Metrics

      • War Room Entries

      • Tasks

      • Scripts

      • Threat Intel Reports

      When selecting Scripts, if your script does not appear you need to add it to the Scripts page and add the widget label.

      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: -status:closed and owner:"", it queries all incidents that are not closed, which does not have an owner.

      Script

      Select the script that you added when creating a custom widget using a script. Add the argument values, if required. See Create a Custom Widget Using an Automation Script.

      Date range

      The time frame to retrieve data.

    2. Select how you want to display the information, such as pie chart, timer widget, etc. You can see a preview of how the widget appears.

  5. Configure the data as required, by clicking the Operations tab.

    Not relevant for Script and Entries types.

    1. In the Values section, select one of the following values:

      • Count

      • Average

      • Sum

      • Min

      • Max

    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.

    4. In the 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 that the Make data available for search field is checked, when editing or creating a new field.

    5. (Optional) To define the groups (for example, you may want to define particular owners in the owner group) do the following:

      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.

    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.

  6. Define how the widget appears by clicking the Visuals tab.

    1. Add the following information:

      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.

  7. Click Save.

    The widget is added to the widgets library.

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