Folder API

Prerequisites:

Table of contents:

  1. Access Admin > System > API Toolkit
  2. Configure Folder
    1. Get Folder
    2. Create Folder
      1. Create Sub-Folder
    3. Update Folder
      1. Update Sub-Folder
      2. Copy Or Move Folder
    4. Delete Folder
  3. Configure Folder Elements
    1. Get Folder Elements
    2. Add Element to Folder
    3. Bulk Add Folder Elements
    4. Delete Element from Folder
  4. Code Snippets
    1. Folders Elements

1. Access Admin > System > API Toolkit

2. Configure Folder

2.1. Get Folder

  1. Item: folder
  2. Methods: GET
  3. Enter the ID of the Folder or Sub-Folder which data needs to be retrieved
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an object with Folder's data.

Example Response 

{
    "folder": {
        "id": "244",
        "name": "Robert Empty Folder",
        "visible": "Y",
        "visible_on_mobile": "Y",
        "include_in_export": "N"
    }
}

Fields Description

Field Name Value Type Description
id string The ID of the folder.
name string The name of the folder.
visible string Whether or not the folder is displayed on the homepage.
visible_on_mobile string Whether or not the folder is displayed in mobile app.
include_in_export string Whether or not the folder is included in the next scheduled migration.

2.2. Create Folder

  1. Item: folder
  2. Methods: POST
  3. Enter ID of an existing Folder
  4. 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
  5. Enter an API Token
  6. [Run request]
  7. The returned object contains an object with Folder's data.

2.2.1. Create Sub-Folder

  1. Item: folder
  2. Methods: POST
  3. Enter ID of an existing Folder
  4. Select JSON request and replace request with the following JSON providing the needed values:
{
    "parent_folder_id": "<Parent Folder ID>",
    "name": "<Sub-Folder name>"
}
  1. Enter an API Token
  2. [Run request]
  3. The returned object contains an object with Sub-Folder's data.

2.3. Update Folder

  1. Item: folder
  2. Methods: PUT
  3. Enter ID of the Folder which data needs to be updated
  4. Select JSON request and enter JSON with the updated Folder's data:
  5. Enter an API Token
  6. [Run request]
  7. The returned object contains an array with an object with the updated Folder's data.

2.3.1. Update Sub-Folder

  1. Item: folder
  2. Methods: PUT
  3. Enter ID of the Sub-Folder which data needs to be updated
  4. 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>"
}
  1. Enter an API Token
  2. [Run request]
  3. The returned object contains an array with an object with the updated Folder's data.

2.3.2. Copy Or Move Folder

  1. Item: folder
  2. Methods: PUT
  3. Enter ID of the Folder or Sub-Folder which needs to be copied or moved
  4. Actions:
    • Copy: A copy of the selected Folder is created inside of the target Folder
    • Move: Selected Folder is moved inside the target Folder
  5. Select JSON request and assign target_folder_id the ID of the target Folder
  6. Enter an API Token
  7. [Run request]

2.4. Delete Folder

  1. Item: folder
  2. Methods: DELETE
  3. Enter ID of the Folder or Sub-Folder which needs to deleted
  4. Enter an API Token
  5. [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.

  1. Item: folder_element
  2. Methods: GET
  3. Use one of the following parameters to retrieve Folder's data:
    • folder_id: Enter Folder ID
    • folder_name: Enter Folder Name
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an object with Folder elements' data.
  7. See Example Response  and Fields Description for details
Example Response 
{
    "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": []
}

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.
has_preview boolean Whether or not preview is enabled for 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_alert_text_news_type string The news type 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.2. Add Element to Folder

  1. Item: folder_element
  2. Methods: POST
  3. Enter any number
  4. 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
  5. Enter an API Token
  6. [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)})

Example Response 

[
   {
     "folder_item_id": "3644700",
     "folder_id": "171",
     "element_id": "1247",
     "segment_value_id": "1",
     "display_order": "1"
   },
   {
     "folder_item_id": "3644699",
     "folder_id": "171",
     "element_id": "1247",
     "segment_value_id": "2596",
     "display_order": "2"
   },
]

Fields Description

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.