Actions to Run Script in Table: Difference between revisions

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search
 
(16 intermediate revisions by the same user not shown)
Line 1: Line 1:


== Overview==
== Overview==
Dashboard functionality can be extended by running scripts that are started from the table's context menu. Scripts can for example call external web services or retrieve additional information for the selected rows.
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 as a popup message. If the script run fails, the error message is also shown to the user. If the script throws a user-defined exception, the thrown value is shown as popup message. If the script throws other than user-defined exception, the more detailed error message is shown as popup message. Loading animation is shown during the entire script run, so the script should preferably run pretty 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 also when multiple rows are selected. Depending on the intended action, the multi-row selection may or may not be suitable.
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: The script are able to modify data in the system and the script is run with user's own permissions, so when running a script, make sure what the script contains.
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 ==
== Action settings ==
Following action settings are available:
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 value '''RunScript''' to run a script.
* '''type''' (mandatory): Use the value '''RunScript''' to run a script.
* '''label''' (mandatory): Text visible in the context menu item.
* '''label''' (mandatory): Text visible in the context menu item.
* '''icon''': Google Material icon 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 not defined, the script is assumed to be found in the project where the dashboard is located.
* '''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.
* '''scriptName''': Name of the run script.
* '''scriptId''': Id of the run script. When defined, the projectName and scriptName parameters are ignored.
* '''scriptId''': Id of the run script. When defined, the projectName and scriptName parameters are ignored.
Line 22: Line 22:
* '''parameters''': Object of additional parameters for the script. The parameters are available as a dictionary in the script.
* '''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.
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 ==
== Passed parameters ==
Following parameters are passed to the script and are available as variables in the script:
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 rows data for each column. The data is available as following keys:
* '''selectedData''': Dictionary of arrays containing the selected row(s) data for each column. The data is available as following keys:
** Column header labels (the ones that are visible in the table)
** Column header labels (text visible in the table header row)
** Column technical names (dimension0, dimension1, ... measure0, measures2, ...).
** Column technical names (dimension0, dimension1, ... measure0, measures2, ...).
** Column indices (0, 1, 2, ...)
** Column indices (0, 1, 2, ...)
* '''rowIndice'''s: Array of selected row indices (first row is zero).
* '''rowIndices''': Array of selected row indices (first row is zero).
* '''variables''': Dictionary of dashboard variables.
* '''variables''': Dictionary containing dashboard variables.
* '''action''': Dictionary containing settings of the clicked action. (This is the way to access the action parameters.)
* '''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.
* '''query''': Dictionary containing the query made by the chart.
* '''chartSettings''': Dictionary containing the chart settings.
* '''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:
<pre>
"rowIdentifier": true
</pre>
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 ==
== Example action settings ==
This example configures three different kind of actions:
<pre>
<pre>
[
[
Line 43: Line 52:
     "label": "Show details",
     "label": "Show details",
     "icon": "smart_toy",
     "icon": "smart_toy",
     "scriptName": "Snow row details",
     "scriptName": "Show row details",
    "multiselect": false,
     "parameters": {
     "parameters": {
       "param1": "val1",
       "param1": "val1",
Line 52: Line 62:
     "type": "RunScript",
     "type": "RunScript",
     "label": "Create ticket",
     "label": "Create ticket",
     "icon": "smart_toy",
     "icon": "functions",
     "projectName": "My project",
     "projectName": "My project",
     "scriptName": "Create ticket to external system",
     "scriptName": "Create ticket to external system",
     "completedMessageHeader": "Ticket has been created",
     "completedMessageHeader": "Ticket has been created",
     "errorMessageHeader": "Creating ticket failed",
     "errorMessageHeader": "Creating ticket failed"
    "multiselect": true
   },
   },
   {
   {
     "type": "RunScript",
     "type": "RunScript",
     "label": "Get data",
     "label": "Get data",
     "icon": "smart_toy",
     "icon": "move",
     "scriptId": 1
     "scriptId": 1
   }
   }
Line 70: Line 79:
== Example scripts ==
== Example scripts ==


This script reads the first two columns and sums them together. If the columns doesn't contain numeric data, an error is thrown:
This script reads the first two columns and sums them together. If the columns don't contain numeric data, an error is thrown:
<pre>
<pre>
let firstNumber = rowData["0"][0];
let firstNumber = selectedData["0"][0];
try {
try {
   firstNumber = ToFloat(firstNumber);
   firstNumber = ToFloat(firstNumber);
Line 78: Line 87:
   throw "First column doesn't contain number";
   throw "First column doesn't contain number";
}
}
let secondNumber = rowData["1"][0];
let secondNumber = selectedData["1"][0];
try {
try {
   secondNumber = ToFloat(secondNumber);
   secondNumber = ToFloat(secondNumber);
Line 87: Line 96:
</pre>
</pre>


This script reads the first column sums them together. If the column doesn't contain numeric data, an error is thrown:
This script sums all selected rows together in the first column. If the column doesn't contain numeric data, an error is thrown:
<pre>
<pre>
let columnSum;
let columnSum;
try {
try {
   columnSum = Sum(rowData["0"].ToFloat(_));
   columnSum = Sum(selectedData["0"].ToFloat(_));
} catch (error) {
} catch (error) {
   throw "Selected rows column contains non-numeric data.";
   throw "Selected rows column contains non-numeric data.";
Line 98: Line 107:
</pre>
</pre>


This script returns selected model name.
This script returns selected model name (''ModelId'' variable is used).
<pre>
<pre>
let modelId = variables.ModelId;
let modelId = variables.ModelId;
return ModelById(modelId).Name;
return ModelById(modelId).Name;
</pre>
This script calculates the number of cases in the filtered data (''ModelId'' and ''Filter'' variables are used).
<pre>
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];
</pre>
</pre>

Latest revision as of 22:22, 23 April 2024

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];