Folder API
Prerequisites:
- Set up API access
- Verify that you have API access and obtain a token via get_token call
Table of contents:
2. Configure Folder
2.1. Get Folder
- Item: folder
- Methods: GET
- Enter the ID of the Folder or Sub-Folder which data needs to be retrieved
- Enter an API Token
- [Run request]
- The returned object contains an object with Folder's data.
- See Example Response and Fields Description for details
2.2. Create Folder
- Item: folder
- Methods: POST
- Enter ID of an existing Folder
- Select JSON request and enter JSON providing the needed values for your Folder:
- The value of
id
parameter is assigned automatically and does not need to be provided manually - All parameters that were not provided manually will be assigned default values
- See Example Response for details on Folder's data structure
- The value of
- Enter an API Token
- [Run request]
- The returned object contains an object with Folder's data.
- See Example Response and Fields Description for details
2.2.1. Create Sub-Folder
- Item: folder
- Methods: POST
- Enter ID of an existing Folder
- Select JSON request and replace request with the following JSON providing the needed values:
{
"parent_folder_id": "<Parent Folder ID>",
"name": "<Sub-Folder name>"
}
- Enter an API Token
- [Run request]
- The returned object contains an object with Sub-Folder's data.
2.3. Update Folder
- Item: folder
- Methods: PUT
- Enter ID of the Folder which data needs to be updated
- Select JSON request and enter JSON with the updated Folder's data:
- See Example Response for details on Folder's data
- Enter an API Token
- [Run request]
- The returned object contains an array with an object with the updated Folder's data.
- See Example Response and Fields Description for details
2.3.1. Update Sub-Folder
- Item: folder
- Methods: PUT
- Enter ID of the Sub-Folder which data needs to be updated
- Select JSON request and replace request with the following JSON providing the needed values:
{
"id": "<Sub-Folder ID>",
"parent_folder_id": "<Parent Folder ID>",
"name": "<Sub-Folder Name>"
}
- Enter an API Token
- [Run request]
- The returned object contains an array with an object with the updated Folder's data.
2.3.2. Copy Or Move Folder
- Item: folder
- Methods: PUT
- Enter ID of the Folder or Sub-Folder which needs to be copied or moved
-
Actions:
- Copy: A copy of the selected Folder is created inside of the target Folder
- Move: Selected Folder is moved inside the target Folder
- Select JSON request and assign
target_folder_id
the ID of the target Folder - Enter an API Token
- [Run request]
2.4. Delete Folder
- Item: folder
- Methods: DELETE
- Enter ID of the Folder or Sub-Folder which needs to deleted
- Enter an API Token
- [Run request]
3. Configure Folder Elements
3.1. Get Folder Elements
Note: Beginning v6.4.3 this API request returns only Elements that are placed in the Folder, without Elements with Discoverability.
- Item: folder_element
- Methods: GET
- Use one of the following parameters to retrieve Folder's data:
- folder_id: Enter Folder ID
- folder_name: Enter Folder Name
- Enter an API Token
- [Run request]
- The returned object contains an object with Folder elements' data.
- See Example Response and Fields Description for details
{
"folder_elements": [
{
"user_dashboard_element_instance_id": "628844",
"user_id": "118",
"element_id": "122343",
"segment_value_id": "0",
"section_type": "Category",
"favorite_id": "0",
"category_id": "123",
"element_type": "other external content",
"in_dashboard_ind_flag": "Y",
"last_stoplight_value": "0",
"is_expired": "0",
"is_owned": "1",
"topics": null,
"refresh_frequency_text": null,
"refresh_frequency_sec": null,
"description_markdown_ind": "N",
"element_info": "",
"metric_unit_of_measure": null,
"last_measurement_time": null,
"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": "iframe",
"certification_level_name": null,
"certification_level_color": null,
"last_certified_by_name": null,
"last_certified_by_email": null,
"business_owner": "Robert Isaenko",
"business_owner_email": "[email protected]",
"data_steward": null,
"data_steward_email": null,
"technical_owner": "Robert Isaenko",
"technical_owner_email": "[email protected]",
"data_source_name": "RI_Local Filesystem via DP",
"supports_last_refreshed_check": "none",
"display_order": "1000000",
"total_view_count": "7",
"in_favorites": "381",
"is_in_favorites": "1",
"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": null,
"last_measurement_time_formatted": null,
"metric_last_moving_average_value_formatted": null,
"last_updated_time": "2022-08-04 14:29:48",
"total_forecast_amount_formatted": null,
"last_activity_time": null,
"last_annotation_text": null,
"last_commentary_text": null,
"element_dashboard_name": "New Local Filesystem External Content",
"is_empty_instance_ind": "N",
"metric_tile_display_pct_variance": null,
"report_rows": null,
"last_display_generation_time": "2022-08-22 21:34:32",
"last_file_updated_time": "",
"last_modified": "more_than_month",
"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": null,
"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": "Local File",
"enable_click_in_mobile_ind": "N",
"content_type": "Local File",
"global_total_view_count": "60",
"has_access": "Y"
}
],
"folder_items": []
}
3.2. Add Element to Folder
- Item: folder_element
- Methods: POST
- Enter any number
- Select JSON request and enter JSON providing the needed values for the following parameters:
- "folder_id": ID of the Folder
- "elements": ID of the element that needs to be added to the Folder
- Enter an API Token
- [Run request]
3.3. Bulk Add Folder Elements
Bulk adding Folder elements is not available in API toolkit but can be performed via direct API request to the /api/folder_element
endpoint:
$.ajax({
url: '/api/folder_element',
type: 'POST',
data: {
folder_id: '<Folder ID>',
elements:['<Element 1 ID>', '<Element 2 ID>']
}
});
Assigning values to the following parameters:
-
folder_id
: A string containing ID of the Folder -
elements
: An array of strings containing IDs of the elements that need to be added to the Folder
Example request:
$.ajax({
url: '/api/folder_element',
type: 'POST',
data: {
folder_id: "258",
elements:['1700', '122483']
}
});
3.4. Delete Element from Folder
Deleting an element from Folder is not available in API toolkit but can be performed via direct API request to the /api/folder_element
endpoint:
$.ajax({
url: '/api/folder_element',
type: 'DELETE',
data: {
folder_id: '<Folder ID>',
elements:['<Element 1 ID>', '<Element 2 ID>']
}
});
Assigning values to the following parameters:
-
folder_id
: A string containing ID of the Folder -
elements
:- A single string containing ID of the element, if only one element needs to be deleted, or
- An array of strings containing IDs of the elements that need to be deleted from the Folder
Example request:
$.ajax({
url: '/api/folder_element',
type: 'DELETE',
data: {
folder_id: "258",
elements:['1700', '122484']
}
});
4. Code Snippets
4.1. Folders Elements
The following API call returns an array of all Folder elements from Folders available on the Homepage:
$.ajax({
url: '/api/element?folder_items=Y',
type: 'GET',
dataType: 'json',
}).then(res=>{console.log(res.folderItems)})
The following API call returns an array of all Folder elements including the Folders hidden from the Homepage:
$.ajax({
url: '/api/element?folder_items=Y&all_folders=Y',
type: 'GET',
dataType: 'json',
}).then(res=>{console.log(res.folderItems)})