> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/widgets-overview.md). # Widgets Overview 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, 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](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/saved-by-dbot-roi-widget.md), etc. You can edit these widgets, when creating or editing a dashboard or report. {% hint style="info" %} ### Note In Cortex XSOAR v6.8 and later, some content packs include a widget that tracks API rate limit errors. You can use this information for troubleshooting and to make decisions about indicator enrichment. From the Widgets Library, click **+** and choose **SOAR Metrics** from the dropdown. From the **Operations** tab, in the **Sum** field, select **Total API Calls**. In the **Group by** dropdown, select **API Response Type**. Note that this widget only displays data if there is an installed content pack that supports API rate limit information. {% endhint %} You can create widgets from the following and then add them to a [dashboard](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/dashboards/add-a-widget-to-a-dashboard.md) or [report](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/reports/add-a-widget-to-a-report.md), as required: * [Widgets Library](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/create-a-widget-using-the-widget-builder.md): Create a widget using the widget builder in the **Widgets Library** which is available for all users. * [From an Incident](/xsoar-6-administrator-guide/6.14/investigate-and-respond-to-threats/day-to-day-tasks-in-cortex-xsoar/incident-management/create-a-widget-from-an-incident.md): Create the widget from the Incidents page and then add it to a dashboard or a report. * [From an Indicator](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/create-a-custom-widget-using-an-automation-script.md#UUID-2be14e62-fa24-1ed6-0d35-64eb380f5496): Create the widget from the Threat Intel (Indicators) page then add it to a dashboard or a report. You can also [add a custom widget in the War Room](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/incidents/war-room-overview.md#UUID-916b4482-b393-2437-d88d-0db8733e6403), so you can easily view the incident in a widget format, such as severity in a bar chart. {% hint style="info" %} ### Note 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 one minute whenever possible. {% endhint %} **The Widget Builder** In the Widgets Library, you [create a widget](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/create-a-widget-using-the-widget-builder.md) 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.

Note

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 the widget tag 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](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/create-a-custom-widget-using-an-automation-script.md). * **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. * **Threat Intel Reports**: Widgets relating to threat intel reports that have been created, such as reports by type, status, 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 | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ![widget-timer.png](/files/ixHHb8PVJX7RqGtAPq3H) | View data in a timer format. For example, mean time to assignment. In the **Visuals** tab, you can select the threshold color. | | ![widget\_number.png](/files/H2gz77wzbBXeTQE7AuFC) | View data in a number format. In the **Visuals** tab, you can select the threshold color. | | ![widget\_bar.png](/files/ZWjaxQO9ZXnQH63G8Lxa) | View data in a bar format. | | ![widget\_barchart.png](/files/GzLVDjz4J2M5jExMiOqo) | View data in a column format. | | ![widget\_pie.png](/files/fzbXA7UIhosm8IwoUol6) | View data in a pie format. | | ![widget\_graph.png](/files/oBW2sRDwDitrExyzMotB) | View data in a line graph format. | | ![widget\_table.png](/files/sCzoohq1c0qoOeCbKJOa) | View data in a table format. Click the gear icon to edit columns. | | ![widget\_text.png](/files/fxwKPxkhzbngj0o2Zdwj) | 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](/xsoar-6-administrator-guide/6.14/learn-about-cortex-xsoar/get-started-in-cortex-xsoar/how-to-use-markdown.md) is supported. | When you [Create a Widget using the Widget Builder](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/create-a-widget-using-the-widget-builder.md), 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: | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Count | Counts 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. | | Average | Calculates the average value of the field. For example, to see the average number of incidents in your system over the selected time frame. You can then group by type, severity, etc. | | 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. | 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 the **Group by** field all relevant data relating to incidents is retrieved, such as type, owner, created by, etc. When selecting one of the options (apart from **Count**) you can choose one of the relevant fields from the dropdown list. If you want to create advanced calculations on fields, select **Custom Calculations on fields**. **Custom calculations on fields** Custom 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. ![widget-customcal.png](/files/UwryrEi2Wvpj0yHEa0HW)

Note

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.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 the following: **`remidationsla.startDate-detectionsla.startDate`** To see remediations (less 10 minutes), type **`remdiationsla.dueDate-10`**. **Grouping** You 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. ![widget-group.png](/files/o46pggy317v93fZQ3016) **Limiting 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 by month. ![widget-pop.png](/files/Zegknt1yUYHLnO9qWogm) * **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. ![widget-visual2.png](/files/zdSeY7kCUgHiTHXRkmp3) **Change Color of Items in Widgets**: You can change the color of items (such as indicator types, incident types, etc.) in some widgets, depending on the widget type and the chart/graph type. When editing a widget, click on the item within the legend in the preview window on the right. The **Edit color** option appears and you can select the color for the item. If you edit the color after a widget has been added to a dashboard or report, the change only applies to the widget within that dashboard or report. If you edit the widget directly in the **Widgets Library** before adding it to a dashboard or report, the change is applied every time you add the widget to a dashboard or report. Changes to an item within a widget only apply within that widget. For example, changing the color for the **`Phishing`** incident type within the **Active Incidents** widget only applies to **Active Incidents**, and not other widgets that contain incident types. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/widgets-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.