Advanced DeepSee Modeling Guide
Defining Advanced KPIs
[Back] [Next]
Go to:

This chapter describes how to implement KPIs that use advanced features. It discusses the following:

Also see the chapters Defining Basic KPIs and Defining KPIs with Filters and Listings.”
Defining Manual KPIs
Any KPI is an instance of a subclass of %DeepSee.KPI. In a manual KPI, callback methods set properties of that instance. This section discusses the following topics:
Available Properties
In the callback methods of your KPI instance, the following properties are available:
Overriding KPI Properties
The %OnLoadKPI() callback enables you to override properties of the KPI object instance before it is displayed. You can use this to specify the range and threshold values at run time. This callback has the following signature:
Method %OnLoadKPI() As %Status
You can also set these properties within other methods of the KPI class.
The following example is from HoleFoods.KPISalesVsTarget:
Method %OnLoadKPI() As %Status
    Set tSC = $$$OK

    // Compute additional values
    Set tFilters = ..%filterValues

    // compute recent history using query
    If ((tFilters.Year'="")&&(tFilters.Year'="*")) {
        // Take &[] off of Year value!
        Set tStartMonth = "Jan-"_$E(tFilters.Year,3,6)
        Set tEndMonth = "Dec-"_$E(tFilters.Year,3,6)
    Else {
        Set tStartMonth = "NOW-12"
        Set tEndMonth = "NOW"

    Set tROWS = ..RowsClause
    Set tMDX = "SELECT "_tROWS_"%LIST(DateOfSale.[MonthSold].["_tStartMonth_"]:["_tEndMonth_"]) "
      _"ON COLUMNS FROM HOLEFOODS WHERE Measures.[Amount Sold] " _ ..FilterClause
    Set tRS = ##class(%DeepSee.ResultSet).%New()
    Set tSC = tRS.%PrepareMDX(tMDX)
    If $$$ISERR(tSC) Quit tSC
    Set tSC = tRS.%Execute()
    If $$$ISERR(tSC) Quit tSC

    For n = 1:1:..%seriesCount {
        Set tValue = tRS.%GetOrdinalValue(1,n)
        Set ..%data(n,"History") = tValue
    Quit tSC
This method populates the History property of this KPI. For each product, this property is a comma-separated list of the past sales, month by month.
Defining a Manual Query
To base a KPI on a manual (custom) query, do the following:
In this method, define a query using any logic you need. Then set the %seriesCount, %seriesNames, and %data properties.
The following shows a simple example with hardcoded values:
Method %OnExecute() As %Status
    Set ..%seriesCount=3
    Set ..%seriesNames(1)="alpha"
    Set ..%seriesNames(2)="beta"
    Set ..%seriesNames(3)="gamma"
    Set ..%data(1,"property1")=123
    Set ..%data(1,"property2")=100000
    Set ..%data(1,"property3")=1.234
    Set ..%data(2,"property1")=456
    Set ..%data(2,"property2")=200000
    Set ..%data(2,"property3")=2.456
    Set ..%data(3,"property1")=789
    Set ..%data(3,"property2")=300000
    Set ..%data(3,"property3")=3.789
    Quit $$$OK
Defining Cacheable KPIs
By default, a KPI that uses an MDX query is cached (along with all other MDX queries). This cache may or may not be recent enough for your purposes; that is, you can also cache the KPI specifically as described in this section.
By default, non-MDX KPIs are not cached.
To modify a KPI so that its results are cached, make the following changes to the KPI class:
To clear the cache for a given KPI, call its %ClearKPICache() method.
Defining Asynchronous KPIs
Except for plugins (in the next chapter), KPIs are executed synchronously.
To modify a KPI so that it executes asynchronously, make the following changes to the KPI class: