## Overview In this guide, we will walk you through on how to update the descriptions on BI Folders. These steps will work for any BI object (Report, Data Source, BI Server, and etc.). Let's assume we want to update the description of a folder that's on our Tableau BI server. This guide will work for any BI source that's been cataloged by Alation. ### APIs being used - [BI Source (GBMv2) Overview](ref:bi-source-gbmv2-overview) - [Custom Field](ref:custom-field) - [Custom Field Values Overview](ref:custom-field-values-overview) - [APIAccessToken](ref:apiaccesstoken) \<- This guide assumes you have a valid access token ### Permissions Needed You will need a **Server Admin** role to do these steps. You can check the [APIs by Roles](doc:alation-apis-by-roles) for more details. ### Completed Code Below is the completed python code for this guide. [block:tutorial-tile] { "backgroundColor": "#018ff4", "emoji": "🦉", "id": "65f23c81c5b332002b2e59b2", "link": "https://developer.alation.com/v2024.1.1/recipes/update-custom-metadatadescriptions-for-bi-objects", "slug": "update-custom-metadatadescriptions-for-bi-objects", "title": "Update custom metadata/descriptions for BI Objects" } [/block] ## 1. Identify which object(s) we want to update ### Get BI Server ID We can use [GET a list of BI Servers](ref:getservers) to identify the BI Server ID that Alation uses. This can also be found in the URL. ![](https://files.readme.io/4df8862-bi_server_id.png "bi_server_id.png") ```python # if you get an error, on the command line type pip install requests import requests # setting the base_url so that all we need to do is swap API endpoints base_url = "CHANGEME" # api access key api_key = "CHANGEME" # setting up this access key to be in the headers headers = {"token": api_key} # api for bi server endpoint bi_server_api = "/integration/v2/bi/server/" bi_server_uri = "https://tableau2020." # make the API call res = requests.get(base_url + bi_server_api, headers=headers) # convert the response to a python dict. bi_servers = res.json() # iterate through our servers to find the one we need bi_server_id = 0 # would recommend creating a function for this action # vs what we're doing in this guide for serv in bi_servers: # matching on URI to find the one that starts with what we need if serv["uri"].startswith(bi_server_uri): bi_server_id = serv["id"] # in this example, our bi server ID = 23 print("The BI folder id for \"{}\" is {}". format(serv['title'], bi_server_id)) break ``` ### Get the BI Folders We can use the [GET a list of folders from a specified BI Server](ref:getfolders) on this BI Server. Now a folder in Alation can represent projects in Tableau, Work Spaces in PowerBI, and etc. Browse your BI Server and Alation to get a feel for how it is organized in Alation. ```python # this code is a continuation of the above code. bi_folder_name = "Ticket Sales" bi_folder_api = "/integration/v2/bi/server/{}/folder/".format(bi_server_id) res = requests.get(base_url + bi_folder_api, headers=headers) bi_folders = res.json() bi_folder_id = 0 for folder in bi_folders: # matching on folder name to find the one that starts with what we need if folder["name"].startswith(bi_folder_name): bi_folder_id = folder["id"] # in this example, our bi folder ID = 744 print("The BI folder id for \"{}\" is {}". format(bi_folder_name, bi_folder_id)) break ``` ## 2. Get the Custom Field IDs We need to get the custom field ID for our "Description", singular name, custom field. The "Description" field is also a "Rich Text" type. If you wanted to update more custom fields on a BI source, then get those additional IDs here. [GET multiple Custom Fields](ref:getcustomfields) In our URL parameters, we will specify the field type as "RICH_TEXT". ```python needed_cf_type = "RICH_TEXT" singular_field_name = "Description" # the custom field name we're looking for custom_field_api = "/integration/v2/custom_field/?field_type={}&limit=100&skip=0".format(needed_cf_type) res = requests.get(base_url + custom_field_api, headers=headers) custom_fields = res.json() custom_field_id = 0 for cf in custom_fields: # matching on folder name to find the one that starts with what we need if cf["name_singular"] == (singular_field_name): custom_field_id = folder["id"] # in this example, our bi folder ID = 4 print("The custom field \"{}\" the ID is {}". format(singular_field_name, custom_field_id)) break ``` ## 3. Update the description Alright! We have all of the needed ids. Let's go to update the Description. > **NOTE:** When updating Rich Text Fields, make sure you review [HTML Sanitization](ref:html-sanitization) for which HTML values are allowed. iframes are always a good work around when needed ;) ### Before API Update Here's our "Folder" right before the API call. ![](https://files.readme.io/ce188a5-desc_to_be_replaced.png "desc_to_be_replaced.png") ### Update Call ```python custom_field_value_api = "/integration/v2/custom_field_value/" data = [ { "field_id": custom_field_id, "otype": "bi_folder", "oid": bi_folder_id, "value": "

Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam tincidunt mauris eu risus.
Vestibulum auctor dapibus neque.

" } ] # Requests library makes it easy for us to convert a payload to json. res = requests.put(base_url + custom_field_value_api, headers=headers, json=data) print(res.json()) # if all went according to plan then, you should see a response that looks like # {'updated_field_values': 1, 'new_field_values': 0, 'field_values_received': 1} ``` ### After API Call And now we can see the updated description! ![](https://files.readme.io/89b965d-desc_after_put.png "desc_after_put.png") And as always.... [block:html] { "html": "

\n" } [/block]