MetricTile Documentation

Overview

The MetricTile component is part of the Vantage analytics and data platform. It serves the purpose of visualizing metrics in a clear and intuitive format, allowing users to quickly assess key performance indicators (KPIs). The tile can display a primary metric, a comparison against a target, and a baseline trend through a sparkline. The design and behavior can be customized based on a variety of settings.

Settings

The MetricTile accepts a configuration object that outlines how it should behave and display information. Below are the exhaustive settings used in the MetricTile.

Primary Measure

1. Name: primaryMeasure

   • Input Type: Object
   • Description: Defines what primary metric to display on the tile. This includes details concerning the metric's data source and aggregation method.
   • Default Value: An empty object {}.

   Fields within primaryMeasure:

   • field:

     • Input Type: Object
     • Description: Contains metadata about the data field, particularly the workflowId that picks the relevant dataset and the specific field to aggregate.
     • Default Value: None, must be specified.

   • aggregation:

     • Input Type: String
     • Description: Defines how the primary data should be aggregated. Options include 'sum', 'avg', 'min', 'max', 'count', and 'latest'. The chosen method changes how raw values are computed.
     • Default Value: 'latest'.

   • format:

     • Input Type: String
     • Description: Determines the display format of the primary value. Options include 'currency', 'percent', and 'raw', along with a custom number format if needed.
     • Default Value: 'number'.

   • customLabel:

     • Input Type: String
     • Description: Optionally provides a title for the metric to override the default label derived from the field metadata.
     • Default Value: None.

Comparison

1. Name: comparison

   • Input Type: Object
   • Description: Configures the optional comparison metric that allows users to evaluate progress against a target.
   • Default Value: An empty object {}.

   Fields within comparison:

   • enabled:

     • Input Type: Boolean
     • Description: Determines whether the comparison section is displayed (true) or hidden (false).
     • Default Value: false.

   • type:

     • Input Type: String
     • Description: Specifies what type of comparison to display. Typically used because of targeted comparisons against objectives.
     • Default Value: None, must be specified when enabled.

   • targetField:

     • Input Type: Object
     • Description: References the field to be used for comparison from the target data.
     • Default Value: None, must be specified when enabled is true.

   • display:

     • Input Type: String
     • Description: Specifies how the comparison value is displayed, either as an 'absolute' difference or as a percentage.
     • Default Value: 'absolute'.

Sparkline

1. Name: sparkline

   • Input Type: Object
   • Description: Defines options for displaying a sparkline, a small line chart indicating trends over time.
   • Default Value: An empty object {}.

   Fields within sparkline:

   • enabled:

     • Input Type: Boolean
     • Description: Determines whether the sparkline is displayed (true) or hidden (false).
     • Default Value: false.

   • dateField:

     • Input Type: Object
     • Description: Contains metadata to fetch the date field in relation to the primary metric. This is essential for plotting the sparkline.
     • Default Value: None, must be specified when enabled is true.

Health

1. Name: health

   • Input Type: Object
   • Description: Facilitates health indicators for the primary measure, allowing for visual feedback based on thresholds.
   • Default Value: An empty object {}.

   Fields within health:

   • enabled:

     • Input Type: Boolean
     • Description: Indicates if health thresholds should be applied and displayed (true) or not (false).
     • Default Value: false.

   • critical:

     • Input Type: Numeric
     • Description: Defines the critical threshold below which the health status is considered poor (red).
     • Default Value: 0.

   • good:

     • Input Type: Numeric
     • Description: Sets the upper threshold for a good health status (green) above which the metric is deemed favorable.
     • Default Value: 0.

   • target:

     • Input Type: String
     • Description: Dictates where the health indicator is rendered (either as a background color or text color).
     • Default Value: 'text'.

Workflows

1. Name: workflows
   • Input Type: Array
   • Description: Contains an array of workflow identifiers which the tile will use to fetch the relevant data.
   • Default Value: An empty array [].

How It Works

The MetricTile component operates by fetching data from specified workflows based on its configuration. Here's how it processes the data:

1. Data Fetching: It accesses the specified workflow using hooks (useTileData and useFullDataset), fetching either high-level stats or detailed data needed for metric calculation.

2. Aggregation Calculation: It processes the retrieved data based on the specified aggregation function, gathering values through the primaryMeasure and deriving metrics accordingly.

3. Comparison Logic: It calculates differences for comparison metrics and adjusts reported values to reflect performance over targets.

4. Conditional Rendering: The component adjusts its appearance based on health thresholds, and visuals adapt accordingly, including secondary values and trend directions with directional icons.

5. Sparklines: If enabled, the sparklines are produced to visually reflect trends over time.

Use Cases & Examples

Use Case 1: Sales Performance Tracking

A company wants to track monthly sales compared to set targets. They utilize the MetricTile to show current sales figures along with a comparison against their target for the month.

Use Case 2: Website Conversion Rate Monitoring

A digital marketing team tracks the conversion rates of their website to determine the effectiveness of campaigns. They can configure the MetricTile to show the conversion rate with a comparison to a previous benchmark.

Example Configuration

For the sales performance tracking use case, a potential configuration of the MetricTile might look like this:

{
  "config": {
    "primaryMeasure": {
      "field": {
        "workflowId": "salesDataWorkflow",
        "field": "monthlySales"
      },
      "aggregation": "sum",
      "format": "currency",
      "customLabel": "Total Sales"
    },
    "comparison": {
      "enabled": true,
      "type": "target",
      "targetField": {
        "workflowId": "salesTargetWorkflow",
        "field": "targetSales"
      },
      "display": "absolute"
    },
    "sparkline": {
      "enabled": true,
      "dateField": {
        "workflowId": "salesDataWorkflow",
        "field": "salesDate"
      }
    },
    "health": {
      "enabled": true,
      "critical": 5000,
      "good": 20000,
      "target": "background"
    },
    "workflows": ["salesDataWorkflow", "salesTargetWorkflow"]
  }
}

In this configuration, the MetricTile displays the total monthly sales, allows comparison against a sales target, shows trends with a sparkline, and responds visually based on performance indicators.