Defining Business Metrics

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:

generated description: busmetric 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:

generated description: busmetric instances

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:

generated description: busmetric instances history 1

Then, when a user selects an instance:

generated description: busmetric instances history 2

Business Metrics as Business Services

All business metric classes are derived from the class Ens.BusinessMetricOpens in a new tab, which is itself derived from the Ens.BusinessServiceOpens in a new tab 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:

It must be a subclass of Ens.BusinessMetricOpens in a new tab.
For this class, the ADAPTER parameter is Ens.InboundAdapterOpens in a new tab, which provides the CallInterval setting. This ensures that the business metric is invoked periodically.
It must define one or more business metric properties. The details are different for simple properties and properties with autohistory.
It can optionally specify values for property parameters, for example, to control the range of values.
It must assign values to the business metric properties. To do so, it must implement the OnCalculateMetrics() method.

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.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 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:

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, Ensemble 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).

Defining a Multi-instance Business Metric

To define a multi-instance business metric:

Follow the instructions in the previous section, except that the details are slightly different for implementing OnCalculateMetrics().
Define the instance names. To do so, you can:
- Define a static set of instance names. To do so, implement the OnGetInstances() method to assign a fixed list of names to an array. This approach is useful if the set of instances is static.
- Define the instance names dynamically. To do so, add a MetricInstances() query to get a list of names from a column in an SQL database. This approach is useful if you expect the number or names of the items to change over time.
- Combine these approaches. Use the MetricInstances() query to get an initial list and then use OnGetInstances() to add or replace names. (The business metric instance calls MetricInstances() first and then calls OnGetInstances().)
In your implementation of OnCalculateMetrics(), check the value of the %Instance property and assign values to the business metric properties as appropriate for that instance.
Keep the following principles in mind:
- The instance names are strings.
- The instance names must be unique.
- The instance names may be displayed to users on a dashboard, so use names that are concise, informative, and appropriate.
- Try to keep the number of instances reasonable. Thousands of instances could be expensive to compute and difficult for users to understand.

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:

The query must be named MetricInstances().
It must take no arguments.
The query must contain an SQL SELECT statement.
The first column returned by the query returns the instance names.

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:

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.)
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:

Add them to the appropriate production, in the same way that you would add any other business service.
Configure the Call Interval setting as needed for each business metric.
Create dashboards and add business metrics to them. For information, see Configuring Ensemble.
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.BusinessMetricOpens in a new tab.

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 %StatusOpens in a new tab 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:

BusinessMetric is the configured name of the business metric class.
Instance is an instance number. Instances are numbered in the order in which they are defined.
Property is the name of the business metric property.