Create custom XQL widgets

You can create custom XQL widgets based on a Cortex Query Language (XQL) query, and add parameters that you can configure as fixed filters or dashboard drilldowns.

Notice

Custom XQL widgets are supported in Cortex XDR Pro and Cortex XSIAM only.

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.

   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 (), 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.

      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.

      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.

1. (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 <number> 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

   • Whenever the time period is changed in the query window, the config timeframe is automatically set to the time period defined, but this won't be visible as part of the query. Only if you manually type in the config timeframe will this be seen in the query.
   • These time picker options are available in XQL queries when using the Query Builder, XQL Widgets, and when defining XQL Widgets in Reports and Dashboards.
2. Save the widget.

   The custom widget appears in the list of existing widgets.