Actions to Run Script in Table: Difference between revisions

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


== Overview==
== Overview==
Chart actions are available in the data grid context menu.
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.
2. Loading animation for the data grid is shown during the operation.
3. When the operation completes successfully or fails, a popup message is shown.
+4. All actions support parameters listed in #71802#.
5. Following types of actions are available:
5.1 End tasks: Can be used when data grid is showing tasks. The selected tasks are ended (#71800#).
+5.2 Run script: Runs the defined script and shows return value as popup dialog (#71798#).


1. When action type is "RunScript", the action will run the defined script.
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.
2. The return value of the script is shown as a popup message.
3. If the script throws a user-defined exception, the thrown value is shown as popup message (stacktrace is not shown).
4. If the script throws other than user-defined exception, the error message and stacktrace 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 ==
5. Following action parameters are supported:
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:
1.1 label: Text visible in the context menu item.
* '''type''' (mandatory): Use the value '''RunScript''' to run a script.
1.2 icon: Google Material icon visible in the context menu item.
* '''label''' (mandatory): Text visible in the context menu item.
1.3 completedMessageHeader: Header of the popup dialog shown when the action is successfully completed.
* '''icon''': Google Material icon visible left of the context menu item.
1.4 errorMessageHeader: Header of the popup dialog shown when the action fails.
* '''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.
1.5 multiselect: Whether the action is available when multiple rows are selected (true) or only when one row is selected (false). Default is true.
* '''scriptName''': Name of the run script.
5.1 projectName: Name of the project where the script is located.
* '''scriptId''': Id of the run script. When defined, the projectName and scriptName parameters are ignored.
5.2 scriptName: Name of the script.
* '''multiselect''': Whether the script run is available when multiple rows are selected (''true'') or only when one row is selected (''false''). Default is ''true''.
5.2.1 If the projectName parameter is defined, the script is searched from that project.
* '''completedMessageHeader''': Header text of the popup dialog shown when the action is successfully completed.
5.2.2 If the projectName parameter is not defined, the script is search from the project where the dashboard is located.
* '''errorMessageHeader''': Header text of the popup dialog shown when the action fails.
5.3 scriptId: Id of the script.
* '''parameters''': Object of additional parameters for the script. The parameters are available as a dictionary in the script.
5.3.1 When defined, the projectName and scriptName parameters are ignored.
 
5.4 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, ...)
* rowIndices: 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];