Reference Information for KPI and Plugin Classes
This appendix contains reference information for KPI and plugin classes. It discusses the following topics:
You must recompile a KPI class after making any change.
Basic Requirements
To define a KPI, create a class that meets the following requirements:
-
It must extend %DeepSee.KPIOpens in a new tab.
-
It must contain an XData block named KPI
-
For this XData block, XMLNamespace must be specified as follows:
XMLNamespace = "http://www.intersystems.com/kpi"
-
The root element within the XData block must be <KPI> and this element must follow the requirements described in this appendix.
-
The class can define several class parameters. See “Class Parameters for the KPI Class,” earlier in this book.
The requirements for a plugin are the same, with the following exceptions:
-
The class must extend %DeepSee.KPIPlugInOpens in a new tab rather than %DeepSee.KPIOpens in a new tab.
-
The class can define the PLUGINTYPE class parameter; see “Defining Plugins.”
Common Attributes in a KPI or Plugin
Most of the elements in a KPI or plugin have the following attributes, which are listed here for brevity:
Attribute | Purpose |
---|---|
name | Logical name of the element. |
displayName | (Optional) Localized name of this element for use in user interfaces. If you do not specify this attribute, DeepSee instead uses the value specified by the name attribute. For details, see the chapter “Performing Localization” in the DeepSee Implementation Guide. |
description | (Optional) Description of this element. |
disabled | (Optional) Controls whether the compiler uses this element. If this attribute is "true" then the compiler ignores it. By default, this attribute is "false" |
<kpi>
The <kpi> element is the root element in the XData block in a KPI or plugin class. This element contains the following items:
Attribute or Element | Purpose |
---|---|
name, displayName, description, disabled | See “Common Attributes in a KPI,” earlier in this appendix. |
caption | Not used. |
sourceType, mdx, sql | See “Specifying the Query for the KPI.” |
rangeLower, rangeUpper, thresholdLower, thresholdUpper | See “Specifying Ranges and Thresholds for Speedometers.” |
actionClass | (Optional) Specifies an associated KPI class that defines actions that are available to this KPI, in addition to the actions defined within this KPI. Specify the full package and class name of another KPI. |
<property> | (Optional) You can include zero or more <property> elements, each of which corresponds to a column of the query that the KPI uses. You cannot display the query results unless you specify <property> elements. |
<action> | (Optional) You can include zero or more <action> elements, each of which is available for use when you create a scorecard based on this KPI. |
<filter> | (Optional) You can include zero or more <filter> elements, each of which is available for use when you create a scorecard based on this KPI. |
<property>
Within <kpi>, a <property> element contains the following attributes:
Attribute | Purpose |
---|---|
name, displayName, description, disabled |
See “Common Attributes in a KPI,” earlier in this appendix.Note that the name or displayName of a KPI property is used as the default caption in any meter widget that displays this property; it is convenient to specify a name that is suitable for that use. |
columnNo | Number of the column in the query that contains the data for this property. The first data column is 1. |
format | (Optional) Default numeric format for this property, when this KPI is displayed in a pivot table widget. For example: format="##.###" |
style | (Optional) CSSOpens in a new tab style to apply to the cells that display this property, when this KPI is displayed in a pivot table widget. For example: style="color:red" |
headerStyle | (Optional) CSS style to apply to the corresponding header cells, when this KPI is displayed in a pivot table widget. For example: style="color:red;font-style:italic" |
defaultValue | Not used. |
Note that the KPI test page ignores the format, style, and headerStyle attributes. These attributes affect only pivot table widgets.
<filter>
Within <kpi>, a <filter> element contains the following attributes:
Attribute | Purpose |
---|---|
name, displayName, description, disabled | See “Common Attributes in a KPI,” earlier in this appendix. |
filterProperty | Logical name of the <property> element that this filter controls. This option is for use when retrieving the filter values programmatically. |
defaultValue | (Optional) Default value for this filter. Note that you can also specify a default value for the filter when you include the KPI in a scorecard; that default value takes precedence over the defaultValue attribute of the <filter> element. |
sql, valueList, displayList | See “Defining KPI Filters.” |
searchType | (Optional) Specifies the kind of control to use when displaying this filter in a widget. The default control is a drop-down list. To display a calendar instead, specify this attribute as "day" |
dependsOn | (Optional) Specifies the name of another filter on which this filter depends. For example, if your KPI has filters named State and City, you might include dependsOn="State" in the definition of the City filter. |
<action>
Within <kpi>, an <action> element contains the following attributes:
Attribute | Purpose |
---|---|
name, displayName, description, disabled |
See “Common Attributes in a KPI” earlier in this appendix. The name attribute cannot be any of the following (not case-sensitive): applyFilter, setFilter, refresh, showListing, viewDashboard, navigate, newWindow, rowCount, rowSort, colCount, colSort. |
Note that the <action> element does not define the actions themselves, which you define within the %OnDashboardAction() callback method of the class; see the chapter “Defining the Available Actions” in the DeepSee Implementation Guide.
The <action> element is necessary to notify the Dashboard Designer which actions are defined in a KPI or plugin, so that you can select them for use.