Skip to main content

%DeepSee.KPI

Class %DeepSee.KPI Extends %DeepSee.AbstractKPI [ Abstract, System = 4 ]

Subclasses of this class are used to define KPIs (key performance indicators). A KPI defines a set of related values that can be used to drive widgets on a DeepSee dashboard.
A KPI can define a set of actions that can be called from control buttons on a dashboard widget.
Each KPI class is also also a %CSP page; if you view it as a Web Page, you can view a test page for the KPI (you must hold Developer privileges to do this).

Parameters​

CACHEABLE​

Parameter CACHEABLE As BOOL = 0;

This projection is used to keep track of when KPI classes are compiled or deleted. If true, then results for this KPI can be cached.

ASYNC​

Parameter ASYNC As BOOL = 0;

If true, then this KPI can be executed asychronously.

LABELCONCAT​

Parameter LABELCONCAT As STRING = "/";

For MDX-based KPIs, use this character when concatenating labels for nested rows.

MAXLISTINGROWS​

Parameter MAXLISTINGROWS As INTEGER;

Use this parameter to limit the number of losting rows displayed in pivot tables. This setting is ignored for exports.

XDatas​

KPI​

XData KPI [ XMLNamespace = "http://www.intersystems.com/deepsee/kpi" ]

This XData definition defines the KPI.

Methods​

%IsCacheable​

ClassMethod %IsCacheable() As %String

Return true if this KPI can interact with the cache.

%IsAsync​

ClassMethod %IsAsync() As %Boolean

Return true if this kpi can be computed asynchronously.

%GetMaxListingRows​

ClassMethod %GetMaxListingRows() As %Integer

%Generate​

ClassMethod %Generate() As %Status [ CodeMode = objectgenerator, Final, Internal ]

Process the xml definition for this KPI and generate meta data.

%GetKPIName​

ClassMethod %GetKPIName(pName As %String = "") As %String [ CodeMode = objectgenerator, GenerateAfter = %Generate ]

Return the logical name for this KPI.

%GetKPICaptionName​

ClassMethod %GetKPICaptionName(pName As %String = "") As %String [ CodeMode = objectgenerator, GenerateAfter = %Generate ]

Return the caption as defined in the XML for this KPI.

%OnGetListingSQL​

ClassMethod %OnGetListingSQL(ByRef pFilters As %String, ByRef pSelection As %String, pListingName As %String = "") As %String

This callback, if implemented, returns the text of an SQL query used to provide a "detail listing" for this KPI.
pFilters is an array of current filter values: pFilters(name)=value.
pSelection is an array containing information about the current selected items in the pivot. It contains several values:
pSelection("selectedRange") contains the current selected cells in the pivot as a string in the form "startRow,startCol,endRow,endCol" (1-based). "" if no cells are selected.
pSelection("rowValues") contains a csv-list of "row" values for the selected rows in the pivot (similar to the $$$VALUELIST value used for OpenWindow URLs. This may contain "\," for "," within the data values.
pSelection("sortColumn") is the number of the column to sort on (or 0 for no sort).
pSelection("sortDir") is the sort direction ("ASC" or "DESC").
pListingName is the name of the listing to display. This is reserved for future use.
This method is simply a convenient alternative to the %OnGetListingResultSet method. It takes precedence over the %OnGetListingResultSet method.

%OnGetListingResultSet​

ClassMethod %OnGetListingResultSet(ByRef pFilters As %String, ByRef pSelection As %String, pListingName As %String = "", Output pRS As %SQL.StatementResult) As %Status

This callback, if implemented, can prepare and execute a listing query used to provide a "detail listing" for this KPI. pFilters is an array of current filter values.
pListingName is the name of the listing to display. This is reserved for future use.

%GetListingResultSet​

ClassMethod %GetListingResultSet(ByRef pFilters As %String, ByRef pSelection As %String, pListingName As %String = "", Output pRS As %SQL.StatementResult) As %Status [ Final, Internal ]

This method is used to get the "detail listing" result set for this KPI, if any.
pSelection is an array of values that can be used to control the listings:
pSelection("rowValues") contains a csv-list of selected row values.
pSelection("selectedRange") contains the selected range of cells in the pivot table: startRow,startCol,endRow,endCol (1-based).
pSelection("sortColumn") is the number of the column to sort by (or 0).
pSelection("sortDir") is the direction to sort in, "ASC" or "DESC".

%GetSourceType​

ClassMethod %GetSourceType() As %String [ CodeMode = objectgenerator, GenerateAfter = %Generate ]

Return the sourceType for this KPI

%GetSQLText​

ClassMethod %GetSQLText() As %String [ CodeMode = objectgenerator, Final, GenerateAfter = %Generate ]

Return the default SQL statement for this KPI.

%GetMDXText​

ClassMethod %GetMDXText() As %String [ CodeMode = objectgenerator, Final, GenerateAfter = %Generate ]

Return the default MDX statement for this KPI.

%ApplyDefaults​

Method %ApplyDefaults() [ CodeMode = objectgenerator, GenerateAfter = %Generate, Internal ]

Apply property defaults from the KPI model.

%OnLoadModel​

Method %OnLoadModel(pSource As %RegisteredObject) As %Status [ Final ]

This callback method does the actual work of loading values from the source object.

%QueueKPI​

Method %QueueKPI() As %Status [ Final, Internal ]

Add a request to compute this KPI to the background agent queue.

%ComputeKPI​

ClassMethod %ComputeKPI(pCacheKey As %String) As %Status [ Final, Internal ]

This is called by a task master background agent that wants to compute the value of this KPI.

%ValidateKPICache​

Method %ValidateKPICache(pSourceType As %String, pQueryText As %String = "") As %Status [ Final ]

Test if the data cached for this KPI is up-to-date. If not, clear the cached data.

%TestKPICache​

Method %TestKPICache(Output pIsCached As %Boolean, pSourceType As %String, pQueryText As %String = "") As %Status [ Final ]

Test if this KPI has cached data.

%ComputeKPICacheKey​

Method %ComputeKPICacheKey(pSourceType As %String, pQueryText As %String = "") As %Status [ Final ]

Compute the kpi cache key for the current KPI result. Place the result in %cacheKey.

%OnKPICleanup​

Method %OnKPICleanup() As %Status [ Internal ]

Runs after the KPI loads and runs

%OnComputeKPICacheKey​

Method %OnComputeKPICacheKey(Output pCacheKey As %String, pQueryText As %String = "") As %Status [ Internal ]

Compute the kpi cache timestamp for the current KPI result. Overridden by subclasses.

%ComputeKPITimestamp​

Method %ComputeKPITimestamp(Output pTimestamp As %String, pSourceType As %String, pQueryText As %String = "") As %String [ Final ]

Compute the kpi cache timestamp for the current KPI result.

%OnComputeKPITimestamp​

Method %OnComputeKPITimestamp(ByRef pTimestamp As %String, pSourceType As %String, pQueryText As %String = "") As %Status

Compute and return the KPI cache timestamp for the current KPI result. Typically this is the timestamp of the cube this KPI depends on.

%LoadKPIFromCache​

Method %LoadKPIFromCache() As %Status [ Final ]

Load this KPI from cached data.

%OnLoadKPIFromCache​

Method %OnLoadKPIFromCache() As %Status

Notification that we are loading this KPI from cached data.

%SetPercentComplete​

Method %SetPercentComplete(pPctComplete As %Integer, pErrorCode As %Status = "") As %Status [ Final ]

For a KPI running in the background, set the percentage complete.

%SaveKPIToCache​

Method %SaveKPIToCache(pSourceType As %String, pQueryText As %String = "") As %Status [ Final ]

Save this KPI to the KPI cache.

%OnSaveKPIToCache​

Method %OnSaveKPIToCache() As %Status

Notification that we are saving this KPI to the cache.

%GetKPIPropertyInfo​

ClassMethod %GetKPIPropertyInfo(Output pList As %String, pModelId As %String = "") As %Status [ CodeMode = objectgenerator, Final, GenerateAfter = %Generate, Internal ]

Return information on properties defined in the KPI block. This takes the form:
pList(n) = name
pList(n,"defaultValue") = value
pList(n,"columnNo") = #

%OnGetKPIPropertyInfo​

ClassMethod %OnGetKPIPropertyInfo(ByRef pList As %String, pPropNo As %Integer, pModelId As %String = "") As %Status

Add additional properties beyond those defined in the KPI block. This takes the form:
pList(n) = name
pList(n,"defaultValue") = value
pList(n,"columnNo") = #
pPropNo is the number of next open slot in the list.

%GetMDX​

Method %GetMDX(Output pMDX As %String) As %Status [ Final, Internal ]

Return an MDX statement to provide the KPI data.

%OnGetMDX​

Method %OnGetMDX(ByRef pMDX As %String) As %Status

This callback, if implemented, lets a subclass provide an MDX statement to fetch data for this KPI. If there are filter values, they will be within the %filterValues property (an object).

%GetMDXContextFilter​

Method %GetMDXContextFilter() As %String

Return a series of %FILTER clauses (as a single string) based on the "%CONTEXT" of the %KPI or %MDX function that invoked this KPI. This behavior is automatic; you can override this method and return "" if you do not want this to happen.

%ExecuteMDX​

Method %ExecuteMDX(pMDX As %String) As %Status [ Final, Internal ]

Execute an MDX statement and use the results to provide the KPI data.

%GetSQL​

Method %GetSQL(Output pSQL As %String) As %Status [ Final, Internal ]

Return an SQL statement to provide the KPI data.

%GetListingSQL​

Method %GetListingSQL(Output pSQL As %String, ByRef pFilters, ByRef pSelection, pListingName) As %Status [ Final, Internal ]

Return an SQL statement to provide the KPI's listing data.

%OnGetSQL​

Method %OnGetSQL(ByRef pSQL As %String) As %Status

This callback, if implemented, lets a subclass provide an SQL statement to fetch data for this KPI. If there are filter values, they will be within the %filterValues property (an object).

%ExecuteSQL​

Method %ExecuteSQL(pSQL As %String) As %Status [ Final, Internal ]

Execute an SQL statement and use the results to provide the KPI data.

%OnExecute​

Method %OnExecute() As %Status

Get data for this KPI manually. This is implemented by subclasses that provide manual data.

%GetFilterList​

ClassMethod %GetFilterList(Output pFilters As %List, pDataSourceName As %String = "") As %Status [ CodeMode = objectgenerator, Final, GenerateAfter = %Generate, Internal ]

Return list of possible filters for this KPI. This drives the list of filter selections for widget connected to this KPI. This takes the form:
pFilters(n)=$LB(name,caption,filterProperty,multiSelect,dependsOn,searchType)

%OnGetFilterList​

ClassMethod %OnGetFilterList(Output pFilters As %List, pDataSourceName As %String = "") As %Status

Callback to get additional possible filters for this KPI. This drives the list of filter selections for widget connected to this KPI. This takes the form:
pFilters($I(pFilters))=$LB(name,caption,value,multiSelect)

%GetFilterMembers​

ClassMethod %GetFilterMembers(pFilter As %String, Output pMembers As %List, Output pDefaultValue As %String, pSearchKey As %String = "", pDataSourceName As %String = "", ByRef pFilterValues As %String) As %Status [ CodeMode = objectgenerator, Final, GenerateAfter = %Generate, Internal ]

Return a list of possible filter values for a given filter. This takes the form:
pMembers(n)=$LB(text,value)

%GetActionList​

ClassMethod %GetActionList(ByRef pActions As %List, pDataSourceName As %String = "") As %Status [ CodeMode = objectgenerator, Final, GenerateAfter = %Generate, Internal ]

Return list of possible actions for this KPI. This drives the list of action selections for widget connected to this KPI. This takes the form:
pActions(n)=$LB(name,caption)

%InvokeDashboardAction​

ClassMethod %InvokeDashboardAction(pAction As %String, pContext As %ZEN.proxyObject, pDataSourceName As %String = "") As %Status [ CodeMode = objectgenerator, Final, GenerateAfter = %Generate, Internal ]

Internal method that gets invoked from a client dashboard and dispatches to a user callback.

%GetMembersForFilter​

ClassMethod %GetMembersForFilter(pCube As %String, pFilterSpec As %String, Output pMembers, pSearchKey As %String = "") As %Status

Convenience method. For a given DeepSee cube and filter spec, return a list of members in the form:
pMembers(n)=$LB(text,value)
This list contains both the display names (text) of the filter items and the logical names (value).
pCube is the logical name of the cube with .cube appended, for example: "holefoods.cube"
pFilterSpec is the COMPLETE name of a level within the cube:
"[DateOfSale].[Actual].[YearSold]"
pSearchKey is any search text entered by the user.

%GetSQLForFilter​

Method %GetSQLForFilter(pFieldName As %String, pFilterName As %String) As %String

Given a filter name, pFilterName, and an SQL field name, pFieldName, return an SQL expression based on the filter value(s) that can be used within an SQL WHERE clause. Returns "" if there is no filter value.
For example: if you have a SQL-based KPI class based on a table with a YearSold field, you can get an SQL expression for it:
Set tYearExpr = ..%GetSQLForFilter("YearSold","Year")
If tYearExpr is not "", then you can add it to your SQL WHERE clause to add the filtering:
Set tSQL = tSQL _ " WHERE " _ tYearExpr
or if your query already has a WHERE clause:
Set tSQL = tSQL _ " AND " _ tYearExpr

%GetMDXForFilter​

Method %GetMDXForFilter(pLevelSpec As %String, pFilterName As %String) As %String

Given a filter name, pFilterName, and a level specification, pLevelSpec, return an MDX expression based on the filter value(s) that can be used within an MDX WHERE or %FILTER clause.
Returns "" if there is no filter value.
For example: if you have a MDX-based KPI class with a YearSold level within a DateOfSale dimension and a filter named Year, you can get an MDX filter expression for it:
Set tYearFilter = ..%GetMDXForFilter("[DateOfSale].[YearSold]","Year")
If tYearFilter is not "", then you can add it to your MDX query to add the filtering:
Set tMDX = tMDX _ " %FILTER " _ tYearFilter

%SplitList​

ClassMethod %SplitList(pValue As %String, Output pList) As %Integer [ Internal ]

Given a value, test if it has multiple values and return a list of them. For example, "Apple" returns "Apple" and a count of 1. "{[2001],[2002]}" returns "[2001]","[2002]", and count of 2. This method assumes that enclosing {} have already been removed.
Return number of items in the value.