Actions to Run Script in Table

Overview

Dashboard functionality can be extended by running scripts that are started from the table's context menu. For example, the scripts can call external web services or retrieve additional information for the selected rows in the table. The scripts are run synchronously, i.e., a loading animation is shown during the entire script run and user needs to wait for the script completion. Thus, the script should preferably be designed to run quickly.

When the script run is completed, the return value of the script is shown to the user in a popup dialog. If the script run fails, the error response is also shown to the user. If a script throws a user-defined exception, the thrown value is shown in the popup dialog. If the script throws other than user-defined exception, the more detailed error message is shown as popup message.

The script action can be configured to be available only when a single row is selected in the table or when multiple rows are selected. Depending on the intended action, the multi-row selection may or may not be suitable.

Security note: Scripts are run with user's own permissions and they are able to modify data in the system, so when running a script action, the user needs to be sure what does the script contain.

Action settings

Chart actions can be set in the chart settings by clicking Chart actions in the Advanced tab. Actions are configured in json format (see next chapter for examples). Following action settings are available:

• type (mandatory): Use the value RunScript to run a script.
• label (mandatory): Text visible in the context menu item.
• icon: Google Material icon visible left of the context menu item.
• projectName: Name of the project where the script is located. If this setting is not defined, the script is searched in the project where the dashboard is located.
• scriptName: Name of the run script.
• scriptId: Id of the run script. When defined, the projectName and scriptName parameters are ignored.
• multiselect: Whether the script run is available when multiple rows are selected (true) or only when one row is selected (false). Default is true.
• completedMessageHeader: Header text of the popup dialog shown when the action is successfully completed.
• errorMessageHeader: Header text of the popup dialog shown when the action fails.
• parameters: Object of additional parameters for the script. The parameters are available as a dictionary in the script.

The type and label are mandatory, and either the scriptName or scriptId is mandatory depending whether to define the script by name or by id.

Passed parameters

Following parameters are passed to the script and are available as variables in the script (see examples below how to use the variables):

• selectedData: Dictionary of arrays containing the selected row(s) data for each column. The data is available as following keys:
  • Column header labels (text visible in the table header row)
  • Column technical names (dimension0, dimension1, ... measure0, measures2, ...).
  • Column indices (0, 1, 2, ...)
• rowIndices: Array of selected row indices (first row is zero).
• variables: Dictionary containing dashboard variables.
• action: Dictionary containing settings of the clicked action. This is where to access the action parameters.
• query: Dictionary containing the query made by the chart.
• chartSettings: Dictionary containing the chart settings.

Row identifier

The context menu needs a way to uniquely identify the selected rows. By default, the first column is assumed to contain unique values. If that is not the case, the selection doesn't work correctly, as it selects all rows that have the same value in the first column. It's possible to define any column as a row identifier by modifying the chart json settings (Advanced tab, Chat settings (editable)) and add the following property to the column or dimension that has the unique values:

"rowIdentifier": true

Note that only one column can serve as the row identifier. Tip: if you don't want to show the row identifier column, it can be hidden in the column/dimension settings.

Example action settings

This example configures three different kind of actions:

[
  {
    "type": "RunScript",
    "label": "Show details",
    "icon": "smart_toy",
    "scriptName": "Show row details",
    "multiselect": false,
    "parameters": {
      "param1": "val1",
      "param2": 2.3
    }
  },
  {
    "type": "RunScript",
    "label": "Create ticket",
    "icon": "functions",
    "projectName": "My project",
    "scriptName": "Create ticket to external system",
    "completedMessageHeader": "Ticket has been created",
    "errorMessageHeader": "Creating ticket failed"
  },
  {
    "type": "RunScript",
    "label": "Get data",
    "icon": "move",
    "scriptId": 1
  }
]

Example scripts

This script reads the first two columns and sums them together. If the columns don't contain numeric data, an error is thrown:

let firstNumber = selectedData["0"][0];
try {
  firstNumber = ToFloat(firstNumber);
} catch (error) {
  throw "First column doesn't contain number";
}
let secondNumber = selectedData["1"][0];
try {
  secondNumber = ToFloat(secondNumber);
} catch (error) {
  throw "Second column doesn't contain number";
}
return firstNumber + secondNumber;

This script sums all selected rows together in the first column. If the column doesn't contain numeric data, an error is thrown:

let columnSum;
try {
  columnSum = Sum(selectedData["0"].ToFloat(_));
} catch (error) {
  throw "Selected rows column contains non-numeric data.";
}
return columnSum;

This script returns selected model name (ModelId variable is used).

let modelId = variables.ModelId;
return ModelById(modelId).Name;

This script calculates the number of cases in the filtered data (ModelId and Filter variables are used).

let data = Query(#{
  "ProcessingMethod": "dataframe",
  "ContextType": "model",
  "ModelId": variables.ModelId,
  "Root": "Cases",
  "Filter": ParseJson(variables.Filter),
  "Dimensions": [],
  "Values": [#{
    "Name": "caseCount",
    "AggregationFunction": "count"
  }],
}).Collect();
return data[0];