Defining Business Metrics

Copy link to this sectionBusiness 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.

Copy link to this sectionSingle- 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:

Copy link to this sectionBusiness 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.

Copy link to this sectionDefining 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;

Copy code to clipboard

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;

Copy code to clipboard

This property can hold either numeric or string values.

Copy link to this sectionDefining 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];

Copy code to clipboard

For the AUTOHISTORY parameter, you can use any positive integer. For example:

/// Recent Sales History
Property SalesHistory As Ens.DataType.Metric (AUTOHISTORY = 50) [ MultiDimensional ];

Copy code to clipboard

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.

Copy link to this sectionSpecifying 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");

Copy code to clipboard

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.

Copy link to this sectionAssigning 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
}

}

Copy code to clipboard

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

Copy link to this sectionDefining 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
}

Copy code to clipboard

Copy link to this sectionDefining 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
}

Copy code to clipboard

Copy link to this sectionAssigning 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
}

Copy code to clipboard

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.

Copy link to this sectionDefining 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.

Copy link to this sectionImplementing 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()
}

Copy code to clipboard

Copy link to this sectionUsing 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)

Copy code to clipboard

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)

Copy code to clipboard

Copy link to this sectionUsing 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)

Copy code to clipboard

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)

Copy code to clipboard