Actions to Run Script in Table: Difference between revisions

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


== Overview==
== Overview==
The actions to run scripts are available in the data grid context menu. Loading animation for the data grid is shown during the operation.
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 operation completes successfully or fails, a popup message is shown. The return value of the script is shown as a popup message. If the script throws a user-defined exception, the thrown value is shown as popup message (stacktrace is not shown). If the script throws other than user-defined exception, the error message and stacktrace is shown as popup message.
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 ==
== 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''': Use value '''RunScript''' to run a script.
* '''type''' (mandatory): Use the value '''RunScript''' to run a script.
* '''label''': 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.
* '''completedMessageHeader''': Header of the popup dialog shown when the action is successfully completed.
* '''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.
* '''errorMessageHeader''': Header of the popup dialog shown when the action fails.
* '''scriptName''': Name of the run script.
* '''multiselect''': Whether the action is available when multiple rows are selected (true) or only when one row is selected (false). Default is true.
* '''scriptId''': Id of the run script. When defined, the projectName and scriptName parameters are ignored.
* '''projectName''': Name of the project where the script is located.
* '''multiselect''': Whether the script run is available when multiple rows are selected (''true'') or only when one row is selected (''false''). Default is ''true''.
* '''scriptName''': Name of the script. If the projectName parameter is defined, the script is searched from that project. If the projectName parameter is not defined, the script is search from the project where the dashboard is located.
* '''completedMessageHeader''': Header text of the popup dialog shown when the action is successfully completed.
* '''scriptId: Id of the script. When defined, the projectName and scriptName parameters are ignored.
* '''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.
* '''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 ==
== 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>
[{
[
  {
     "type": "RunScript",
     "type": "RunScript",
     "label": "Run my action 1",
     "label": "Show details",
     "scriptName": "My action 1",
    "icon": "smart_toy",
     "scriptName": "Show row details",
    "multiselect": false,
     "parameters": {
     "parameters": {
       "param1": "val1",
       "param1": "val1",
       "param2": 2.3
       "param2": 2.3
     }
     }
   }, {
   },
  {
     "type": "RunScript",
     "type": "RunScript",
     "label": "Run my action 2",
     "label": "Create ticket",
     "projectName": "${projectName}",
     "icon": "functions",
     "scriptName": "My action 2",
     "projectName": "My project",
     "completedMessageHeader": "Operation completed",
     "scriptName": "Create ticket to external system",
     "errorMessageHeader": "<span>Custom error occurred</span>",
     "completedMessageHeader": "Ticket has been created",
     "icon": "cancel",
     "errorMessageHeader": "Creating ticket failed"
    "multiselect": true
   },
   }, {
  {
     "type": "RunScript",
     "type": "RunScript",
     "label": "<span>Nonexisting action</span>",
     "label": "Get data",
     "icon": "smart_toy",
     "icon": "move",
    "multiselect": false,
     "scriptId": 1
     "scriptId": 123456789,
  }
    "parameters": {
]
      "param1": "val1",
      "param2": 2.3
    }
  }]
</pre>
</pre>


== Example scripts ==
== 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:
<pre>
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;
</pre>
This script sums all selected rows together in the first column. If the column doesn't contain numeric data, an error is thrown:
<pre>
let columnSum;
try {
  columnSum = Sum(selectedData["0"].ToFloat(_));
} catch (error) {
  throw "Selected rows column contains non-numeric data.";
}
return columnSum;
</pre>
This script returns selected model name (''ModelId'' variable is used).
<pre>
let modelId = variables.ModelId;
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>

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