Favorites API

Prerequisites:

Table of contents:

  1. Access Admin > System > API Toolkit
  2. Get Favorite Folders
  3. Create Favorite Folder
  4. Delete Folder from Favorites
  5. Get Favorite Elements
  6. Add Element to Favorite Folder
  7. Delete Element from Favorite Folder

1. Access Admin > System > API Toolkit

2. Get Favorite Folders

  1. Item: favorite
  2. Methods: GET
  3. Optionally provide ID of the Favorite Folder to retrieve its' data.
    • If this parameter is not provided, all Favorite Folders' data is returned.
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects representing Favorite Folders
Example Response 
{
    "favorites": [
        {
            "id": "382",
            "name": "Most Popular",
            "include_in_favorites_digest_ind": "N",
            "include_in_digest_on": "element update"
        },
        {
            "id": "381",
            "name": "My Favorites",
            "include_in_favorites_digest_ind": "Y",
            "include_in_digest_on": "element update"
        },
        {
            "id": "564",
            "name": "Weekly Popular",
            "include_in_favorites_digest_ind": "Y",
            "include_in_digest_on": "trigger event"
        }
    ]
}

Fields Description

Field Name Value Type Description
id string The ID of the favorite folder.
name string The name of the favorite folder.
include_in_favorites_digest_ind string Whether or not the favorite folder is included in favorites digest.
include_in_digest_on string Whether the favorite folder is included in favorites digest on element update or data collection trigger completion.

3. Create Favorite Folder

  1. Item: favorite
  2. Methods: POST
  3. Enter ID of an existing Favorite Folder
  4. Select JSON request and enter JSON providing the needed values for your Folder:
    • name: The name of the new Favorite Folder
    • include_in_favorites_digest_ind: Whether or not the Favorite Folder is included in Favorites Digest. Available values are yes and no
    • include_in_digest_on: Whether the Favorite Folder is included in Favorites Digest on element update or trigger event
  5. Enter an API Token
  6. [Run request]
  7. The returned object representing the new Favorite Folder

4. Delete Folder from Favorites

  1. Item: favorite
  2. Methods: DELETE
  3. Enter ID of the Favorite Folder that needs to be deleted
  4. Enter an API Token
  5. [Run request]

5. Get Favorite Elements

  1. Item: favorite_element
  2. Methods: GET
  3. Optionally assign parameter favorite the value of the Favorite Folder ID to retrieve its' elements only.
    • If this parameter is not provided, all Favorite Folders' elements are returned.
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects representing Favorite Folders' elements.
Example Response 
{
    "favorite_elements": [
        {
            "user_dashboard_element_instance_id": "478869",
            "user_id": "118",
            "element_id": "2344",
            "segment_value_id": "0",
            "section_type": "Category",
            "favorite_id": "0",
            "category_id": "83",
            "element_type": "multi-metric chart",
            "in_dashboard_ind_flag": "Y",
            "last_stoplight_value": "0",
            "is_expired": "0",
            "is_owned": "0",
            "topics": null,
            "refresh_frequency_text": "Daily",
            "refresh_frequency_sec": "86400",
            "description_markdown_ind": "N",
            "element_info": "World-wide Sales Multi-metric Multi-Metric",
            "metric_unit_of_measure": null,
            "last_measurement_time": "2021-07-15 00:00:00",
            "external_report_download_url_info": null,
            "certified_ind": "N",
            "certification_level_id": null,
            "last_certified_time": null,
            "metric_display_on_tile": "value",
            "metric_moving_average_interval": null,
            "metric_display_on_tile_prefix": null,
            "metric_home_page_compare_value_type": "last value",
            "metric_home_page_compare_line_id": null,
            "metric_home_page_compare_target_id": null,
            "report_single_unit_label": null,
            "report_multiple_units_label": null,
            "report_no_units_label": null,
            "report_on_demand_generation_ind": "Y",
            "external_report_display": null,
            "certification_level_name": null,
            "certification_level_color": null,
            "last_certified_by_name": null,
            "last_certified_by_email": null,
            "business_owner": "Anna Kennedy",
            "business_owner_email": "[email protected]",
            "data_steward": null,
            "data_steward_email": null,
            "technical_owner": "Anna Kennedy",
            "technical_owner_email": "[email protected]",
            "data_source_name": "Manual Entry",
            "supports_last_refreshed_check": null,
            "display_order": "1000000",
            "total_view_count": null,
            "in_favorites": null,
            "is_in_favorites": "0",
            "is_in_folders": "0",
            "mi_name": "Daily",
            "mi_sequence": "30",
            "pct_variance_text": "from last day",
            "total_ind": "N",
            "parent_segment_value_id": null,
            "last_measurement_value_formatted": "8.23M",
            "last_measurement_time_formatted": "Thursday 07/15/2021",
            "metric_last_moving_average_value_formatted": null,
            "last_updated_time": "2022-08-18 08:09:25",
            "total_forecast_amount_formatted": null,
            "last_activity_time": "2018-08-10 00:00:00",
            "last_annotation_text": null,
            "last_commentary_text": null,
            "element_dashboard_name": "World-wide Sales Multi-metric",
            "is_empty_instance_ind": "N",
            "metric_tile_display_pct_variance": null,
            "report_rows": null,
            "last_display_generation_time": "2023-10-18 03:59:22",
            "last_file_updated_time": "",
            "last_modified": "today",
            "favorite_content": null,
            "alert_event_id": null,
            "last_alert_text": null,
            "last_alert_news_type": null,
            "is_alert_active": "0",
            "is_collaborative_alert_active": "0",
            "is_collaborative_annotation_active": "0",
            "is_annotation_active": "0",
            "is_commentary_active": "0",
            "last_notable_event_activity_time": "2018-08-10 00:00:00",
            "last_user_annotation_activity_time": null,
            "last_user_note_activity_time": null,
            "last_alert_event_activity_time": null,
            "reporting_tool_name": null,
            "remove_preview_link_ind": null,
            "is_tech_editor": "N",
            "external_content_type_name": null,
            "enable_click_in_mobile_ind": null,
            "content_type": "Multi-Metric",
            "global_total_view_count": null,
            "has_access": "Y"
        }]
}

Fields Description

Field Name Value Type Description
business_owner string The name of the Element Business Owner.
business_owner_email string The email of the Element Business Owner.
category_id string The ID of the element's category.
certification_level_color string The hex value of the certification level color.
certification_level_id string The ID of the certification level.
certification_level_name string The name of the certification level.
certified_ind string Whether or not the element is certified. Takes value “Y” if the element is certified, “N” - if not.
content_type string The type of the content.
data_source_name string The name of the data source from which the element is populated.
data_steward string The name of the element's Data Steward.
data_steward_email string The email of the element's Data Steward.
description_markdown_ind string Whether or not markdown is applied to the element's description. Takes value “Y” if markdown is enabled, “N” - if not.
element_dashboard_name string The name of the element.
element_id string The ID of the element.
element_type string The type of the element.
enable_click_in_mobile_ind string If the element is an External Report or External Content, defines whether or not the “Enable click-through” option is activated for its content type.
external_content_type_name string If the element is an External Content, describes its type.
external_report_display string If the element is an External Report, describes its display options.
external_report_download_url_info object Information about element download.
favorite_content string The type of favorite content.
favorite_id string The IDs of the element instances in favorites.
folder_id array An array of folders where the element is present.
global_total_view_count string The engagement count of the element.
has_access string Whether or not the user who ran the API request has access to the element.
in_dashboard_ind_flag string Whether or not the element is displayed on the dashboard.
in_favorites string The IDs of favorites where the element is present.
is_empty_instance_ind string Whether or not the last instance of the report is empty.
is_expired string Whether or not the element is expired.
is_in_favorites string Whether or not the element is displayed on the dashboard.
is_in_favorites string Whether or not the element is in favorites. Takes value “1” if the element is in favorites, “0” - if not.
is_in_folders string Whether or not the element is in any folder. Takes value “1” if the element is in any folder, “0” - if not.
is_owned string Whether or not the element has an owner. Takes value “1” if the element has an owner, “0” - if not.
is_tech_editor string Whether or not the user who ran the API request can edit the element. Takes value “1” if the user who ran the API request can edit the element, “0” - if not.
last_activity_time string The date and time of the last element activity.
last_alert_event_activity_time string The date and time of the last alert activity.
last_alert_news_type string The type of the last alert. Can take one of the three value: “good”, “bad”, and “neutral”.
last_alert_text string The text of the last alert.
last_annotation_text string The text of the last annotation.
last_certified_by_email string The email of the user who certified the element.
last_certified_by_name string The name of the user who certified the element.
last_certified_time string The date and time of the last certification of the element.
last_commentary_text string The text of the last comment.
last_updated_time string The date and time of the last element update.
metric_last_moving_average_value_formatted string The last collected value of a metric.
metric_tile_display_pct_variance string The percentage ratio between the two latest metric values.
refresh_frequency_sec string The frequency of element refresh in seconds.
reporting_tool_name string If the element is an External Report, displays the name of the BI tool from which the element is populated.
segment_value_id string The dimension value of the element.
technical_owner string The element's Technical Owner.
technical_owner_email string The email of the element's Technical Owner.
topics array An array of the element's tags' IDs.
total_view_count string The engagement count of the element.
user_dashboard_element_instance_id string A unique ID of the element record.
user_id string The ID of the user who ran the API request.

6. Add Element to Favorite Folder

  1. Item: favorite_element
  2. Methods: POST
  3. Enter any number
  4. Select JSON request and enter JSON providing the needed values:
    • favorite_id: The ID of the Favorite Folder
    • element_id: The ID of the Element
    • segment_value_id:
      • If the Element is non-dimensioned, assign any numeric value to this parameter, the parameter will be ignored.
      • If the Element is dimensioned, provide its dimension value.
  5. Enter an API Token
  6. [Run request]

7. Delete Element from Favorite Folder 

$.ajax({
    url: '/api/favorite_element/id/elementId?favorite_id=favoriteId&elementSegment=0',
    type: 'DELETE',
});

Provide values for the following parameters:

  • elementId - the ID of the Element,
  • favoriteFolderId - the ID of the Favorite Folder from which the Element will be removed,
  • elementSegment - dimension value of the Element,
    • If the Element is non-dimensioned, assign any numeric value to this parameter, the parameter will be ignored.