IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Developing monitor models > Create monitor models > Defining monitor details models

Defining metrics

A metric is a holder for information in a monitoring context. Metrics are associated with one or more metric value expressions that, when evaluated, give the metric a value. Examples of metrics are the working duration of a process and a supplier's response time.

To define a metric:


Procedure

  1. Click the Monitor Details Model tab of the editor, right-click the monitoring context (or any element of the monitoring context) in the model tree, and click New > Metric.

  2. In the Create New Metric window, type a name into the Name field. The name is limited to 256 characters. As you type the name, a default ID is created for you, although you can change it if you prefer. The ID is required and must be unique within the monitoring context. The ID must be an XML NCName (non-colonized name), which means that it must start with a letter or underscore and that it can contain only letters, digits, underscores, hyphens, and periods. Select the type of the metric from the list of available types, and click OK.

    Tip: Keep the name of the metric short so that it can be used as part of the name of a KPI.

    The metric is added to the model tree under the monitoring context, and the form editor opens so that you can define the metric.

  3. In the form editor, specify the details of the metric as follows:

    1. Optional: Type a description in the Description field. The description is used only in the Monitor Model editor and is not displayed anywhere in Business Monitor. The character set is unrestricted.

    2. Optional: Type the maximum string length in the Maximum string length field. This option is available only if the type is String. The default value is 256, and you can enter any value greater than 0. The maximum string length is added as a constraint in the database.

    3. If the type is String and the string will be translated into other languages, select Allocate additional space in database to accommodate Unicode string for globalization. This option is available only if the type is String.

    4. If this metric is a source for a dimension level, select A value is required for this metric and also specify a default value. Requiring a value ensures that every instance falls into a specific dimension level when you look at dimensions or reports in the dashboards. It also ensures that database sorts can be performed efficiently.

    5. Optional: To specify a default value, type a number or a function into the box, or click Edit to enter an expression. If you press Ctrl+Space for content assist, a small window is displayed to help you write the expression. In this window, you can select valid operators or functions. For metrics with a type other than string, integer, or decimal, you must cast the default value to the appropriate type using a constructor function.

      You can select the function from content assist before specifying the value or type the function yourself.

      For example, if the type is Duration, a valid default value would be: duration('P0Y0M1DT0H0M0.000S'), which would represent a default value of 1 day.

      If you are using an Oracle database, do not set the default value for a required metric to "" (the empty string). If a required metric evaluates to the empty string, an attempt is made to store a null value in a database column, which results in an error at run time. Use '~' or 'None' instead of the empty string.

    6. If you want the metric to be indexed in the database so that it can be used for sorting in Instances in the dashboards, select This metric can be used for sorting. (In the XML document, this option corresponds to the isSortable attribute of the metric.)

      Selecting the A value is required for this metric check box will ensure that database sorts can be performed efficiently.

    7. To specify that this metric not be shown on the dashboard, select Hide from dashboards.

  4. To add a metric value expression to the table, click Add or double-click a row. Each metric must have either a default value assigned or have a metric value expression to set the value of the metric at run time. The expression is evaluated based on the following occurrences:

    • A trigger fires. If you provide an explicit trigger, the metric value expression is evaluated only when the trigger fires.

    • An inbound event that is referenced in the metric value expression arrives. If a metric value expression references an inbound event, the expression is evaluated only when that inbound event arrives. A metric value expression can reference at most one inbound event.

    • A metric or counter that is referenced in the metric value expression is updated. If the metric value expression has no trigger and does not refer to an inbound event, the expression is evaluated when a metric or counter that is referenced in the expression is updated (even if the update does not result in a new value).

    1. To provide an explicit trigger, click the Trigger cell and click the button that is displayed to open the Select a Trigger window. Select a trigger that you have previously created.

    2. Click the Expression cell and add an expression. You can either type directly into the cell, or, for a large expression, click the button that is displayed to open a resizable window. If you press Ctrl+Space for content assist, a small window is displayed to help you write the expression. In this window, you can select valid operators, functions, and the following elements within your model:

      • Inbound event attributes.
      • Metrics, counters, and stopwatches in the same monitoring context.
      • Metrics, counters, and stopwatches in child contexts and down, but only if the metric value expression is executed because of a trigger firing in the child context.

      To cast literals or sub-expressions to the appropriate data type, you can choose a constructor function from content assist before specifying its argument, or you can type the function yourself.

      For example, if you are defining a date metric (perhaps for defining a time period for a KPI), you might use content assist to select Functions > date() and then My Monitor Model > My Monitoring Context > My Inbound Event > Predefined Data > creationTime. See "Expression support" for supported expressions, and see your event schema definition for a list of valid attributes.

      If you are using an Oracle database and a required metric evaluates to the empty string, an attempt is made to store a null value in a database column, which results in an error at run time. The following example shows a metric value expression that can be used to ensure that the empty string is not used to set the value of a metric: 

      (if (fn:exists(Inbound_Event/extendedData/Name) and Inbound_Event/extendedData/Name != "") then Inbound_Event/extendedData/Name else 'None')
      The fn:exists function makes sure that the extended data element Name exists. Then the Name element is compared to the empty string. If the Name element exists and is not equal to the empty string, the value of the Name element is used to set the metric. If the value of the Name element is the empty string, the metric value is set to the string None.
    3. Continue adding metric value expressions, either by clicking Add or by double-clicking a row in the table, until you have specified all the ways in which the value of the metric can be assigned.

Defining monitor details models