Help & Documentation

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:

Set up API access
Verify that you have API access
Obtain a token via a get token call since all API calls require a token

TABLE OF CONTENTS:

Access Admin > System > API Toolkit
Get All Metrics
- Example Response
- Fields Description
Get Specified Metric Info
Update a Metric
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.

Item: metric
Method: GET
Enter an API Token
[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",
      "content_type_alias": "metric",
      "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.
content_type_alias	string	The alias of the Content Type. For Metrics, this value is always `"metric"`.
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.

Item: metric
Method: GET
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

Enter an API Token
[Run request]
- See Example Response and Fields Description for details.

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.

Item: metric
Method: PUT
ID: Enter the ID of the Metric
Actions: Validate
Select JSON request, specify the last_measurement_time
Enter an API Token
[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.

Item: metric
Method: PUT
ID: Enter the ID of the Metric
Actions: Collect Data
Select JSON request, specify the compute_metric_values_after
Enter an API Token
[Run request]

4.3. Enable a Metric

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

Item: metric
Method: PUT
ID: Enter the ID of the Metric
Actions: Enable
Enter an API Token
[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.

Item: metric
Method: PUT
ID: Enter the ID of the Metric
Actions: Update Live Chart
Enter an API Token
[Run request]

5. Delete Metric

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

Item: metric
Method: DELETE
ID: Enter the ID of the Metric
Enter an API Token
[Run request]

Help & Documentation

Metric API

1. Access Admin > System > API Toolkit