Defining Plugins

Introduction

A plugin is a class that defines one or more computations to use in the Analyzer and in queries. A plugin has the following features:

• In any given context, the plugin instance has access to the lowest-level data.

• It can accept parameters.

• It executes asynchronously. When the plugin is used in a pivot table, DeepSee can display the plugin current status (as the string n% complete) in any pending cells.

  The pivot table automatically refreshes when the results are available.

• Values returned by the plugin are cached.

Plugins are especially appropriate for complex or time-consuming computations. For example, you might have a computation that uses several different parts of the source record, as well as external information; a plugin would be suitable in this case.

Requirements for a Simple Plugin

To define a simple plugin, create a class as follows:

• Use %DeepSee.KPIPlugInOpens in a new tab as a superclass.

• Define an XData block named KPI that specifies at least one property. For example:

  XData KPI [ XMLNamespace = "http://www.intersystems.com/deepsee/kpi" ]
  {
  <kpi name="PluginDemo" displayName="PluginDemo" caption="PluginDemo" >
  
  <property name="PatientCount" displayName="PatientCount" />
  <property name="HighScoreCount" displayName="HighScoreCount" />
  
  </kpi>
  }

  

  You can also include filters, as with other KPIs.

  For details, see the appendix “Reference Information for KPI and Plugin Classes.”

• Specify the BASECUBE class parameter. For a simple plugin, specify the logical name of a single cube or subject area. (But also see “Creating a Plugin for Multiple Cubes,” later in this chapter.)

• Specify the base MDX query to use. Either specify the mdx attribute of <kpi> or implement the %OnGetMDX() method in the following generic way:

  Method %OnGetMDX(ByRef pMDX As %String) As %Status
  {
      Set pMDX = "SELECT FROM "_..#BASECUBE
      Quit $$$OK
  }
  

  

  DeepSee automatically applies context information (row, column, and filter) to this base query.

• Specify the fields that need to be available to the %OnCompute method. These can be fields in the source table of the cube or can be fields in the fact table. You can specify a hardcoded list, or you can use a callback to define the list of fields.

  To specify these fields:

  • If the fields you want to use are in the fact table, specify the LISTINGSOURCE class parameter as "FactTable". (For details on the fact table, see “Details for the Fact and Dimension Tables” in Defining DeepSee Models.)

    If you omit this parameter or specify it as "SourceTable", the plugin queries the source table of the given cube.

  • If you want to specify a hardcoded list of field names, specify the LISTINGFIELDS class parameter. Specify a comma-separated list of fields to use.

    For example:

    Parameter LISTINGFIELDS = "Field1, Field2, Field3";

    

    You can specify an alias for any field. For example:

    Parameter LISTINGFIELDS = "Field1, Field2 as FieldAlias, Field3";

    

    You can also use Caché arrow syntax and SQL functions, as with other listings.

    If you use Caché arrow syntax, be sure to specify an alias for the field.

  • Or if you want to define the list of fields programmatically, implement the %OnGetListingFields() method. For example, the following method causes the plugin to retrieve a single field:

    Method %OnGetListingFields() As %String
    {
        //could use an API to get the field name, but in this case factName is set 
        //so the field name is known
        Set tListingFields = "MxTestScore"
        Quit tListingFields
    }

    

    For information, see “Defining a Listing for a KPI,” earlier in this book.

  Note:

  For a plugin, the LISTINGFIELDS parameter and the %OnGetListingFields() do not define a detail listing or any listing fields. These options only define the fields that are available to the %OnCompute() method.

• Implement the %OnCompute() method. The following section provides details on this task.

• Optionally specify the PLUGINTYPE and PUBLIC class parameters. See “How Plugins Can Be Used,” earlier in this chapter.

Implementing %OnCompute()

For each pivot table cell where the plugin is used, the plugin performs either a DRILLTHROUGH or DRILLFACTS query (depending on the value of LISTINGSOURCE) and returns the fields specified by LISTINGFIELDS or %OnGetListingFields() (as applicable). It then passes the field values to the %OnCompute() method. This method has the following signature:

Method %OnCompute(pSQLRS As %SQL.StatementResult, pFactCount As %Integer) As %Status

Where:

• pSQLRS is an instance of %SQL.StatementResultOpens in a new tab that contains the fields specified by LISTINGFIELDS or %OnGetListingFields().

  For information on using this class, see “Using Dynamic SQL” in Using Caché SQL.

• pFactCount is total number of facts in the given context.

In your implementation of this method, do the following:

1. Iterate through the statement result. To do so, use the %Next() method of this instance.

2. As needed, retrieve values for each row. The statement result instance (pSQLRS) provides one property for each field in the listing query; the name of the property is the same as the field name.

   For example, in the previous section, %OnGetListingFields() retrieves a single field, MxTextScore. In this case, pSQLRS has a property named MxTextScore.

3. Perform the desired computations.

4. Set the properties of the plugin instance, as described in the previous chapter. At a minimum, set the following properties:

   • %seriesCount — Specifies the number of series (rows) in this plugin.

     InterSystems recommends that plugins have only one series. (For plugins with PLUGINTYPE equal to "Pivot", when a user drags and drops a plugin property, the Analyzer uses only the first series.)

   • %seriesNames(n) — Specifies the name of the series n, where n is an integer.

   • %data(n,propname) — Specifies the value of the given property (propname), for the series n.

     The property name must exactly match the name of a <property> in the XData block.

For example:

 // place answer in KPI output
 Set ..%seriesCount = 1
 Set ..%seriesNames(1) = "PluginDemo"
 //set Count property of KPI -- just use received pFactCount
 Set ..%data(1,"PatientCount") = pFactCount
 
 // iterate through result set to get HighScoreCount 
 set n = 0
 Set highcount = 0
 While (pSQLRS.%Next(.tSC)) {
   If $$$ISERR(tSC) Quit
   set n = n + 1

   Set testscore = pSQLRS.MxTestScore
   if (testscore>95) {
     Set highcount = highcount + 1
  }

 }
 Set ..%data(1,"HighScoreCount") = highcount

This is an extract from DeepSee.Model.KPIs.PluginDemoOpens in a new tab in SAMPLES, which is available in the Analyzer for use with the Patients cube.

Indicating State of Completion

Plugins are executed asynchronously. When a query containing plugins is executed, the query can be complete before the plugins have completed execution. In this case, there are cells whose results are pending. Within these cells, you can display the plugin current status (as the string n% complete). To do so, within %OnCompute(), periodically invoke the %SetPercentComplete() instance method; the argument is an integer between 0 and 100. For example, you could do the following while iterating through the statement result:

    // update pct complete
    If (n#100 = 0) {
        Do ..%SetPercentComplete(100*(n/pFactCount))
    }

The appropriate approach depends on the logic in %OnCompute(). In some cases, the majority of the computation time might occur outside of this iteration.

The pivot table automatically refreshes when the results are available.

Creating a Plugin for Multiple Cubes

The previous sections describe how to create a plugin that can be used with a single cube or subject area. You can also create a plugin that can be used in multiple cubes. In practice, this is difficult to do because it is usually necessary to programmatically determine the fields to query.

To create a plugin that you can use with multiple cubes, use the following additional instructions:

• Specify the BASECUBE class parameter as one of the following:

  • A comma-separated list of logical cube or subject area names

  • "*" — refers to all cubes and subject areas in this namespace

  This option determines which cubes and subject areas can use the plugin.

• Include the following filter definition within the XData block:

  <filter name="%cube" displayName="Subject Area" />
  

  

  The name must be %cube but you can use any value for the display name.

  When you use this plugin within the Analyzer (if applicable), DeepSee passes the name of the current cube or subject area to this filter. Similarly, when you use this plugin within an MDX query, the FROM clause of the query determines the value of this filter.

• Implement the %OnGetMDX() method so that it uses the value of the %cube filter. For example:

  Method %OnGetMDX(ByRef pMDX As %String) As %Status
  {
      Set tBaseCube = ""
  
      // Use %cube filter to find the base cube
      If $IsObject(..%filterValues) {
          If (..%filterValues.%cube'="") {
              Set tBaseCube = ..%filterValues.%cube
          }
      }
  
      If (tBaseCube'="") {
          Set pMDX = "SELECT FROM "_tBaseCube
      }
      Quit $$$OK
  }

  

• Ensure that the listing query can work with all the desired cubes and subject areas. Either:

  • For hardcoded listings, use only fields that are suitable in all cases.

  • Programmatically determine the fields to use.

For examples, see %DeepSee.PlugIn.MedianOpens in a new tab and %DeepSee.PlugIn.PercentileOpens in a new tab.

Filtering the Listing

Plugins provide a feature that is not available in other scenarios: namely, the ability to specify which records to use when a detail listing is displayed. By default, when a user requests a detail listing for a given cell or set of cells in the results, DeepSee displays a listing that shows all the records associated with those cells. In some cases, however, it is preferable to show a subset of them. For example, the sample DeepSee.Model.KPIs.PluginDemoOpens in a new tab has a plugin property called HighScoreCount. The following shows an example MDX query that uses this plugin property as a measure:

SELECT NON EMPTY {[Measures].[%COUNT],%KPI("PluginDemo","HighScoreCount",,"%CONTEXT")} ON 0,NON EMPTY [AllerSevD].[H1].[Allergy Severities].Members ON 1 FROM [PATIENTS]
 
                       Patient Count       HighScoreCount
1 Nil known allergi               158                   12
2 Minor                           113                    7
3 Moderate                        103                    5
4 Life-threatening                133                    9
5 Inactive                        122                    8
6 Unable to determi               119                    6
7 No Data Available               385                   29

Consider the row for Nil known allergies. If you display a listing for either cell, by default, DeepSee displays a listing that consists of 158 records, because there are 158 patients with no known allergies. But the purpose of the HighScoreCount measure is to count the patients with scores above a given threshold, so when we display the detail listing for the cell HighScoreCount in this row, we might prefer to see only the patients with scores above that threshold.

To apply this sort of filtering to a plugin, include the following logic in your implementation of %OnCompute(), for any source class ID that should be shown in the listing:

   set ..%data("IDLIST",pluginProperty,sourceClassID) = ""

Where pluginProperty is the name of the plugin property that should use this filtering, and sourceClassID is the ID in the source class. (The ID should be a source class ID even if plugin otherwise uses the fact class. To make the source class ID available to the plugin, add %sourceId to the field list.)

For a given plugin property, if %data("IDLIST",pluginProperty) is not defined, the listing shows all the records associated with the given cell or cells.

Available Error Logging

If a plugin encounters an error, DeepSee writes to the error log file in the manager’s directory. The name of this file is DeepSeeTasks_namespace.log.

Defining a Calculated Member That Uses a Plugin

For any plugin (and any other KPI), you can create a calculated member that retrieves values from it. Then users can drag and drop this member within the Analyzer. To create such a calculated member:

• Define a calculated measure as described in “Defining a Calculated Measure,” in Defining DeepSee Models.

• For Expression, specify an MDX expression of the following form:

  %KPI(pluginname,propertyname,seriesname,"%CONTEXT")
  

  

  Where pluginname is the name of the plugin, propertyname is the name of the property, and seriesname is the name of the series. You can omit seriesname; if you do, this function accesses the first series in the plugin.

  "%CONTEXT" is a special parameter that provides row, column, and filter context to the plugin; this information is passed to the base MDX query used by the plugin.

  For example (for a plugin with only 1 series):

  %KPI("PluginDemo2","Count",,"%CONTEXT")
  

  

  For plugins with PLUGINTYPE equal to "Pivot", when a user drags and drops a plugin property, the Analyzer automatically uses syntax like this in the underlying MDX query that it generates.

  For additional options, see the %KPI function in the DeepSee MDX Reference.