> 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.14/configure-cortex-xsoar/dashboards-and-reports/widgets/create-a-custom-widget-using-a-json-file.md). # Create a custom widget using a JSON file You can create a custom widget for your dashboard or report using a JSON file and then add the new widget to a new or edited dashboard or report. If you want to create more complicated widgets using scripts, see [Create a custom widget using a script](/cortex-xsoar-8-on-prem/8.14/configure-cortex-xsoar/dashboards-and-reports/widgets/create-a-custom-widget-using-a-script.md). 1. Create a JSON file, and add the relevant JSON file widget parameters.
List of JSON file widget parameters | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`id`** | The unique identifier for the widget. | | **`name`** | The display name of the widget. | | **`dataType`** |

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

| | **`query`** |

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.

| | **`sort`** |

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

| | **`widgetType`** |

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

| | **`size`** |

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

| | **`category`** | Adds a category name. The widget appears under a category instead of being classified by **`dataType`**. | | **`dataRange`** |

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

| | **`description`** | The description of the widget in the Widget Library. | | **`params`** |

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

| | **`legend`** | 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. |
2\. Create or edit a dashboard or report. 3. In the **Widget Library** section, click **Upload**. 4. Select the JSON file you created in step 1 and click **Open**. 5. To add the widget to the dashboard or report, click **Add**. ### **JSON file widget examples**
Display incident severity by type The JSON file to display incident severity by type contains the following: * Bar chart * Incidents from the last 30 days * Grouped by severity and for each severity display the nested group size (count of incidents displayed by the length of the bar) colored according to type. Create the following JSON file: ``` { "name": "Incident Severity by Type", "dataType": "incidents", "widgetType": "bar", "query": "-category:job and -status:archived and -status:closed", "dateRange": { "period": { "byFrom": "days", "fromValue": 30 } }, "params": { "groupBy": [ "severity", "type" ] } } ``` You can see the following parameters: * The Widget is called **Incident Severity by type**. * The data type is **incidents**. * The widget type is **bar**. * The **query** specifies that you do not want to return incidents that are categorized as job nor incidents that are archived and closed. * For the date range, the **fromValue** sets the widget to display the last 30 units of time. The **byFrom** sets the units of time to days, which results in the last 30 days. * The **params** parameter is set with a **groupBy** value marking the first group by severity name and then by type (making the bar chart stacked). After you import the widget into the **Widget Library** the following widget appears:
You can see the incidents are grouped by severity and the number of incidents are displayed by the length of the bar, which are colored according to type.
Display incidents by type The JSON file to display incidents by type contains the following: * Vertical bar chart * Incidents from the last 7 days * Grouped by date and type and sorted by date occurred ``` { "dataType": "incidents", "widgetType": "column", "params": { "groupBy": [ "occurred(d)", "type" ], "valuesFormat": "abbreviated", "timeFrame": "days" }, "dateRange": { "period": { "byFrom": "days", "fromValue": 7 } }, "propagationLabels": [ "all" ], "customCalculation": { "operation": "count", "fieldName": "", "expression": "" }, "name": "Change Sort Order In Column Chart - Sort by Date", "sort": [{ "field": "occurred", "asc": true }] } ``` You can see the following parameters: * The Widget is called **`Change Sort Order In Column Chart - Sort by Date`**. * The data type is **`incidents`**. * The widget type is **`column`**. * For the date range, the **`fromValue`** sets the widget to display the last 7 units of time. The **`byFrom`** sets the units of time to days, which results in the last 7 days. * The **`params`** parameter is set with a **`groupBy`** value marking the first group by occurrence date and then by type (making the column chart stacked). After you import the widget into the Widget Library the following widget appears:
--- # 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.14/configure-cortex-xsoar/dashboards-and-reports/widgets/create-a-custom-widget-using-a-json-file.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.