Defining keys

The key that uniquely identifies a monitoring context instance is based on the piece or pieces of information that characterize what you want to monitor. For example, if the monitoring context represents an order handling process, its key might correspond to the order ID. Each monitoring context must have at least one key.

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 > Key.
2. In the Create New Key window, type a name into the Name field and click OK. 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 key from the list of available types.

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

3. In the form editor, specify the details of the key 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. Optional: 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. Optional: If this key is a source for a dimension level, select A value is required for this key 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 operators or functions. For keys 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('P2DT5H30M0.000S'), which would represent a default value of 2 days, 5 hours, and 30 minutes. The default value must be a literal expression. Valid operators, such as add (+) and subtract (-), and functions such as abs() and string(), can be used in defining it.
   6. Optional: If you want the key to be indexed in the database so that it can be used for sorting in Instances in the dashboards, select This key can be used for sorting. In the XML document, this option corresponds to the isSortable attribute of the key.
4. To add a key value expression to the table, click Add or double-click a row. Each key must either have a default value assigned or have a key value expression to set the value of the key at run time.
5. For each key value expression, 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.

   Each expression must reference one or more attributes of a single inbound event that is capable of creating an instance of the monitoring context when it arrives; that is, the inbound event must have "If no instances are found" set to "Create new instance."

   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 attributes from any creation inbound events. You must cast the value to the appropriate type, either by selecting the Function from content assist before specifying the value or by typing the function yourself. See "Expression support" for supported expressions, and see your event schema definition for a list of valid attributes.

   Tip: If you are using an Oracle database, avoid empty strings because they generate runtime errors.