CATSWeb Manager User Guide - Managing Measurements

Managing Measurements

Contents

Introduction
Settings for Measurements
Measurement Ranges
Measurement Alerts
Displaying Measurement Data (via Measurement Summary Display Parts)
Purging Measurement Data

Introduction

The optional Measurements feature enables aggregate totals, statistics, etc. to be periodically calculated by CATSWeb on configurable schedules, or in quasi-real-time via the Trigger Measurement configurable action or the Perform Measurement Now management link. The calculated values are stored in the MeasurementData table for display, trending and analysis. Ranges for measured values may be configured so that the current range of a data value can be displayed as iconic indicators in Measurement Summary display parts. Alerts may be configured to automatically send E-mail when measured values enter or leave a particular Range, or transition from one Range to another.

Settings for Measurements

The settings below apply to Measurements. Note that when settings are changed, the changes only apply when subsequent (new) measurements are performed. For example, if you change the Upward Trend Icon, Measurement Data records created before the change will still display the prior icon.

Active - Determines whether or not the Measurement is performed automatically, per the other information in the Scheduling Parameters section. If this box is not checked, the Measurement can still be performed manually via the Perform Measurement Now link, or via the Trigger Measurement configurable action.
Bad Trend Icon - Choose an icon that will appear in the Trend column of Measurement Data displays when the trend is bad.
Bad Trend Icon Help Text - While viewing Measurement Data, this is the text that a user sees when they float their mouse over the icon that represents a bad trend (the Bad Trend Icon). Web developers often refer to this as Alternative Text or just "Alt Text". The Help Text is displayed in the same way as the Description for field definitions.

Calculation - The type of summary calculation that is performed on the data specified in Field Expression. For example, if Field Expression is set to "Field1 {-} Field2" and Calculation is set to Average, Field1 - Field2 will first be calculated for each record in the data source, and these values will then be averaged to produce the final measured value. The Record Count option does not use Field Expression, since it counts the records without accessing fields. The Single Value option is used to return data from only the first record in the data source (e.g., to return the result from a complex calculation performed by a stored procedure).

Component Name - The name of the parent Component record for all Measurement components ("Measurements", read-only).

Data Retention - The number of days that CATSWeb retains data from Measurements. Measured data older than this is automatically purged from the system. Enter 0 (zero) to keep the measured data indefinitely. Measurement Data may also be purged manually via the Purge Measurement Data form.

Important

Once Measurement Data is purged, it cannot be recovered without restoring a backup of the CATSWeb database.

Data Source Type - The type of data source that provides the raw data for a Measurement. After selecting a type, click the iconic reload button to choose the specific data source from a list (if applicable). Most data source types are self-explanatory.

Date Format - A format string that is applied to date values when they are displayed within measurement data. This format string is specified in the same way as the Format setting for field definitions.

Days of the Month - Used only for Measurements with a Frequency setting of One-time or Monthly by Date, this multi-select list is used to specify the days on which the Measurements will be performed during the month.

Days of the Week - Used only for Measurements with a Frequency setting of Periodically, this multi-select list is used to specify the days of the week on which the Measurements will be performed. 01=Sunday, 02=Monday, etc.

Description - An optional description of the Measurment. This value can appear as a column in Measurement Summary display parts.

Downward Trend Icon - Choose an icon that will appear in the Trend Direction column of Measurement Data displays when the trend is downward.

Downward Trend Icon Help Text - While viewing Measurement Data, this is the text that a user sees when they float their mouse over the Trend Direction icon that represents a downward trend (the Downward Trend Icon). Web developers often refer to this as Alternative Text or just "Alt Text". The Help Text is displayed in the same way as the Description for field definitions.

Field Expression - The name of a field (column) in the data source, or an arithmetic expression combining two fields from the data source. Arithmetic operators (+, -, x, /) must be enclosed in braces (ex: "Field1{/} Field2"). The expression is evaluated for each record in the data source, and the resulting data from each record is used in the Calculation described above. The final value from the Calculation is used as the measured value. Field Expression is not required if Calculation is set to Record Count.

Field expressions that calculate time spans may use the "{Today}" token to represent the current date. The default units for time span calculations are days, but hours, weeks, months, etc. may be specified. Here are some examples of field expressions:

Example	Result
StandardSingle001	Returns the value of StandardSingle001 from the first record in the data source.
{Today} {-} DateClosedGoal	Returns the number of days between the current date and the goal date (the date in the DateClosedGoal field). The value will be positive if the item is overdue, negative if the goal date is in the future.
DateClosedGoal {-} {Today} [Weeks]	Same as the last example, but returns the number of weeks instead of days, and reverses the sign (overdue is negative). The available time span units are: [Seconds], [Minutes], [Days], [Weeks], [Months] and [Years].
StandardDouble001 {x} StandardLongInteger002	Multiplies StandardDouble001 by StandardLongInteger002 and returns the result.

Flat Trend Icon - Choose an icon that will appear in the Trend Direction column of Measurement Data displays when the trend is flat.

Flat Trend Icon Help Text - While viewing Measurement Data, this is the text that a user sees when they float their mouse over the Trend Direction icon that represents a flat trend (the Flat Trend Icon). Web developers often refer to this as Alternative Text or just "Alt Text". The Help Text is displayed in the same way as the Description for field definitions
.

Frequency - This setting is used to specify the frequency of the Measurement and how it is scheduled. The setting is ignored when the Perform Measurement Now link is used to perform the measurement. One of the following values:

One-time - The measurement is performed only once at the first scheduled time. Following execution, the Active setting is automatically changed to false (unchecked), thereby preventing it from running again. The Months, Days of the Month and Hours settings determine when the job runs. The Days of the Week setting is ignored.
Monthly by Date - Themeasurement is performed on a regular monthly schedule as defined by the Months, Days of the Month and Hours settings. The Days of the Week setting is ignored. The measurement may be configured to be performed many times during each month, since the applicable scheduling parameters are multi-select lists.
Periodically - The measurement is performed on a regular schedule as defined by the Months, Days of the Week and Hours settings. The Days of the Month setting is ignored. You might also think of this type of measurement as a 'Weekly by Day' measurement, with the added benefit of being able to limit its execution based on the month (select all months if by-month limits aren't needed). The measurement may be configured to run many times during each week, since the applicable scheduling parameters are multi-select lists.

Good Trend - Choose the type of trend in the data that is considered to be good. For example, increasing data would be good in a measurement of "Total Revenue", while decreasing data would be good in a measurement of "Total Defects". If you choose Converging Data, click the iconic reload button to expose the Ideal Value setting.

Good Trend Icon - Choose an icon that will appear in the Trend column of Measurement Data displays when the trend is good.

Good Trend Icon Help Text - While viewing Measurement Data, this is the text that a user sees when they float their mouse over the icon that represents a good trend (the Good Trend Icon). Web developers often refer to this as Alternative Text or just "Alt Text". The Help Text is displayed in the same way as the Description for field definitions.

Hours - This multi-select list is used to specify the hours of the day in which the Measurement will be performed. Hours are specified in 24-hour format: 00=Midnight, 12=Noon, 23=11 PM. If multiple Measurements are scheduled to be performed in the same hour, the Order within Hour setting determines the order in which they are performed.

Ideal Value - When Good Trend is set to Converging Data, this is the value that the trend must converge toward to be considered a good trend. For example, if this value is 10, measured values of 8 or 12 would be considered equally good (or bad). If the next value was 9 or 11, a good trend would be present, since the data is converging toward the ideal value of 10.

Links in Data (section) - Present in Display Parts that can display data, this section is used in the same way as the Optional Links in Results section of the Drill Down form. If the data is from saved queries or filters, you do not need to define links for the record key fields (ActionID, SubtaskID, etc.) since CATSWeb provides these links automatically.

Measurement Name - A unique name for the Measurement.

Measurement Name Link Type - Choose a type of link for the Measurement Name field when it appears in Measurement Data displays. Click the iconic reload button and choose a specific target for the link.

Months - This multi-select list is used to specify the months in which the measurement will be performed (01=January, 02=February, etc.). If the measurement is intended to be performed in all months, be sure to select all months, rather than selecting none.
Moving Average (section) - The section provides configuration parameters for the moving average calculation. Measurement Data records store both the actual value from the measurement, and the moving average value that is calculated from the actual value and prior values of the measurement. These settings determine how moving averages are calculated and used:
- SQL - The SQL statement that provides raw data for the Measurement when the Data Source Type is SQL. The SQL may use tokens or field value replacements as described here
- Trend Direction Icon Display Part - Choose a display part that will be shown when the user clicks the Trend Direction icon while viewing Measurement Data. This would typically be a Trend Chanrt display part. If Override Settings is checked, various settings in the display part will be overriden with information from the Measurement's configuration and current measured values.
- Trend Status Icon Display Part - Choose a display part that will be shown when the user clicks the Trend icon while viewing Measurement Data. This would typically be a Trend Chanrt display part. If Override Settings is checked, various settings in the display part will be overriden with information from the Measurement's configuration and current measured values.
- Upward Trend Icon - Choose an icon that will appear in the Trend Direction column of Measurement Data displays when the trend is upward.
- Upward Trend Icon Help Text - While viewing Measurement Data, this is the text that a user sees when they float their mouse over the Trend Direction icon that represents an upward trend (the Upward Trend Icon). Web developers often refer to this as Alternative Text or just "Alt Text". The Help Text is displayed in the same way as the Description for field definitions.
- Subcomponent Type - The type of Subcomponent ("Measurement", read-only).
- Value Format - A format string that is applied to measurement values (including the moving average values) when they are displayed. This format string is specified in the same way as the Format setting for field definitions.
Back to Top

Measurement Ranges
Measurement Ranges allow a particular Icon to be associated with measured values that are in the specified range. The icon is displayed in the Range column of Measurement Data displays, such as in a Measurement Summary display part. Measurement Ranges are also required in Measurement Alerts, as a means of specifying the conditions under which an alert is sent. These settings apply to Measurement Ranges:
Active - Determines whether or not the Measurement Range is active for the Measurement.

Description - An optional description of the Measurment Range.

End Limit - Specifies whether the End Value is Inclusive or Exclusive. When CATSWeb evaluates the measured value to determine if it is in the range, it uses the following logic to evaluate the measured value against the End Value, depending on the selection made:
End Value - The numeric value that defines the start of the range. See also: End Limit.
Icon - Choose an icon that will appear in the Range column of Measurement Data displays when the measured value is in the range.
Icon Help Text - While viewing Measurement Data, this is the text that a user sees when they float their mouse over the Icon. Web developers often refer to this as Alternative Text or just "Alt Text". The Help Text is displayed in the same way as the Description for field definitions.
Measurement Name - The name of the parent Measurement (read-only).
Meter Zone Overrides (section) - The settings in this section can be used to override Meter Zone information when the Range Icon Dislay Part, Trend Status Icon Display Part or Trend Direction Icon Display Part is a Meter. The settings are the same as in a Meter Zone, and are described here. If any of the Measurement Ranges have valid Meter Zone Overrides specified, then all of the Meter Zones are overriden in the Meter.
Range Name - The name of the Measurement Range (ex: "Good"). This name must be unique among other range names for the Measurement.
Start Limit - Specifies whether the Start Value is Inclusive or Exclusive. When CATSWeb evaluates the measured value to determine if it is in the range, it uses the following logic to evaluate the measured value against the Start Value, depending on the selection made:
Start Value - The numeric value that defines the start of the range. See also: Start Limit.

Back to Top

Measurement Alerts

Measurement Alerts allow E-mail alerts to be sent when when measured values enter or leave a particular Range, or transition from one Range to another. These settings apply to Measurement Alerts:

Active - Determines whether or not the Measurement Alert is active for the Measurement.
Alert Name - The name of the Measurement Alert (ex: "Alert when Critical"). This name must be unique among other alert names for the Measurement.
Bcc - Enter Bcc recipients for the alert E-mail message.
Cc - Select and/or enter Cc recipients for the alert E-mail message.
Description - An optional description of the Measurment Alert.
Importance - Choose an importance (priority) for the alert E-mail message.
Measurement Name - The name of the parent Measurement (read-only).
Message - Enter the body for the alert E-mail message. Values from fields in the current Measurement Data record can be included by specifying the field name between tilde characters such as "~MeasurementName~", "~MeasurementValue~", "~MovingAverageValue~" or "~MeasurementDate~". Text tokens and date tokens may also be used. Note that text tokens such as "{My Name}" have limited value since the measurement is performed by a CATSWeb system account.
Range Determination - Choose the value that is used to determine the current range for the measurement data (current measured value or the moving average value). This would typically be set the same as the Range Determination setting in the parent Measurement, but may be different so as to allow better precision in determining when to send an alert. For example, you may wish an alert to be sent whenever the current measured value enters a range, while the measurement data display uses the smoothed (moving average) value to determine the range icon.
Range(s) From - Select the range(s) that the immediately prior measurement point must be in to make the alert eligible to be triggered. For the alert to actually trigger, the Range(s) To criteria must also be met. If you want the alert to trigger based only on the Range(s) To criteria, don't select anything in this list.
Range(s) To - Select the range(s) that the current measurement point must be in to make the alert eligible to be triggered. For the alert to actually trigger, the Range(s) From criteria must also be met. If you want the alert to trigger based only on the Range(s) From criteria, don't select anything in this list.
Subject - Enter the subject for the alert E-mail message. Values from fields in the current Measurement Data record can be included by specifying the field name between tilde characters such as "~MeasurementName~", "~MeasurementValue~", "~MovingAverageValue~" or "~MeasurementDate~". Text tokens and date tokens may also be used. Note that text tokens such as "{My Name}" have limited value since the measurement is performed by a CATSWeb system account.
To - Select and/or enter To recipients for the alert E-mail message. You must select or enter at least one recipeient for the message, or it will not be sent when the alert triggers.

Purging Measurement Data

Measurement Data can be purged at any time via the Purge Measurement Data form. This form is accesed by clicking the Measurments button on the Manage page, then clicking the Purge Measurement Data link. Note that data for a particular measurement can be purged automatically via the Data Retention setting for the Measurement.

Important

Once Measurement Data is purged, it cannot be recovered without restoring a backup of the CATSWeb database.

These fields are present on the Purge Measurement Data form:

Measurements - Select the measurement(s) to purge the Measurement Data for.
Date Range - Specify an optional date range to constrain the Measurement Data records to be purged (based on the date/time that the measurement was made). The date range may be entered using the same format as date ranges for CATSWeb queries.

Click Submit to purge the specified Measurement Data.

Back to Top