> 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.7/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.7/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.

Note

| | **`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 displays incident severity by type. It creates a bar chart with incidents from the last 30 days. It groups incidents by severity and then type. The bar length shows the incident count. Create the following JSON file: ```json { "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" ] } } ``` This configuration uses the following parameters: * The widget is called **Incident Severity by Type**. * The data type is **`incidents`**. * The widget type is **`bar`**. * The query excludes job, archived, and closed incidents. * The date range displays the previous 30 days. * The **`groupBy`** value groups by severity, then type, creating a stacked bar chart. After importing the widget into the **Widget Library**, the widget appears as `widget_incident.png`. Incidents are grouped by severity. Bar lengths show incident counts. Colors identify incident types.
Display incidents by 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 ```json { "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: widget-example2.png
--- # 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.7/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.