Ctrlk
BlogSupport
For the complete documentation index, see llms.txt. This page is also available as Markdown.
XSOAR 6.13

Create a Custom Widget Using an Automation Script

Create custom widgets in Cortex XSOAR 6.13 with automation scripts for dashboards and reports.

You can use custom script based widgets with an automation script to create dynamic widgets for more complex calculations. For examples of creating widgets using scripts, see Script Based Widgets Using Automation Scripts Examples.

Note

Cortex XSOAR supports JavaScript, Python and PowerShell.

You need to create or upload the script to the Automation page and then you can create a widget in Widgets Library. In the Widgets Library, you can define the arguments and change the visuals.

Note

If you upload a script to the Automation page, the Arguments field is automatically updated. You can then define the arguments in the Widget Builder. If you create a new automation (without uploading) in the Automation page, you need to add the arguments manually for them to appear in the Widgets Library when creating or editing a widget.

  1. In the Automation page, upload or create a new automation.

    Create the following widgets using automations:

    • Text

    • Number

    • Duration

    • Trend

    • Chart

    • Table or List

    • Filter Data for all Widgets (Pivoting)

    For examples, see Script Based Widgets Using Automation Scripts Examples.

  2. For dashboards and reports, create a widget in the Widgets Library, as described in Create a Widget using the Widget Builder.

  3. Select the Script based data type and then add the script.

    (Upload automation only) If you have added arguments, these appear when creating a widget. If you have not uploaded the automation, you need to add the arguments manually on the Automation page.

  4. Add the script based widget to one of the following:

Script Based Widgets Using Automation Scripts Examples

Use the following arguments/scripts to create a widget. After creating the script, Create a Widget using the Widget Builder.

Arguments Used In An Automation

If you want to add timestamp, or a use a search query, add the following arguments to an automation.

Argument
Description

demisto.args()[‘from’]

The start date of the timestamp date range of the widget.

demisto.args()[‘to’]

The end date of the timestamp date range of the widget.

demisto.args()['searchQuery']

The search query entered into the search bar at the top of the dashboard.

Text

In this example, create a script that queries and returns current on-line users, and displays the data in a markdown table.

In the automation script, type one of the following return values:

JavaScript

return executeCommand("getUsers", {online: true})[0].HumanReadable;

Python

demisto.results(demisto.executeCommand("getUsers", { "online": True })[0]["HumanReadable"])

To add a page break when creating or editing a widget in Cortex XSOAR, type /pagebreak in the text box. When you generate a report, the widgets that follow the page break are on a separate page.

quick_definitions_pagebreak.png

In the dashboard, the following widget displays the online users:

onelineusers_widget.png

Note

(Multi-tenant) Script-based text widgets are not supported in the Main Account.

Number

This example shows how to create a single-item widget with the percentage of incidents that DBot closed.

In the automation script, type one of the following:

JavaScript

Python

Duration

In this example, create a script that queries and returns a time duration (specified in seconds), and displays the data as a countdown clock. If using a JSON file, you must set widgetType to duration.

In the automation script, type one of the following return values:

JavaScript

return JSON.stringify([{ name: "", data: [120] }]);

Python

demisto.results('[{"name": "", "data": [120]}]')

The return type should be a string (any name) and an integer. The time is displayed in seconds.

After you have uploaded the script and created the widget, you can add the widget to the dashboard or report. The following widget displays the time duration:

widget_time_example.png

Chart

A valid result for a chart widget is a list of groups. Each group points to a single entity, for example in bar charts each group is a bar. A group consists of the following:

  • Name - A string.

  • Data - An array of integers.

  • Color - A string representing a color that will be used as a default color for that group. It can be the name of the color, a hexadecimal representation of the color, or an rgb color value (optional).

    Note

    A widget legend color will override a group color if it exists.

  • Groups - A nested list of groups (optional).

In this example, we show how to create a script that will query and return the trend between two sums in a pie chart.

  • Pie

  • Line

  • Bar

  • Column

Simple piechart

In the automation script, type the following return value:

JavaScript

Python

After you have uploaded the script and created the widget you can add the widget to a dashboard or report. The following widget displays the trend in a pie chart:

widget_example_pie.png

Two-group chart

JavaScript

Python

automation_widget_chart.png

Trend

In this example, create a script that queries and returns the trend between two sums.

In the automation script, type one of the following return values:

JavaScript

return JSON.stringify({currSum: 48, prevSum: 32});

Python

demisto.results({ "currSum": 48, "prevSum": 32 })

The return displays an object which compares the current sum with the previous sum.

Table or List

In this example, you need to create a script that queries and returns employee information in a table. For Table or List, if creating a JSON file, set the widgetType to table or list. When using lists, a maximum of two columns displays, the rest are ignored (do not display).

In the automation script, type one of the following return values:

JavaScript

Python

After you have uploaded the script and created a widget you can add the widget to a dashboard or report. The following widget displays the employee information:

widget_example_employee.png

Filter Data for all Widgets (Pivoting)

Example: Display Filtered Incident and Indicator Data in a Widget with a Bar Graph

In this example, you create a filter according to type (phishing, access and IP) and then pivot to the relevant incident/indicators page. You need to add the following to the JSON or python automation script.

  • dataType: Pivots to the relevant page, such as Incidents page.

  • query: Filters according to the value in the relevant page. For example, for phishing, if you define ‘type:Phishing’ and the dataType:incidents, you are taken to the Incident page with the ‘type:Phishing’ filter.

  • pivot: Filters the dashboard according to data set. For example, pivot: “type:Phishing” enables you to filter data that relates to phishing in the dashboard.

In the automation script, type one of the following return values:

JavaScript

Python

After you upload the script and create a widget, add the widget to a dashboard or report page.

widget-customfilter.png

Example: Display Filtered Incident and Indicator Data in a Widget with a Line Graph

In this example, you create a filter according to type (phishing, access and IP) and then pivot to the relevant incident/indicators page. You need to add the following to the JSON or python automation script.

JavaScript

Python

After you upload the script and create a widget, add the widget to a dashboard or report page.

Create a Widget from an Indicator

Widgets are the visual components that populate dashboards and reports with specific data. Although there are various out-of-the-box system widgets available, you can create custom widgets from indicators and then add them to a dashboard or report. You can also Create a Widget using the Widget Builder.

To create a widget from an indicator, you need to run a query from the Indicators page, and then save the visual results as a widget.

  1. In the Threat Intel (Indicators) page, from the dropdown list select the date range.

  2. In the query field, type the query criteria as required and run the query.

  3. Click create-widget.png.

  4. Follow the procedure in Create a Widget using the Widget Builder.

  5. Click Save.

    The widget is added to the Widgets Library.

    Note

    By default, the widget inherits the date range that you specify when creating the widget, but you can modify the date range when you create the dashboard or report. If the date range for the report or dashboard does not include the widget date range, the data is blank. To override the dashboard or report’s date range, click Use Widget’s date range.

  6. Add the widget to a report or dashboard, as required.

Add a Custom Widget to the Indicator Page

You can add a custom widget to the info tab when you view a detailed indicator. Every time you open the detailed incident or indicator type you can see the widget.

Before you start, you need to create a custom widget, as described in Create a Custom Widget Using an Automation Script.

Note

In the Automation page, when adding or editing the script you want to use, ensure that you add the dynamic-indicator-section label.

  1. Go to Settings → OBJECTS SETUP → Indicators → Types.

  2. Select the indicator type you want the widget to appear in and click Edit layout.

  3. From the Layout Builder window, in the Library section, drag the General Purpose Dynamic Section into the layout area you want it to appear.

  4. In the General Purpose Dynamic Section, click the edit button.

  5. Type a name and description for the widget.

  6. In the Automation script field, from the dropdown list select the automation script you want to add.

    Note

    If the automation script does not appear, you need to add the dynamic-indicator-section label to the script in the Automation page.

  7. Click OK.

    For an example of adding a widget to an incident (which follows the same procedure), see Add a Custom Widget to the Incident Page.

PreviousCreate a Custom Widget Using a JSON File
NextEdit a Widget

Last updated

Was this helpful?