HomeGuidesRecipesAPI ReferencePython SDK
Alation Help Center
API Reference

ULM with Article ID

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

POST
/api/v2/bulk_metadata/custom_fields/<template_name>/<object_type>?<params>

Path Parameters

NameRequiredDescription
<template_name>YesName of the template, custom fields have been applied to.
NOTE: Template name can be default or any other name given to a custom template created by an Alation user for articles. More information on using a template name for different object types is given below.
a) Use the name given to a user-created custom template for the article object type and use default for all supported object types.
b) article object type can also use default if they do not have any custom template applied to them.

For Example:
The URL to update/create articles with custom template Business Glossary will look like:
https://<your_host>/api/v2/bulk_metadata/custom_fields/Business%20Glossary/article
<object_type>YesThe type of object to update or create.
<object_type> can only be article

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

URL Parameters

NameRequiredDefaultDescription
create_newNotrueSpecifies if a new object should be created in case the object passed is not present in the Alation catalog.
create_new can have one of the following values:
true
false
create_new=true specifies that a new object should be created for objects not existing in Alation catalog.
replace_valuesNofalseSpecifies if the custom field values passed to the API request should be replaced with the existing values or should be added to the existing list of values.
replacevalues can have one of the following values:
true
false
NOTE: This parameter works only for object, people set and reference custom fields. Also, if _existing
title and description of an object needs to be updated, this field must be set to true.

Data Parameters

NameRequiredDescription
keyYes - when creating new articlesRepresents the title of the article the fields belong to.
article_idNoCan be used to filter articles during updating fields of existing articles
descriptionNoDescription of an article
<custom_field_name>NoName of the custom field.

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

HTTP HeaderValue
TOKEN<your_token>

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": {}
}
NameDescription
new_objectsRepresents the number of new objects created.
NOTE: Valid in case of article
updated_objectsRepresents the number of objects updated
number_receivedRepresents the number of objects received in the request
error_objectsA list of keys for objects with errors
errorAn error message
created_articlesKey value pairs representing newly created articles, with article_id as key and title as value
custom_fields_updatedA list of updated custom fields in the form of {<article_id> : {<field> : <value>}}

Error_Objects

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

Error_ObjectDescription
Neither article_id nor key foundAt least one of the primary keys (title or article_id) is required
Article id was already usedReoccurrence of an article_id in the same request
Wrong key or article_id formatarticle_id should be integer and come from an article creation response
Cannot create object since article_id is auto generated and should be emptyOccurs when article_id is specified for article creation
Cannot create object if key(title) is emptyArticle title/key is required for article creation

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())