Implementing InterSystems Business Intelligence
Defining Custom Actions
|
|
This chapter describes how to define custom actions for use in InterSystems IRIS Business Intelligence dashboards. It discusses the following topics:
You define custom actions within KPI classes. Then:
-
-
If you specify a KPI class as the
actionClass attribute of the
<cube> element, all actions within this class are available to pivot tables that use this cube, which means they can be added as controls to widgets that display these pivot tables.
-
If you specify a KPI class as the
actionClass attribute of another
<kpi> element, all actions within this class are available to that KPI, in addition to any actions defined within that KPI.
-
You can execute actions from within the Analyzer. Note that in this case, only a subset of the client-side commands are supported:
alert,
navigate, and
newWindow. Other commands are ignored.
You can perform many of the same operations with either a standard action or a custom action:
The system makes context information available to actions, by two different mechanisms. When a user launches a custom action, the system writes context information into the
pContext variable, which is available in your custom code on the server. When a custom action opens a URL, the system replaces the
$$$VALUELIST and
$$$CURRVALUE tokens, if these are included in the URL. The following figure illustrates these mechanisms:
To declare actions, do either or both of the following tasks in a KPI class:
-
Within the
<kpi> element, include one
<action> element for each action.
This element specifies the name of an action available within this KPI class; the user interfaces use this information to create lists of available actions for the users. For example:
<kpi xmlns="http://www.intersystems.com/deepsee/kpi"
name="Holefoods Actions">
<action name="ActionA"/>
<action name="ActionB"/>
<action name="ActionC"/>
</kpi>
-
Override the
%OnGetActionList() callback method of your KPI class. This method has the following signature:
ClassMethod %OnGetActionList(ByRef pActions As %List, pDataSourceName As %String = "") As %Status
Where
pActions is an array with the following nodes:
ClassMethod %OnGetActionList(ByRef pActions As %List, pDataSourceName As %String = "") As %Status
{
set newaction=$LB("New Action","New Action Display Name")
set pActions($I(pFilters))=newaction
quit $$$OK
}
To define the behavior of the actions, override the
%OnDashboardAction() callback method of your KPI class. This method has the following signature:
classmethod %OnDashboardAction(pAction As %String, pContext As %ZEN.proxyObject) as %Status
The system executes this callback when a user invokes an action on a dashboard.
pAction is the logical name of the action.
pContext is an object that contains
information about the currently selected scorecard row and that provides a way for the method to return
commands to the dashboard; the next sections give the details.
A simple example is as follows:
ClassMethod %OnDashboardAction(pAction As %String, pContext As %ZEN.proxyObject) As %Status
{
Set sc = $$$OK
Try {
If (pAction = "Action 1") {
//this part defines Action 1
//perform server-side actions
}
Elseif (pAction="Action 2")
{
//this part defines Action 2
//perform other server-side actions
}
}
Catch(ex) {
Set sc = ex.AsStatus()
}
Quit sc
}
Note:
Because
%OnDashboardAction() is a class method, you do not have access to
%seriesNames or other properties of the KPI class from within this method (no class instance is available from the method).
An action can use context information — values from the dashboard, based on the row or rows that the user selected before launching the action. These values are useful if you want to cause changes in the database that are dependent on context.
Because
%OnDashboardAction() is a class method, you do not have access to
%seriesNames or other properties of the KPI class from within this method. Instead, the system provides the
pContext variable, which is an object whose properties provide information for use in the action. The details are different in the following scenarios:
An action can contain commands to execute when the control returns to the dashboard. To include such commands, set the
pContext.command property within the definition of the action. For example:
//this part defines Action 1
//perform server-side actions
//on returning, refresh the widget that is using this KPI
Set pContext.command="refresh;"
For
pContext.command, specify a string of the following form to execute a single command:
command1;command2;command3;...;
The final semicolon is optional.
Displays the message in a dialog box.
message is the message to display
Set pContext.command = "alert:hello world!"
applyFilter:target:filterSpec
This command sets the given filter and refreshes the browser window.
For example, the following applies a filter to a pivot table:
Set pContext.command = "applyFilter:samplepivot:[DateOfSale].[Actual].[YearSold]:&[2008]"
Where
url is the URL to display.
This command opens the given URL in the same browser window.
Set pContext.command = "navigate:http://www.google.com"
Where
url is the URL to display.
This command opens the given URL in a new browser window.
Set pContext.command = "newWindow:http://www.google.com"
Where
popupurl is the relative URL of a popup window.
This command displays the given popup window. For example:
Set pContext.command = "popup:%ZEN.Dialog.fileSelect.cls"
Where
widgetname is the optional name of a widget to refresh; if you omit this argument, the command refreshes the widget from which the user launched the action.
This refreshes the browser window, using any current settings for filters.
// Refresh the widget that fired this action and another named samplepivot.
Set pContext.command = "refresh;refresh:samplepivot"
Note that this example includes multiple commands, separated by a semicolon.
setFilter:target:filterSpec
This command sets the given filter, but does not refresh the browser window.
The applyFilter and setFilter commands are as follows, respectively:
applyFilter:target:filterSpec
setFilter:target:filterSpec
-
target is the widget to filter. You can use an asterisk (
*) to apply the filter to all widgets.
-
filterSpec specifies the filter value or values to apply to the given target. This must have the following form:
filter_name:filter_values
Where the arguments depend upon the details of the target widget as follows:
-
You can use multiple filter specifications; to do so, separate them with a tilde (
~). For example:
FILTER:filterspec1~filterspec2
-
The filter name and filter values are not case-sensitive for pivot tables or for KPIs that use MDX queries.
-
The filter can affect only widgets that have been configured with a filter control (possibly hidden) that uses the same filter. For example, suppose that a widget includes a Cities filter control, and has no other filter controls. If the action filters to a city, the widget is updated. If the action filters to a ZIP code, the widget is not updated.
In your custom action, you can use the
%CreateTable API to create a SQL table from cube context. The table may be created from either:
-
-
The name of a listing defined in the cube, either as a field list or a custom SQL query.
