> 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.12/configure-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/create-a-widget-using-the-widget-builder.md).
# Create a Widget using the Widget Builder
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](/xsoar-6-administrator-guide/6.12/investigate-and-respond-to-threats/day-to-day-tasks-in-cortex-xsoar/incident-management/create-a-widget-from-an-incident.md) or an [indicator](/xsoar-6-administrator-guide/6.12/configure-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/create-a-custom-widget-using-an-automation-script.md).
1. Create or edit a [report](/xsoar-6-administrator-guide/6.12/configure-cortex-xsoar/customize-and-configure-cortex-xsoar/reports.md) or [dashboard](/xsoar-6-administrator-guide/6.12/configure-cortex-xsoar/customize-and-configure-cortex-xsoar/dashboards.md).
2. In the **Widgets Library** click the **+** button.
3. From the dropdown list, 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 Automation 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 you [created a custom widget using an automation script](/xsoar-6-administrator-guide/6.12/configure-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/create-a-custom-widget-using-an-automation-script.md). Add the argument values, if required. |
| 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 list 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 list, 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](/xsoar-6-administrator-guide/6.12/configure-cortex-xsoar/customize-and-configure-cortex-xsoar/incidents/incident-customization/incident-fields.md) 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):
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 list.
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 list, 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
**Create a Widget Using the Widget Builder Examples**
**Average Time to Close Incidents per Day**
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. In the **Widgets Library** click the add button.
2. Select **Incident data**.
3. In the **Query** tab, define the following:
* Data Type: **Incidents**
* Data query: **`-category:job and -status:Closed.`**
* Time frame: **Last 7 days**
* Type: **`Bar chart`**
4. In the **Operations** tab:
* Change **Count** to **Average**.
* From the dropdown list, select **Custom calculations on fields**.
* Type **`remediationsla.startDate-detectionsla.startDate`**
* Group by: **Data Occurred**
* Second Group by: **Type**
**How Many Incidents Occurred in the Last 7 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. In the **Quick Chart definitions** window, use the following data:
2. In the **Operations** tab, the first group is **`Date Occurred`**.
3. In the second group, from the dropdown list, select **`status`**.
4. 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 two groups (group A and group B) and by type.
* In a Bar Chart
1. In the **Query** tab, type:
2. 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 information:
6. Select the **Create and display a group for all remaining values** checkbox.
We have additional users that are not in the groups that we want to see.
7. In the second group by field, from the dropdown list, select **Type**.
3. 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/xsoar-6-administrator-guide/6.12/configure-cortex-xsoar/customize-and-configure-cortex-xsoar/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.