Metric and Scorecard Tables

Metrics Tables

Table Title Table Name Purpose
Archibus Metrics Definitions afm_metric_definitions Holds the definition for each metric and the parameters for calculating metric values.
Archibus Metric Granularities Definitions afm_metric_gran_defs Holds the pre-defined list of metric granularities.
Metric Granularity Assignments afm_metric_grans Holds the list of granularities to which each metric is assigned. The Drill-down View (dflt_view) field holds the name of the view file to load when drilling down from a particular metric.
Archibus Metric Trend Values afm_metric_trend_values Holds the results for each active metric definition calculated by the metric rules.

Metric Scorecard Tables

Table Title Table Name Purpose
Archibus Metric Scorecards List afm_ metric_scard_defs Holds the list of scorecards. Metric display controls, such as the Process Metric Scorecards or the Metrics Alerts Scorecard, refer to one of these scorecard definitions to obtain the list of metrics to display.
Archibus Metric Scorecards Assignments afm_ metric_scards Holds the assignment of particular metrics to scorecards. A metric can be assigned to multiple scorecards. The Displayed on Scorecard (is_displayed) field controls whether metrics assigned to the scorecard appear in the metric display controls.

Archibus Metrics Definitions (afm_metric_definitions)

This table holds the metric definitions that the metrics rule uses to calculate its results.

Summary

Table Title Table Name Purpose
Metric Name metric_name A unique name for the metric, e.g. " env_EnergyConsumption_monthly ". See Naming Convention for Metrics and Metric Recurrence.
Metric Title metric_title A relevant title describing the metric, e.g. "Energy Consumption (monthly)" . Related fields (e.g. metric_title_fr , metric_title_es , etc.) hold the title translated into other languages.
Metric Description description

Detailed business description of the metric, containing the purpose of the metric and information helpful for understanding the metric’s calculation.

For instance, Occupancy (%), might be described as: "Occupancy density calculated as the Number of Occupants/ Number of Seats"

Business Implication biz_implication

The business import of the metric. This text states what the metric means and what actions managers might take based on that metric's information. For instance, the implication for "Occupancy (%)" might be:

"Too low of a value indicates that the portfolio is not being used as efficiently as possible. Too high indicates that space is cramped and the organization cannot accommodate change or growth. More space or an alternative workspace strategy may be indicated."

Numeric Format value_disp_numeric

All metric values are of Numeric data type. This field indicate how the metrics display controls should display the metric values:

  • Number -- as they are (e.g. 100,000.12)
  • Percentage -- multiplied by 100 (e.g. 23%)
  • Base-Unit Area -- converted from the stored value in the Base-Area Units of the project (e.g. sqM) to the user-display area units (e.g. sqM or sqft depending on the user's locale)
  • Organizational Budget Currency -- converted from the common budget currency (as defined in the AbCommonResources-Budget Currency application parameter) to the user-display currency (e.g. dollars or euros based on the user's locale).
Decimal Places value_disp_decimals

By default all metrics are collected and stored with 2 decimals of precision in the afm_metric_trend_values table. This field specifies the rounding that the display controls should perform on values when displaying them.

For instance, you can display "10,000,000.12" with the following rounding values:

  • “2 Places” -- 10,000,000.12
  • “1 Place” -- 10,000,000.1
  • “0 Places” -- 10,000,000.
  • "Hundreds" -- 100,000H

  • “Thousands” -- 10,000K
  • “Millions” -- 10M
  • "Billions" (i.e. "thousand-millions") -- 0.01G

Display Format value_disp_format This is a template pattern formatting the display value. Please see the discussion on Display Format below.
Display Format (Metric) value_disp_format_m This is the template pattern the program uses for formatting the display value if your project database has metric Base-Area Units.
Metric Status metric_status

If this value is "Active", the metrics rule will collect metric trend data per the metric definition.

If this value is "Deactivated", the metric rule will skip this definition. Useful for turning off metrics that are tested but that you do not want in production.

Test Status metric_status_test Holds the result of the "Test Metric" action on the Define Metrics form. The metrics rule will only calculate metrics with a Test Status of "Tested".
Collect Recurrence recurring_rule

Records the recurring rule pattern that defines the collection recurrence -- how often the metrics rule will run this particular metric definition. The metrics rule runs every day. If the current date matches the Collect Recurrence (e.g. Monthly, on the 1st Day of the Month, Yearly, on the Last Day of the Year, etc.) the metrics rule will collect a set of metrics trend data according to the metric definition.

Ignore the existing Collect Frequency ( collect_frequency ) field, which is used for legacy metric defined prior to V.21.2.

Collect: Table collect_table The name of the table containing the data for calculating the metric’s values.
Collect: Date Field to Filter On collect_date_field

Use this field when defining metrics on transaction tables to specify the date the metric rule should examine to determine if a record falls within the current recurrence interval. The record falls in that interval if the value of the collect_date_field falls within the interval. The metric rule measures the interval from the metric recurrence date back to the beginning of the recurrency period (e.g. back one week, one month, one year, etc. depending on the recurrence).

Do not use this field if your metric definition is on an inventory table. In this case, the metric rule creates a snapshot of the inventory data on the recurrence date.

Collect: Date End Field to Filter On collect_ date_end_field Use this field when defining metrics on transaction tables, and the transaction may span multiple recurrence periods. The metric rule will include any record whose Collect: Date Field to Filter on and Collect: Date End Field to Filter on span a time interval that overlaps the current interval.
Collect: Formula collect_formula The formula the metrics rule should use to calculate this metric's values. Please see the discussion Collect: Formula below.
Collect: Where Clause collect_where_clause A "WHERE" clause used for filtering the values returned by the Collect: Formula.
Report: Trend Direction report_trend_dir

This attribute is used for trend direction interpretation, which specifies whether an increase in this metric’s values from the last time period represents a positive or negative outcome for the organization. Possible selections are:

  • Smaller is Better
  • Larger is Better
  • On Target is Better
  • No Significance

When displaying stoplight colors, the Report: Trend Direction indicates whether the program compares against the "high" limits (when "Smaller is Better", the "low" limits (when "Larger is better") or both ("On Target" is better).

Report: Benchmark Value report_benchmark_value Use this field to record any industry benchmark value, against which the organization can compare its performance.
Report Limit Target report_limit_target The current performance target value for the organization.
Report Limit High Critical/Warning report_limit_high_crit report_limit_high_warn High critical (red) and warning (yellow) levels for the metric.
Report Limit Low Critical/Warning report_limit_low_crit report_limit_low_warn Low critical (red) and warning (yellow) levels for the metric
Ratio Metric Numerator ratio_metric_num

Specifies the numerator metric (e.g. fin_RealEstateOpEx_monthly) in a ratio metric.

If you specify a Ratio Metric Numerator, you must also specify a Ratio Metric Denominator.

Ratio Metric Denominator ratio_metric_denom Metric that is the denominator (e.g. spac_GrossArea_monthly ) in a ratio metric.
Report: Aggregate As report_aggregate_as Determines how the metric values are aggregated when multiple values occurs for the same granularity value (for instance the same Building Code) and the same date or date range. Possible aggregation operators are Sum, Count, Min, Max, and Avg.

Display Format

This format pattern controls how the program displays metric values. The display format is important for clarity, as the units for metrics change from row to row in a scorecard display.

Wherever possible, use the Decimal Places and Numeric Format settings to control the output format and units, as these round values, convert currencies, and convert areas automatically. For instance, the formatting below you can accomplish without specifying a Display Format.

  • 45,032M
  • 34%
  • 250.0 sqft --or-- 23.2 sqM
  • $5,000 K --or--€3,748 K

Use the Display Format when the metric value is not a standard value or when the metric value is a ratio, and the relationship between the original values and the display units is a function of the metric definition and not the original values. To do so, use a replaceable parameter "{0}" for the value and write the units as you want them to appear. For instance, if you have a Display Format of "{0} hrs" the program will display values like "1.5 hrs".

Use Display Format and Display Format (Metric) if you have a ratio with area as a denominator. For instance, take OpEx per Rentable Area. The metric value is in the budget currency, but the metric itself is divided by the Rentable Area, which is defined by your project base-area units as square feet or square meters, making the denominator either "RSF" (rentable square feet) or "RSM" (rentable square meters). The program will convert the budget currency, but use the format you specify for the denominator.

Project Units are: Base-Unit Area is sqFt Base-Unit Area is sqM
Program Uses Display Format Display Format (Metric)
The Format specified is: {0}/RSF {0}/RSM
Typical output values (numerator is converted to user's display currency): $1.21/RSF €0.29/RSM

(The denominator stays in the Base-Unit Area regardless of the user's locale, as the Base-Unit Area is a function of the project database, not of the user.)

Collect: Formula

This value defines the formula the metric rule uses in its calculation.

  • Use "field: field_name" when the formula should just use a field value (e.g. "field:area_rentable").
  • Use " bean:bean_name" when the metric rule should delegate to a workflow rule (e.g. "bean: CashFlowForecast").
  • Use an SQL formula when the metric should insert an SQL statement that uses fields from the Collect: Table.

You use the SQL formula as follows. Consider the SLA Compliance (%) ( ops_SLACompliance_percent_weekly ) metric. In this case, the Collect:Table is Historical Work Requests ( hwr ). You calculate the ratio of completed work orders to total work requests with the formula below:

Collect:Table hwr
Collect: Formula (SELECT count (wr_id) FROM hwr WHERE escalated_completion = 0)/(select count(*) from hwr)

Another example would be the Cost of Low Density, which prorates the cost of a room by the number of vacancies:

-(rm.count_em-cap_em)*rm.cost/${sql.replaceZero('rm.count_em')}

Note that it is good practice to guard against division by zero. Also, if you are going to deploy the formula on different database servers, test the metric on each server (e.g. on Oracle or Microsoft SQL Server)