To define a single-instance business metric, define a class that meets the following requirements:
The following subsections provide the details.
Defining Simple Business Metric Properties
To define a simple business metric property, add a property to the business metric class as follows:
Property MetricProperty As Ens.DataType.Metric;
This property can hold either numeric or string values.
Where MetricProperty is the name of the business metric property. For example:
/// This metric tracks A/R totals
Property AccountsReceivable As Ens.DataType.Metric;
This property can hold either numeric or string values.
Defining Business Metric Properties with Autohistory
To define a business metric property with autohistory, add a property to the business metric class as follows:
Property MetricProperty As Ens.DataType.Metric (AUTOHISTORY=50) [MultiDimensional];
For the AUTOHISTORY parameter, you can use any positive integer. For example:
/// Recent Sales History
Property SalesHistory As Ens.DataType.Metric (AUTOHISTORY = 50) [ MultiDimensional ];
Generally, the purpose of this kind of property is to collect values at intervals, over time, so that the resulting series of numbers can be plotted on a chart. For this reason, the assigned values are typically numeric.
The rate of collection is controlled by the Call Interval setting of the configured business metric.
Specifying Other Parameters for Metric Properties
You can specify additional property parameters for the business metric properties. These parameters might include default values for the upper and lower limits that control the appearance of any meter that displays that metric. For example:
/// Total Sales for the current day.
Property TotalSales As Ens.DataType.Metric (RANGELOWER = 0, RANGEUPPER = 50, UNITS = "$US");
The following table lists the property parameters that you can use with Ens.DataType.MetricOpens in a new tab (in addition to AUTOHISTORY, which is discussed in the previous section). These parameters apply to metric properties that hold numeric values; none of them apply when the metric property holds a string value.
Parameter |
Description |
LINK |
Optional. A URL specifying a browser page related to this metric. If a dashboard user right-clicks on the associated meter and selects the Drill Down option, the browser will show this page. |
RANGELOWER |
Optional. A numeric value specifying the expected lower range for values of this metric. This value provides a default for the low range of any meters connected to this metric. |
RANGEUPPER |
Optional. A numeric value specifying the expected upper range for values of this metric. This value provides a default for the upper range of any meters connected to this metric. |
THRESHOLDLOWER |
Optional. A numeric value specifying the expected lower threshold value for this metric. This value provides a default for the lower threshold of any meters connected to this metric. |
THRESHOLDUPPER |
Optional. A numeric value specifying the expected upper threshold value for this metric. This value provides a default for the upper threshold of any meters connected to this metric. |
UNITS |
Optional. A user-defined string enclosed in double quotes that specifies the units for this metric. Examples include "$US" or "Liters". This string appears in the bottom half of the dashboard display when the viewer clicks on the corresponding meter in the top half of the display. |
Assigning Values to Business Metric Properties
This section describes how to assign values to business metric properties for single-instance business metrics; the details for multi-instance business metrics are discussed later in this page.
To assign values to business metric properties, implement the OnCalculateMetrics() instance method of the business metric class. The purpose of OnCalculateMetrics() is to calculate, look up, or otherwise set a value for any metric properties in the class.
The following example defines two metric properties, Counter and SalesHistory. In this example, the OnCalculateMetrics() method simply increments the single-valued Counter property and updates the SalesHistory property to random value:
/// Example Business Metric class
Class MyProduction.MyMetric Extends Ens.BusinessMetric
{
/// Number of times these metrics have been calculated.
Property Counter As Ens.DataType.Metric
(RANGELOWER = 0, RANGEUPPER = 100000, UNITS = "Events");
/// Total Sales for the current day.
Property SalesHistory As Ens.DataType.Metric
(RANGELOWER = 0, RANGEUPPER = 50, AUTOHISTORY = 50, UNITS = "$US")
[ MultiDimensional ];
/// Calculate and update the set of metrics for this class
Method OnCalculateMetrics() As %Status
{
// set the values of our metrics
Set ..Counter = ..Counter + 1
Set ..SalesHistory = $GET(..SalesHistory) + $RANDOM(10) - 5
Quit $$$OK
}
}
Notes:
-
Notice that you specify the value for a property in the same way for simple properties and for properties with autohistory.
(If you are familiar with multidimensional properties, note that you specify the value only for the unsubscripted top node of the property, as shown here. Because of the AUTOHISTORY parameter, InterSystems IRIS generates code that automatically maintains the lower nodes in the array, which is an integer-subscripted array. For example, SalesHistory(1) is the oldest value in the SalesHistory property.)
-
In this method, you can optionally invoke business operations and business processes. You can also invoke any APIs needed to compute the values.
-
Never allow a property with autohistory to contain a null value. The null values are not displayed, causing bar charts and line charts to contain the wrong number of bars or entries. This can result in a mismatch between the axis labels and the items that they label. To prevent such problems, replace any null values with zero.
-
Before the OnCalculateMetrics() method is called, all metric properties are set to their last calculated value (if any). After the OnCalculateMetrics() is called, the values of all the metric properties are stored in the business metric cache for subsequent use by dashboards or other interested parties (if any).