Element API

1. Access Admin > System > API Toolkit

2. Get Elements Available to User

  1. Item: element
  2. Enter an API Token
  3. [Run request]
  4. The returned object contains an array of objects representing all elements available to the user who executes the API call.
Example Response

This example demonstrates an object which represents a single element.

{
  "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

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
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.

3. Get All Elements

  1. Item: element
  2. show_hidden_from_homepage: Y
  3. Enter an API Token
  4. [Run request]
  5. The returned object contains an array of objects representing all elements in MI: both available to the user and hidden.

4. Get Elements Available to User And Folder Items

  1. Item: element
  2. folder_items: Y
  3. Enter an API Token
  4. [Run request]
  5. The returned object contains an array of objects representing all elements and Folder items available to the user.
Example Response
{
  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"
    }
  ],
  folderItems: [
    {
      "folder_item_id": "3644700",
      "folder_id": "171",
      "element_id": "1247",
      "segment_value_id": "1",
      "display_order": "1"
    }
  ]
}

Fields Description

Fields related to the elements were previously described in the prior Fields Description section. Here you can find the description of the fields related to Folder items.

Field Name Value Type Description
folder_item_id string The ID of the Folder item unique for each element.
folder_id string The ID of the Folder.
element_id string The ID of the element.
segment_value_id string The dimension value of the element.
display_order string The order in which the element is displayed in the Folder.

5. Get Elements Available to User And Folder Items Including Hidden Folders

  1. Item: element
  2. folder_items: Y
  3. all_folders: Y
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects representing all elements available to the user and all Folder items, including items from the Folders not displayed on the Homepage.

6. Get Elements Available to User, Tags, and Glossary Terms

  1. Item: element
  2. with_topics: Y
  3. Enter an API Token
  4. [Run request]
  5. The returned object contains an array of objects representing elements available to the user, those elements' tags, and glossary terms.
Example Response
{
  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"
    }
  ],
  topics: [
    {
      "topic_id": "223",
      "topic_type_id": "55",
      "name": "Robert New Term for Docs",
      "definition": "Some text...",
      "description": "This is description of my section",
      "business_owner_id": "118",
      "technical_owner_id": "118",
      "data_steward_id": null,
      "created_by": "robert",
      "created_time": "2023-10-18 16:50:40",
      "last_updated_by": "robert",
      "last_updated_time": "2023-10-18 19:14:35",
      "is_parent_topic": "N",
      "parent_topic_id": null,
      "is_governed_ind": "Y",
      "created_by_id": "0",
      "topic_type_name": "Robert Section",
      "use_icon": "uploaded",
      "icon_type": "image/png",
      "icon": "iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAACXBIWXMAAA7EAAAOxAGVKw4bAAADKUlEQVQoFQEeA+H8Af////8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAAAAAAAAAAAAAKmpqQCGhoYAAAAAAAAAAAAAAAAAAAAAAAAAAACpqakAhoaGAAAAAAAAAAAAAP///////////////4WFhf8AAAD///////////////////////////+FhYX/AAAA////////////Af////8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAri4uABBQUEAmJiYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAgIP8AAAD/AAAA/39/f////////////////////////////7e3t/8gICD/ICAg/5+fn///////AHBwcP8AAAD/AAAA/wAAAP8gICD/n5+f/////////////////xgYGP8AAAD/AAAA/wgICP//////APf39/9ISEj/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/2hoaP//////AP/////39/f/YGBg/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA////////////AP///////////////4eHh/8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/aGho////////////Af////8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAArMTblUXmdZsAAAAASUVORK5CYII=",
      "fa_icon": null,
      "child_topics": "",
      "full_name": "Robert New Term for Docs"
    }
  ]
}

Fields Description

See Example Response for the description of Element-related fields. The table provided here is describing fields related to Tags and Glossary Terms.

Field Name Value Type Description
business_owner_id string The ID of the business owner.
child_topics string The type of icon of the glossary term.
created_by string The Username of the user who created the tag or glossary term.
created_by_id string The ID of the user who created the tag or glossary term.
created_time string Date and time of tag's or glossary term's creation.
data_steward_id string The ID of the data steward.
definition string Definition of the glossary term.
description string Description of the glossary term.
fa_icon string The description of the favicon.
full_name string The name of the tag or glossary term.
icon string The base64 representation of the uploaded icon.
icon_type string The type of icon of the glossary term.
is_governed_ind string Whether or not the element is a Glossary Term.
last_updated_by string The Username of the last user who updated the tag or glossary term.
last_updated_time string Date and time of the last update.
name string The name of the tag or glossary term.
technical_owner_id string The ID of the technical owner.
topic_id string The ID of the tag or glossary term.
topic_type_id string The ID of the glossary section. If the element is tag, takes value 0.
topic_type_name string The name of the glossary section.
use_icon string Whether the glossary term has a favicon, an uploaded icon, or no icon at all.
​​​​ ​​​​

7. Get Element Info

  1. Item: element_info
  2. Methods: GET
  • The 9 request parameters described below are optional and can be used to filter the API's response:
    1. element: The ID of the Element
    2. dimension_value: The dimension value of the Element
    3. category: The ID of the Category
    4. category_name: The name of the Category
    5. business_owner: The ID of the Business Owner
    6. business_owner_username: The username of the Business Owner
    7. business_owner_email: The email of the Business Owner
    8. tag: The ID of the Tag or Glossary Term
    9. tag_name: The name of the Tag or Glossary Term
  1. Enter an API Token
  2. [Run request]
  3. The returned object contains an array of objects representing elements
    • If no filtering parameters have been applied, all elements are returned.
  4. See Example Response  and Fields Description for details
Example Response
{
    "info": [
        {
            "id": "122373",
            "dimension_value": "0",
            "name": "Test for dashboard_element",
            "description": "Test for dashboard_element",
            "last_updated_time": null,
            "content_type": "Microsoft Power BI",
            "element_type": "external report",
            "category": "123",
            "business_owner_email": "[email protected]",
            "technical_owner_email": "[email protected]",
            "plugin_connection_profile_id": "261",
            "plugin_internal_name": "powerbi",
            "external_report_url": "https://app.powerbi.com/groups/d6ad0d96-7d4e-44ed-8b53-afcce54af419/reports/4f52ef19-b252-4285-b61d-a50f6c53933f",
            "certified_ind": "Y",
            "certified_by": "Robert Isaenko",
            "last_certified_time": "2023-03-14 22:43:22",
            "last_measurement_time": null,
            "external_report_display": "iframe",
            "tags": [
                "test",
                "docs",
                "Robert New Term for Docs",
                "My new term"
            ]
        }
    ]
}

Fields Description

Field Name Value Type Description
business_owner_email string The email of element's business owner.
category string The ID of the element's category.
certified_by string The name of the user who certified the element.
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.
description string The description of the element.
dimension_value string The dimension value of the element.
element_type string The type of the element.
external_report_display string If the element is an External Report, describes its display options.
external_report_url string The URL of the element in the external BI tool.
id string The ID of the element.
last_certified_time string The date and time of the last certification of the element.
last_measurement_time string The date and time of the last measurement of the element.
last_updated_time string The date and time of the last update of the element.
name string The name of the element.
plugin_connection_profile_id string The ID of the element's plugin connection profile.
plugin_internal_name string The name of the element's plugin connection profile.
tags string An array with names of the element's tags and glossary terms.
technical_owner_email string The email of the element's technical owner.

8. Update Element Info

8.1. Update Element Name

  1. Item: element_info
  2. Methods: PUT
  3. Enter ID of the Element
  4. Actions: Name
  5. Select JSON request and replace request with the following JSON providing the needed values:
{
    "call": "name",
    "name": "<New Element Name>"
}
  1. Enter an API Token
  2. [Run request]

8.2. Update Element Description

  1. Item: element_info
  2. Methods: PUT
  3. Enter ID of the Element
  4. Actions: Description
  5. Select JSON request and replace request with the following JSON providing the needed values:
{
    "call": "description",
    "description": "<New Element Description>"
}
  1. Enter an API Token
  2. [Run request]

8.3. Update Element Certification

  1. Item: element_info
  2. Methods: PUT
  3. Enter ID of the Element
  4. Actions: Certify
  5. Select JSON request and replace request with the following JSON providing the needed values:
{
    "call": "certify",
    "certified": "<Y/N>"
}
  • "Y" - the Element is certified
  • "N" - the Element is not certified
  1. Enter an API Token
  2. [Run request]

8.4. Add Element To Publishing Workflow

  1. Item: element_info
  2. Methods: PUT
  3. Enter ID of the Element
  4. Actions: Certify
  5. Select JSON request and replace request with the following JSON providing the needed values:
{
    "call": "content_workflow",
    "content_workflow_id": "<Publishing Workflow ID>"
}
  1. Enter an API Token
  2. [Run request]

8.5. Request Access to Element

  1. Item: element_info    
  2. Methods: PUT
  3. Enter ID of the Element
  4. Actions: Request Access
  5. Select JSON request and replace request with the following JSON providing the needed values:
{
    "call": "request_access",
    "element": <Element ID>,
    "segment_value": <Element Segment Value>
}
  1. Enter an API Token
  2. [Run request]