Metric API

This article provides sample API calls for managing Metrics:

  • /api/metric: Get all Metrics or a specified Metric available to User, validate, collect data, enable, update live chart, delete a Metric.

PREREQUISITES:

TABLE OF CONTENTS:

  1. Access Admin > System > API Toolkit
  2. Get All Metrics
  3. Get Specified Metric Info
  4. Update a Metric
    1. Validate a Metric
    2. Collect Data for a Metric
    3. Enable a Metric
    4. Update Live Chart
  5. Delete Metric

1. Access Admin > System > API Toolkit

2. Get All Metrics

The GET request to /api/metric returns all Metrics data available to the User.

  1. Item: metric
  2. Method: GET
  3. Enter an API Token
  4. [Run request]

Example Response 

{
  "metrics": [
    {
      "id": 152742,
      "measurement_interval": 3,
      "values_are_additive_across_time_periods": "Yes",
      "name": "Fruit Sales Italy In Store",
      "description": "Fruit Sales Italy In Store Metric",
      "category": 123,
      "display_mask": 13,
      "display_mask_example": "1,234.1K",
      "unit_of_measure": "avocados",
      "data_values": "integer",
      "for_this_metric": "Y",
      "data_source": "dataset",
      "data_collection_trigger": 1,
      "dimension": 0,
      "include_only_new_report_data": "N",
      "dataset_id": 21418,
      "dataset_filter_id": 0,
      "primary_segment_value_ds_column": 9008,
      "secondary_segment_value_ds_column": 9008,
      "measurement_date_ds_column": 9009,
      "measurement_value_ds_column": 9010,
      "ds_aggregate_function": "SUM",
      "ds_incremental_load_ind": "all_data",
      "stoplight_calculation_method": "fixed range",
      "metric_stoplight_color_for_high_values": "#077E45",
      "metric_stoplight_color_for_low_values": "#AC2B2B",
      "stoplight_compare_value_to": 1,
      "compare_value_period": 0,
      "stoplight_range_start": 123,
      "stoplight_range_end": 456,
      "metric_compare_value_range_method": "fixed",
      "metric_stoplight_range_start": 0,
      "metric_stoplight_range_end": 0,
      "metric_compare_value_range_percent": 0,
      "chart_type": "lines",
      "use_different_color_bars_for_positive_vs_negative_values": "the same color",
      "moving_average_interval": "30 day",
      "max_time_before_expired_period": 2,
      "max_time_before_expired_unit": "day",
      "show_minimum_ever_line": "N",
      "chart_layout": 1,
      "do_not_chart_values_smaller_than": 0,
      "do_not_chart_values_greater_than": 0,
      "statistical_view_standard_deviations": 2,
      "can_be_viewed_without_login": "public",
      "batch_load_data_going_back_no_more_than": 0,
      "project_value_of_partial_days": "No",
      "project_values_of_future_days": "No",
      "project_future_day_using": "linear_regression",
      "metric_future_projection_reference_metric_id": 152742,
      "tile_variance_compare_to": 3,
      "baseline_trend_to_avg_of_prior": 1,
      "extend_target_interval": "N",
      "target_view_extend_scope": "current",
      "target_view_extend_measurement_interval": 4,
      "include_metric_data_table_in_e_mail_digests": "No",
      "suppress_alerts_on_partial_period_data": "Yes",
      "business_owner_id": 88,
      "technical_owner_id": 118
    }
   ]
}

Fields Description

This description covers only the fields that contain information useful  for Portal Page development, the fields that are not covered are for  internal use only.

 

Field Name Value Type Description
id integer The ID of the Metric.
measurement_interval integer The ID of the Measurement Interval.
values_are_additive_across_time_periods string Whether or not daily values can be aggregated into weekly and monthly totals. Takes value “Y” if values are additive, “N” if not.
name string The name of the Metric.
description string The description of the Metric.
category integer The ID of the Metric’s category.
display_mask integer The ID of the applied display mask.
display_mask_example string An example of the display mask format.
unit_of_measure string Metric's value display units.
data_values string Defines whether data values are “integer” or “decimal”.
for_this_metric string
Defines the stoplight expectation for this metric. Takes value “Y” if higher values are better, “N” if lower values are better, “RANGE” if measurements should fall within a certain range, and “N/A” if there is no expectation for what is better.
data_source string The data source of the Metric.
data_collection_trigger integer The ID of the associated Trigger.
dimension integer The ID of the Metric's Dimension. Takes value "0" if not dimensioned.
data_fetch_command string The command used to fetch data for the Metric.
include_only_new_report_data string Whether Metric values are calculated for new data only ("Y"), or for all data ("N").
dataset_id integer The ID of the Dataset from which the Metric is populated.
dataset_filter_id integer The ID of the Dataset View from which the Metric is populated.
ds_aggregate_function string The aggregation function applied to Dataset values.
business_owner_id
 integer The ID of the Metric’s Business Owner.
data_steward_id integer The ID of the Metric’s Data Steward. 
technical_owner_id integer The ID of the Metric’s Technical Owner. 

3. Get Specified Metric Info

  • The GET request to /api/metric/id/<id> returns the specified Metric's data.
  1. Item: metric
  2. Method: GET
  3. ID: Enter the ID of the Metric
    • Metric ID can be determined in the web browser URL of the Metric Editor. For example:
 https://<hostname>/editor/element/metric/152742
  1. Enter an API Token
  2. [Run request]

4. Update a Metric

4.1. Validate a Metric

The PUT request to /api/metric/id/<id> with body {"call": "validate", "last_measurement_time": "<time>"} validates the specified Metric.

  1. Item: metric
  2. Method: PUT
  3. ID: Enter the ID of the Metric
  4. Actions: Validate
  5. Select JSON request, specify the last_measurement_time
  6. Enter an API Token
  7. [Run request]

4.2. Collect Data for a Metric

The PUT request to /api/metric/id/<id> with body {"call": "collect", "compute_metric_values_after": "<time>"} collects data for the specified Metric.

  1. Item: metric
  2. Method: PUT
  3. ID: Enter the ID of the Metric
  4. Actions: Collect Data
  5. Select JSON request, specify the compute_metric_values_after
  6. Enter an API Token
  7. [Run request]

4.3. Enable a Metric

The PUT request to /api/metric/id/<id> with body {"call": "enable"} enables the specified Metric.

  1. Item: metric
  2. Method: PUT
  3. ID: Enter the ID of the Metric
  4. Actions: Enable
  5. Enter an API Token
  6. [Run request]

4.4. Update Live Chart

The PUT request to /api/metric/id/<id> with body {"call": "generate"} updates the live chart for the specified Metric.

  1. Item: metric
  2. Method: PUT
  3. ID: Enter the ID of the Metric
  4. Actions: Update Live Chart
  5. Enter an API Token
  6. [Run request]

5. Delete Metric

The DELETE request to /api/metric/id/<id>  deletes the specified Metric.

  1. Item: metric
  2. Method: DELETE
  3. ID: Enter the ID of the Metric
  4. Enter an API Token
  5. [Run request]