Defining Custom Actions

Context Information

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:

Declaring Actions

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>
  

  

  For information on <action>, see Reference Information for KPI and Plug-in Classes in Advanced Modeling for InterSystems Business Intelligence.

• 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:

  Node	Value
  pActions	Number of actions
  pActions(n)	Details for the nth action. This is a $LISTBUILD list that consists of the following items: A string that equals the logical action name A string that equals the corresponding display name

  And pDataSourceName is for future use.

  For example:

  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
  }
  

  

Defining the Behavior of the Actions

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
}

This method defines two actions, Action 1 and Action 2.

Scenario: Pivot Table Widget with Pivot Table as Data Source

In this scenario, within the %OnDashboardAction() method, the pContext object contains the properties described in the following table. As noted, the contents of the pContext object vary depending on whether the widget is displaying the pivot table itself (pivot mode) or a listing (listing mode).

Scenario: Pivot Table Widget with KPI as Data Source

In this scenario, within the %OnDashboardAction() method, the pContext object contains the properties described in the following table. As noted, the contents of the pContext object vary depending on whether the widget is displaying the pivot table itself (pivot mode) or a listing (listing mode).

Scenario: Scorecard with Pivot Table or KPI as Data Source

For scorecards, the contents of the pContext object within the %OnDashboardAction() method are mostly the same regardless of whether the data source is a pivot table or a KPI. The following table describes the contents of pContext for a scorecard, noting where there are variations depending on the data source:

Available Commands

Within pContext.command, you can use the following commands:

alert

alert:message

Displays the message in a dialog box. message is the message to display

For example:

 Set pContext.command = "alert:hello world!"

applyFilter

applyFilter:target:filterSpec

For information on the arguments, see Details for applyFilter and setFilter.

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

navigate

navigate:url

Where url is the URL to display.

This command opens the given URL in the same browser window.

For example:

 Set pContext.command = "navigate:http://www.google.com"

newWindow

newWindow:url

Where url is the URL to display.

This command opens the given URL in a new browser window.

For example:

 Set pContext.command = "newWindow:http://www.google.com"

popup

popup:popupurl

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"

refresh

refresh:widgetname

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.

For example:

 // 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

setFilter:target:filterSpec

For information on the arguments, see Details for applyFilter and setFilter.

This command sets the given filter, but does not refresh the browser window.

Details for applyFilter and setFilter

The applyFilter and setFilter commands are as follows, respectively:

applyFilter:target:filterSpec

And:

setFilter:target:filterSpec

Where:

• 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:

  Scenario	filter_name	filter_values
  Target widget displays a pivot table	[dimension].[hierarchy].[level]	See Allowed Default Values for Filters in Configuring Settings.
  Target widget displays a KPI	Name of a filter defined in that KPI	One of the allowed values for this filter, as defined in the KPI

  Notes:

  • 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.