> 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/cortex-xsoar-8-on-prem/8.9/configure-cortex-xsoar/dashboards-and-reports/widgets/create-a-widget-using-the-widget-builder.md).
# Create a widget using the 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
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 following 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.
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. |
**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 do not have an owner.
Or to see all incidents that are not closed, not archived, and are not jobs, use the query: **`-status:closed and -status:archived and -category:job`**.
**Date range**
The time frame to retrieve data.
**Widget name**
Type a meaningful name for the widget.
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 26. 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.
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 27. 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.
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**
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:
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.
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`**.
---
# 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/cortex-xsoar-8-on-prem/8.9/configure-cortex-xsoar/dashboards-and-reports/widgets/create-a-widget-using-the-widget-builder.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.