> 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-xdr-3.x/cortex-xdr-3.x-documentation/investigate-and-respond-to-incidents/dashboards/custom-dashboards/create-custom-xql-widgets.md). # Create custom XQL widgets {% hint style="info" %} ### Notice Custom XQL widgets are supported in Cortex XDR Pro and Cortex XSIAM only. {% endhint %} With custom XQL widgets you can personalize the information that you display on your custom dashboards and reports. You can build widgets that query specific information that is unique to your workflow, and define the graphical format you require (such as table, line graph, or pie chart). All of your predefined and custom XQL widgets are available in the **Widget Library** under Dashboards & Reports → Customize → **Widget Library**. From the **Widget Library**, you can browse all widgets by category, create new XQL widgets, and edit and delete existing XQL widgets. How to create a custom XQL widget 1. In the **Widget Library**, select **Create custom XQL widget**. 2. Enter a widget name and an optional description. 3. Define an XQL query that searches for the data you require. Select **XQL Helper** to view XQL search and schema examples. For more information, see [How to build XQL queries](/cortex-xdr-3.x/cortex-xdr-3.x-documentation/investigate-and-respond-to-incidents/build-xql-queries/how-to-build-xql-queries.md).

Tip

You can create a generic dashboard for multiple views of the same dataset by defining the dataset in the XQL widget as dataset = <dataset_name>*. The placement of the asterisk (*) in the dataset name ensures that any view containing this prefix text is displayed in the results.

Example:

The dataset in a query is defined as:

dataset = amazon_aws_raw*

If there are multiple datasets that begin with amazon_aws_raw in their name, such as amazon_aws_raw_eu_view and amazon_aws_raw_us1_view, these views will be included.

4. Select **Preview** to review the search results.

Note

Cortex Query Language (XQL) queries generated from the Widget Library do not appear in the Query Center. The results are used only for creating the custom widget.

5. Under **Widget**+Graph → **Chart Editor (**![visualizing-query-results-chart-editor.png](/files/eWXNl8VsxItqXs803QGf)**)**, manually build and view the graph using the selected graph parameters: * **Main** * **Graph Type**: Type of graphs and output options available: **Area**, **Bubble**, **Column**, **Funnel**, **Gauge**, **Line**, **Map**, **Pie**, **Scatter**, **Single Value**, or **Word Cloud**.

Note

To display the result of as a time duration, choose the graph type Single Value and enable Show as Time. You can then select the Time Unit (millisecond, second, minute, or hour) and the Display format.

* **Subtype** and **Layout**: Depending on the selected type of graph, choose from the available display options. * **Header**: Title your graph. * **Show Callouts**: Display numeric values on graph. * **Data** * **X-axis**: Select a field with a string value. * **Y-axis**: Select a field with a numeric value. * (Optional) **Series**: For an area, bubble, column, line, map, or scatter chart, you can specify a field (column) to group chart results based on y-axis values. This option is only displayed when one of the supported graph types are selected, and a single y-axis value is selected. * Depending on the selected type of graph, customize the **Color**, **Font**, and **Legend**. 6. *(Optional)* Add parameters to the query. You can use parameters to filter widget data on a dashboard or report, and create drilldowns on dashboards. Base your filters on fields and values in the query results.
Take the following steps 1. In the search results, identify a field by which you want to filter. 2. Using the `filter` stage, define parameters prefixed with `$`. To specify parameters with a single predefined value, use the `=` operator. To specify parameters with multiple values (predefined or dynamic), use the `IN` operator. 1. Example of a single value parameter: The following query defines the `$domain` parameter for filtering dashboard data by domain, based on the `domain` field in the `agent_auditing` dataset. Single value parameters are based on static predefined values. In this example, the dashboard user will be able to select a domain from a list of predefined domains. ```programlisting dataset = agent_auditing | filter domain = $domain ``` 2. Example of a multiple value parameter: The following query defines the `$endpointname` parameter for filtering dashboard data by one or more endpoint names, based on the `endpoint_name` field in the `agent_auditing` dataset. You can configure this parameter with static predefined values, or dynamic values that are pulled from an XQL query. ```programlisting dataset = agent_auditing | filter endpoint_name IN ($endpointname) ``` 3. (Optional) Under **Assign Parameters (default values)**, define default values for the parameters. When you add the widget to a dashboard or report, the data will be automatically populated. Alternatively, you can configure all input values when you set up a dashboard or report.
7. *(Optional)* Change the default time period against which to run your query from the time picker at the top right of the window. You can select the required **Timeframe** from any of the following options available: * Preset time ranges easily available to select from, such as **24 hours** and **30 days**. * Recently used selections from your previous queries. * **Relative time**: Define the time frame as the last \ minutes, days, or hours by setting the number. * **Calendar**: Create a customized time period by selecting the date range from the calendar and the specific **Start Time** and **End Time**.

Note

8. Save the widget. The custom widget appears in the list of existing widgets. --- # 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-xdr-3.x/cortex-xdr-3.x-documentation/investigate-and-respond-to-incidents/dashboards/custom-dashboards/create-custom-xql-widgets.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.