高度な KPI の定義

この章では、高度な機能を使用する KPI を実装する方法について説明します。項目は以下のとおりです。

“基本的な KPI の定義” の章および “フィルタおよびリストを含む KPI の定義” の章も参照してください。

手動 KPI の定義

任意の KPI は、%DeepSee.KPIOpens in a new tab のサブクラスのインスタンスです。手動 KPI では、コールバック・メソッドがそのインスタンスのプロパティを設定します。このセクションでは、以下の項目について説明します。

利用できるプロパティ

KPI インスタンスのコールバック・メソッドで、以下のプロパティを利用できます。

%seriesCount — この KPI の系列 (行) 数を指定します。
%seriesNames(n) — 系列 n の名前を指定します。n は整数値です。
%data(n,propname) — 系列 n に対して、指定されたプロパティ (propname) の値を指定します。
%rangeLower — 範囲の下限値を指定します。この値により、この KPI がメータで表示されている場合の既定の下限インジケータが設定されます。
%rangeUpper — 範囲の上限値を指定します。この値により、この KPI がメータで表示されている場合の既定の上限インジケータが設定されます。
%thresholdLower — 下限しきい値を指定します。この値により、この KPI がメータで表示されている場合の既定の下限しきい値インジケータが設定されます。
%thresholdUpper — 上限しきい値を指定します。この値により、この KPI がメータで表示されている場合の既定の上限しきい値インジケータが設定されます。
%filterValues — 任意のフィルタの値が含まれます。詳細は、前の章を参照してください。

KPI プロパティのオーバーライド

%OnLoadKPI() コールバックにより、KPI オブジェクト・インスタンスのプロパティを表示前にオーバーライドできます。これを使用すると、実行時に範囲としきい値を指定できます。このコールバックには、以下のシグニチャがあります。

Method %OnLoadKPI() As %Status

これらのプロパティを、KPI クラスの他のメソッド内で設定することもできます。

例

以下の例は、HoleFoods.KPISalesVsTargetOpens in a new tab からの抜粋です。

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
}

このメソッドは、この KPI の History プロパティに値を入力します。このプロパティは、製品ごとの過去の月別の売上を並べたコンマ区切りリストです。

手動クエリの定義

手動 (カスタム) クエリを KPI の基にするには、以下の手順を実行します。

<kpi> 要素内で、sourceType="manual" を指定します。
KPI クラスの %OnExecute() コールバック・メソッドをオーバーライドします。このメソッドには、以下のシグニチャがあります。
```
method %OnExecute() as %Status 
```

このメソッドで、必要に応じた任意のロジックを使用してクエリを定義します。次に %seriesCount、%seriesNames、および %data の各プロパティを設定します。

例

以下は、ハードコードされた値の単純な例を示しています。

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
}

キャッシュ可能な KPI の定義

既定では、MDX クエリを使用する KPI は、(他のすべての MDX クエリと一緒に) キャッシュされます。このキャッシュは、目的に対して十分に最新である場合と最新ではない場合があります。すなわち、このセクションで説明するように、KPI を明示的にキャッシュすることもできます。

既定では、非 MDX KPI はキャッシュされません。

KPI を変更して結果がキャッシュされるようにするには、以下の変更を KPI クラスに適用します。

CACHEABLE クラス・パラメータを 1 に指定します。
%OnComputeKPICacheKey() メソッドを実装します。
```
Method %OnComputeKPICacheKey(Output pCacheKey As %String, 
                            pQueryText As %String = "") As %Status
```
pQueryText は KPI クエリのテキスト、pCacheKey はキャッシュされた結果に関連付けられる一意のキーです。通常、これはクエリ・テキストのハッシュ化した値です。
%OnComputeKPITimestamp() メソッドを実装します。
```
Method %OnComputeKPITimestamp(ByRef pTimestamp As %String, 
                             pSourceType As %String, 
                             pQueryText As %String = "") As %Status
```
pSourceType はクエリ・タイプを示す文字列 ("mdx"、"sql"、または "manual")、pQueryText は KPI クエリのテキスト、pTimestamp は KPI のタイムスタンプです。
%OnComputeKPITimestamp() が、指定された KPI に対して、指定されたキーの KPI キャッシュに格納されている同じタイムスタンプを返す場合、DeepSee はキャッシュされた値を使用します。それ以外の場合、DeepSee はその KPI を返します。
既定では、%OnComputeKPITimestamp() は分単位の精度のタイムスタンプを返します。これは、既定では、キャッシュは (最大) 1 分間保持されることを意味します。

指定された KPI のキャッシュをクリアするには、その %ClearKPICache() メソッドを呼び出します。

非同期 KPI の定義

プラグイン (次の章で説明) を除けば、KPI は同期的に実行されます。

KPI を変更して非同期に実行されるようにするには、以下の変更を KPI クラスに適用します。

ASYNC クラス・パラメータに 1 を指定します。
さらに、KPI を変更して、その結果がキャッシュされるようにします。前のセクションを参照してください。
これは、DeepSee に結果を格納する場所を用意するために必要です。
%OnCompute() 内で、必要に応じて %SetPercentComplete() を呼び出して、処理状態を通知します。詳細は、次の章の “完了状態の通知” を参照してください。