JSON File Widget Parameters - Administrator Guide - 8 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR Administrator Guide

Cortex XSOAR
Creation date
Last date published
Administrator Guide

JSON file parameters to use when creating a custom widget for reports or dashboards in Cortex XSOAR.

The following table describes the parameters for a JSON file when creating a widget. For an example of a JSON file, see JSON File Widget Examples.




The unique identifier for the widget.


The display name of the widget.


The data source of the widget. Must be one of the following:

  • incidents

  • indicators

  • messages

  • entries

  • scripts

    Relevant only when you are creating a script.

  • tasks

  • generics

    Relevant when creating Threat Intel reports. When used, the definitionId value must be ThreatIntelReport.


Queries query data in the Lucene query syntax form relating to the dataType. For example when dataType is incidents and the query is: -status:closed and owner:"", it queries all incidents that are not closed, which does not have an owner.

For script based widgets, the query is the name of the script.


Sorts the data, when displaying the widgetType (applies to table and list widget types) as a list of objects, which consists of the following:

  • field: The field name for which to sort.

  • asc: Whether to sort data in ascending values. If true, the order is in ascending value.


The type of widget you want to create. Must be one of the following:

  • bar

  • column

  • pie

  • number

  • line

  • table

  • trend

  • list

  • duration

  • image


The maximum number of returning elements. Use 0 for the widgetType's default.


  • Table/List: Default is up to 13

  • Chart: Default is up to 10.

  • Number and Trend: Ignores the size value.


Adds a category name. The widget appears under a category instead of being classified by dataType.


The time period for which to return data. The time period is overridden by the dashboard or report time period. Default is all times.

  • fromDate: The start date from which to return data in the format: “YYYY-MM-DDTHH:MM:SSZ”. For example, "2019-01-01T16:30:00Z".

  • toDate: The end date for which to return data in the format: "YYYY-MM-DDTHH:MM:SSZ". For example, "2019-01-01T16:30:00Z".

  • period: An object describing a period of relative time. If using the fromDate/toDate parameters, this parameter is ignored.

    • byTo: The to period unit of measurement. Values are ‘minutes', 'hours', 'days', 'weeks', 'months'.

    • byFrom: The from period unit of measurement. Values are: 'hours', 'days', 'weeks', 'months'.

    • toValue: The duration of the to period. Integer.

    • fromValue: The duration of the from period. Integer. For example, last 7 days - { byFrom: 'days', fromValue: 7 }.


The description of the widget in the Widget Library.


Enriches the widget with specific parameters, mainly based on the widgetType. Includes the following:

  • groupBy: An array of field names for which to group the returned values. Used when widget type is bar, column, line or pie. For example, ["type", "owner"]: Groups results by type and owner, and returns a nested result for each type with statistics according to the owner.


    Bar/column charts defined with two groups can become stacked.

  • hideLegend: Shows or hides the legend, if it exists. Default is false.

  • keys: An array that enables processing the data value and modifies it by the given list of keys. For example, ["avg|openDuration / (3600*24)"] process for each group found in the result, the average open duration (in days).

  • text : The markdown text for text widgets or image data for image widgets. For example, if you want the widgets to appear on separate pages in a report, use [ “\\pagebreak” ].

  • timeFrame: Supplies the custom time frame for which the widget scales. Values are "years", "months", "days", "hours", "minutes". The default is “days”.

  • tableColumns: Enables you to define the name of the columns in a list or table. For example, "[{ "key": "name" }, { "key": "mycustomfield" }]": Displays the name and a custom field.


An array of objects that consists of a name and color. The name must match a group name. The color can be the name of the color, the hexadecimal representation of the color, or the rgb color value.