Developing Ensemble Productions
Defining Business Metrics
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

An Ensemble business metric measures or calculates one or more values, typically related to the performance of a production, for display in dashboards or in the Production Monitor. This chapter describes how to create and display business metrics. It contains the following sections:

Note:
As an alternative, you can use third-party business activity monitoring products with Ensemble. These products can interoperate with Ensemble via any of its connectivity technologies, including web services, JDBC, ODBC, and more.
Introduction to Ensemble Business Metrics
A business metric is a specialized business service class that you include in a production. While the production is running, the business metric values are available for display; when it is not running, the values are null.
Business Metric Properties
The values in a business metric are called properties. There are two general kinds of business metric properties: simple properties and multidimensional properties with autohistory.
A simple property holds only one value at any time. The following example displays a business metric with two simple properties:
A property with autohistory holds multiple values, one value for each point in time, with the most recent value at the end. You can control the number of times when the value is recorded. The following example displays a business metric with two properties that have autohistory:
As a developer of business metric classes, you are free to provide values for metric properties in any manner you choose: such values can be based on data stored within Ensemble messages or business process instances, data maintained within Ensemble by business processes, or data obtained by sending requests to external applications or databases.
Single- and Multi-instance Business Metrics
Also, there are two general kinds of business metrics: single-instance and multi-instance business metrics.
A single-instance business metric holds a single set of metric values. The examples in the previous section showed single-instance business metrics.
A multi-instance business metric holds multiple sets of metric values, one set for each instance defined by the metric. Multi-instance business metrics are useful when you have a number of similar items whose metrics you want to compare. Each item is distinct, but has properties in common with the others. For example, each department might have a count of unassigned workflow tasks and a count of assigned workflow tasks. A business metric can have one instance for each department. The following shows an example multi-instance business metric that has two simple properties:
A multi-instance business metric can also have multidimensional properties with autohistory. In practice, however, it is not possible to simultaneously display the instances and the history. If you define such a business metric, then when you add it to the dashboard, the dashboard displays the current values for all instances by default. You can include a filter so that the user can select a single instance; in that case, the dashboard can display the history for that instance.
For example:
Then, when a user selects an instance:
Business Metrics as Business Services
All business metric classes are derived from the class Ens.BusinessMetric, which is itself derived from the Ens.BusinessService class so that it has the full functionality of a business service. For example, you can add a business metric to a production definition, you can assign a logical name to a business metric, you can schedule it for periodic execution (to recalculate its metric properties at a given interval), and you can invoke business operations and business processes as part of the metric value calculation.
Defining a Single-instance Business Metric
To define a single-instance business metric, define a class that meets the following requirements:
The following subsections provide the details.
Studio provides a wizard that you can use to create a stub class. To access this wizard, click File and then click New. Select the Production tab. Select the Business Metric icon and click OK.
Also see Defining a Multi-instance Business Metric,” later in this chapter.
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.Metric (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 Ensemble 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 chapter.
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:
Defining a Multi-instance Business Metric
To define a multi-instance business metric:
The following subsections provide the details.
Defining a Static Set of Instance Names
To define a static set of instance names, override the OnGetInstances() method. This method is passed an array by reference. The OnGetInstances() method must fill this array with names using an ordinal number as a subscript, starting with 1. A simple example follows:
/// Return an array of metric instances
ClassMethod OnGetInstances(ByRef pInstSet As %String) As %Status
{
  Set pInstSet(1) = "Apple"
  Set pInstSet(2) = "Banana"
  Set pInstSet(3) = "Cherry"
  Quit $$$OK
}
Defining the Instance Names Dynamically
To define the set of instance names dynamically, add a query to the business metric class as follows:
For example:
/// Return current list of product names
Query MetricInstances() As %SQLQuery
{
  SELECT ProductName FROM MyApplication.Product
}
Assigning Values to Properties in a Multi-instance Metric
To assign values to properties in a multi-instance business metric, implement the OnCalculateMetrics() method. In your implementation, set the values as appropriate for each instance. To do so:
  1. Check the value of the %Instance property. This property equals the name of one of the business metric instances.
    (Ensemble automatically processes one instance at a time, sequentially. For each instance, Ensemble executes the OnCalculateMetrics() instance method.)
  2. Set the values of the business metric properties as needed for that instance.
The following shows an example:
Method OnCalculateMetrics() As %Status
{
  // get product name
  Set product = ..%Instance


  // find recent sales using SQL
  &SQL(SELECT SUM(Sales) INTO :sales
              FROM MyApplication.Product
              WHERE ProductName = :product)

  // update sales metric
  Set ..Sales = sales
  Quit $$$OK
}
This example uses the current instance name (%Instance) in an SQL query to retrieve the most recent sales data for that instance, then writes this data to the Sales property of the current instance of the class.
Note:
You can also use the %Instance property elsewhere in the class when you want to substitute the current instance name.
Other Options in Business Metrics
This section describes other options within business metric classes.
Defining Actions for Use in Dashboards
A business metric class can define actions, which you can expose as user options in dashboards. An action can perform a combination of client-side activities (such as filtering and refreshing the dashboard) and server-side activities (such as invoking your own APIs). The action mechanism is quite general.
To define actions, implement the %OnGetActionList() and %OnDashboardAction() methods of the business metric class. For information on these methods, see the chapter Defining Custom Actions in the DeepSee Implementation Guide.
Implementing OnInit()
You can also override the OnInit() callback of the business metric class, to initialize any properties, for example. If you do so, you must ensure that it explicitly calls the OnInit() method provided by its superclass BusinessMetric, as shown below. If not, the corresponding dashboard element does not display properly:
Method OnInit() As %Status
{
    // . . .

    // invoke superclass implementation
    Quit ##super()
}
Adding Business Metrics to Dashboards
To add business metrics to dashboards, do the following:
  1. Add them to the appropriate production, in the same way that you would add any other business service.
  2. Configure the Call Interval setting as needed for each business metric.
  3. Create dashboards and add business metrics to them. For information, see Configuring Ensemble.
  4. Optionally extend the Production Monitor page to show information from your business metrics. See the next section.
Adding Business Metrics to the Production Monitor
In addition to displaying business metrics in dashboards, you can extend the Production Monitor page to show information from your business metric classes. To do so, set nodes in the ^Ens.Monitor.Settings global in your namespace, as follows:
Node Value
^Ens.Monitor.Settings("MetricClasses",n,"Metric") Configuration name of the business metric, for the nth business metric. The Production Monitor page lists the business metrics in the order specified by n.
^Ens.Monitor.Settings("MetricClasses",n,"Title") Display name for this business metric. The default is the configuration name of the business metric
^Ens.Monitor.Settings("MetricClasses",n,"Instance") Instance name of this business metric. If the metric does not have instances, omit this. If the metric does have instances and you omit this, Ensemble uses the first instance, considering the order in which instances are defined.
For example, do the following in the Terminal:
 Set ^Ens.Monitor.Settings("MetricClasses",1,"Metric") = "MetricConfigName"
 Set ^Ens.Monitor.Settings("MetricClasses",1,"Title") = "Title for Display"
 Set ^Ens.Monitor.Settings("MetricClasses",1,"Instance") = "MetricInstanceName"
For each business metric that you add, the Production Monitor page indicates when it last updated the metric information, if there is any data for the given metric or instance, and whether or not the given metric is currently running.
For information on using the Production Monitor page, see Monitoring a Production in Monitoring Ensemble.
Setting and Getting Values Programmatically
In some cases, you might need programmatic access to metric properties. For example, you might want a business process to directly read or set a metric property. To do this, use the GetMetric() and SetMetric() class methods of Ens.BusinessMetric.
Using the GetMetric() Method
The GetMetric() class method reads the current value of a specified metric property from the business metric cache. Call this method as follows:
  Set value = ##class(Ens.BusinessMetric).GetMetric(metric,property)
Where metric is the name of the business metric (the configuration name, not the class name) and property is the name of the metric property. If GetMetric() is unable to read the specified value, it returns an empty string.
To read values from multidimensional metric properties, there is a third, optional parameter that specifies which subnode of the property to read. For example:
  Set value(1) = ##class(Ens.BusinessMetric).GetMetric(metric,property,1)
Using the SetMetric() Method
The SetMetric() class method sets the value of a specified metric property within the business metric cache. Call this method as follows:
  Set tSC = ##class(Ens.BusinessMetric).SetMetric(metric,property,value)
Where metric is the name of the business metric (the configuration name, not the class name), property is the name of the metric property, and value is the value to which the metric property should be set.
SetMetric() returns a %Status code indicating success or failure. It is possible that SetMetric() is unable to acquire a lock for the business metric and may fail for that reason.
To set all the values of a multidimensional metric property, create the array of values and then pass the array by reference. For example:
  For i=1:1:20 {
    Set data(i) = i*i
  }
  Set tSC = ##class(Ens.BusinessMetric).SetMetric("MyMetric","MyGraph",.data)
About the Business Metric Cache
So that Ensemble can retrieve metric values as efficiently as possible, it stores these values in a cache. This cache is the global ^Ens.Metrics, which has the following structure:
 ^Ens.Metrics(BusinessMetric,Instance,Property) = value
Where: