Element API
The calls to the /api/element
and /api/element_info
API endpoints return information about all the elements within the Catalog. The response can be parsed to populate objects with information specific to one or more element IDs.
Prerequisites:
- Set up API access
- Verify that you have API access and obtain a token via get_token call
Table of contents:
1. Access Admin > System > API Toolkit
2. Get Elements Available to User
- Item: element
- Enter an API Token
- [Run request]
- The returned object contains an array of objects representing all elements available to the user who executes the API call.
- See Example Response and Fields Description for details
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.
3. Get All Elements
- Item: element
- show_hidden_from_homepage: Y
- Enter an API Token
- [Run request]
- The returned object contains an array of objects representing all elements in MI: both available to the user and hidden.
- See Example Response and Fields Description for details
4. Get Elements Available to User And Folder Items
- Item: element
- folder_items: Y
- Enter an API Token
- [Run request]
- The returned object contains an array of objects representing all elements and Folder items available to the user.
- See Example Response and Fields Description for details
{
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.
5. Get Elements Available to User And Folder Items Including Hidden Folders
- Item: element
- folder_items: Y
- all_folders: Y
- Enter an API Token
- [Run request]
- 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.
- See Example Response and Fields Description for details
6. Get Elements Available to User, Tags, and Glossary Terms
- Item: element
- with_topics: Y
- Enter an API Token
- [Run request]
- The returned object contains an array of objects representing elements available to the user, those elements' tags, and glossary terms.
- See Example Response and Fields Description for details
{
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.
7. Get Element Info
- Item: element_info
- Methods: GET
- The 9 request parameters described below are optional and can be used to filter the API's response:
- element: The ID of the Element
- dimension_value: The dimension value of the Element
- category: The ID of the Category
- category_name: The name of the Category
- business_owner: The ID of the Business Owner
- business_owner_username: The username of the Business Owner
- business_owner_email: The email of the Business Owner
- tag: The ID of the Tag or Glossary Term
- tag_name: The name of the Tag or Glossary Term
- Enter an API Token
- [Run request]
- The returned object contains an array of objects representing elements
- If no filtering parameters have been applied, all elements are returned.
- See Example Response and Fields Description for details
{
"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
8. Update Element Info
8.1. Update Element Name
- Item: element_info
- Methods: PUT
- Enter ID of the Element
- Actions: Name
- Select JSON request and replace request with the following JSON providing the needed values:
{
"call": "name",
"name": "<New Element Name>"
}
- Enter an API Token
- [Run request]
8.2. Update Element Description
- Item: element_info
- Methods: PUT
- Enter ID of the Element
- Actions: Description
- Select JSON request and replace request with the following JSON providing the needed values:
{
"call": "description",
"description": "<New Element Description>"
}
- Enter an API Token
- [Run request]
8.3. Update Element Certification
- Item: element_info
- Methods: PUT
- Enter ID of the Element
- Actions: Certify
- 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
- Enter an API Token
- [Run request]
8.4. Add Element To Publishing Workflow
- Item: element_info
- Methods: PUT
- Enter ID of the Element
- Actions: Certify
- Select JSON request and replace request with the following JSON providing the needed values:
{
"call": "content_workflow",
"content_workflow_id": "<Publishing Workflow ID>"
}
- Enter an API Token
- [Run request]
8.5. Request Access to Element
- Item: element_info
- Methods: PUT
- Enter ID of the Element
- Actions: Request Access
- 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>
}
- Enter an API Token
- [Run request]