Upload Logical Metadata with Article ID

🚧

Deprecation Notice

The Upload Logical Metadata (ULM) API will be deprecated in the 2024.3 release of Alation in early September. We recommend you move as soon as possible to the alternatives listed in the API Release Notes.

Description

This API allows you to upload values to titles, descriptions, stewards and custom fields for articles in the Alation catalog.

Custom fields are fields created in Alation's Customize Catalog interface.

Note:

Here are the key differences between this and the other Upload Logical Metadata endpoints:

1. This API can only be used for Article Overview
   
2. The API returns article_id values for newly created articles
   
3. The same article_id values can be used as primary keys to filter the desired articles during the subsequent requests to upload article-related logical metadata
   
4. This endpoint returns a list of updated fields and their new values
   

URL

Path Parameters

Replace with your list of parameters. Multiple parameters can be combined as PARAM1&PARAM2

URL Parameters

Data Parameters

NOTE: Please refer Custom Field Values Overview to know the format of data parameters in the request body.

Sample Request Body

{"article_id": "1", "description": "Description for article1 with steward", "steward":[{"key":"[email protected]", "type":"user"}]}
{"article_id": "10", "description": "Description of the new article", "steward":[{"key":"[email protected]", "type":"user"}]}
{"article_id": "10", "steward":[{"key":"[email protected]", "type":"user"}]}

NOTE:

1. Request body above is an example for /api/v2/bulk_metadata/custom_fields/Business%20Glossary/article API call. The request body should be a list of JSON objects separated by a new line. Each JSON object on a line corresponds to field values for a single article upload.
   

2. In Alation, you can recover deleted data sources and articles. As a result, if your request body includes an article id of a deleted article, its metadata will still be updated in the internal database. The updated values will become available in the catalog if this article is recovered.

Headers

Replace <your_token> with the API Token which can be obtained from getToken API call Generate Tokens for the Alation API.

Success Response

Content-Type: application/json

Status: 200 OK

Body

{
    "new_objects": 1,
    "updated_objects": 0,
    "number_received": 1,
    "error_objects": [],
    "error": "",
    "created_articles": {"1": "New Article"},
    "custom_fields_updated": {}
}

Error_Objects

New error objects (strings) introduced with the inclusion of article_id are as follows:

Error Response

Invalid Token

Status: 401 UNAUTHORIZED

Body

{
   "detail": "Authentication failed"
}

Missing Token Header

Status: 401 UNAUTHORIZED

Body

{
    "detail": "Authentication credentials were not provided."
}

Code Samples

cURL

#!/bin/bash

# This is an example token. Please replace this with your token.
API_TOKEN="2abcd-4c04-4c21-8692-eda27a877f90"

BASE_URL="https://alation.yourcompany.com/api/v2/bulk_metadata/custom_fields"

# Create an article if it does not exist
# The template applied is default article template. If the new article needs to be created under a custom template, replace 'default' with custom template name
curl -X POST "${BASE_URL}/default/article" -H 'content-type: application/json' -H "TOKEN: ${API_TOKEN}" -d '{"key":"database info article", "description":"This article has db info."}'

# Add a description and steward to an existing article
curl -X POST "${BASE_URL}/default/article" -H 'content-type: application/json' -H "TOKEN: ${API_TOKEN}" -d '{"article_id":"1", "description":"Data API Resource", "steward":[{"type":"user","key":"[email protected]"}]}'

# Add a custom field to an existing article
curl -X POST "${BASE_URL}/custom_template/article" -H 'content-type: application/json' -H "TOKEN: ${API_TOKEN}" -d '{"article_id":"1", "custom text":"My custom note on the article"}'

Python

import requests
import json

# This is an example token. Please replace this with your token.
headers = {'Token': '2abcd-4c04-4c21-8692-eda27a877f90'}
BASE_URL = 'https://alation.yourcompany.com/api/v2/bulk_metadata/custom_fields/'


# Upload custom field to article with custom template
# The custom field uploaded should be added to the custom template
data = {"article_id": "10", "max_salary": "20000", "related_articles": [{"type":"article", "key": "Employee names"}]}
response = requests.post(BASE_URL + 'Custom%20Template/article', json=data, headers=headers)
result = json.loads(response.text)
print ("Updated Objects: %s , New Objects: %s" % (result['updated_objects'], result['new_objects']))
for error in result['error_objects']:
	print (error)
print(result['custom_fields_updated'].items())

# Create an article with default template
# The custom field uploaded should be added to the custom template
data = {"key": "My New Article", "description": "Description of the new article"}
response = requests.post(BASE_URL + 'default/article', json=data, headers=headers)
result = json.loads(response.text)
print ("Updated Objects: %s , New Objects: %s" % (result['updated_objects'], result['new_objects']))
for error in result['error_objects']:
    print (error)
print (result['created_articles'].items())