Description

If an Alation API returns a job identifier, this API can be used to determine the status of a job. The job identifier could either be a name or an integer ID.

Since the PUT multiple Custom Field Values Async endpoint writes data to two data stores, it initiates two separate jobs. The Custom Field Values API response returns the ID of the first job. Use that ID to query the Jobs API. The response from the Jobs API returns the ID of the second job. You must track the status of each job separately.

URL

Replace {params} with one of the parameters mentioned in the URL parameters section.

URL Parameters

Headers

Replace <your_token> with your API token, which can be obtained from Get API Token.

Success Response

Content-Type: application/json

Status: 200 OK

Body

The response body will be a JSON object containing three properties: status, msg, and result.

Example:

{
  "status": "successful",
  "msg": "Job finished in 1.0 seconds at 2017-01-12 23:52:34.307327+00:00",
  "result": "{\"updated_objects\": 2, \"number_received\": 2, \"error_objects\": [], \"error\": \"\"}"
}

The three properties are described below.

status

Indicates the status of the job. Status can be one of the following:

• running - specifies that the job is not yet completed.
• successful - specifies that the job has been completed successfully.
• failed - specifies that the job has failed.

msg

Message describing the time taken to complete the job and the timestamp of job completion.

result

Contains detailed information about the job. The format of the result depends on the API that initiated the job.

The general format for most jobs will be a JSON object that has four properties:

• updated_objects - Represent the number of objects updated.
• number_received - Represents the number of objects received.
• error_objects - Contains information about any errors that might have occurred while executing the API (the one that has returned the job name) request.
• error - Specifies the number of errors ignored

If the the job was initiated with a PUT multiple Custom Field Values Async call, the result format will be a JSON object containing an array of message strings. Anytime there's an update on the status of the job, a new message will be added to the array. Since the Custom Field Values PUT endpoint writes data to two data stores, it initiates two separate jobs. Each result message for the first job indicates the job ID for the other job. You must track the status of each job separately.

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/v1/bulk_metadata/job"

# Get the status of the job returned from Lineage API
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/?name=bulk_api_job_2017-09-10-17-07-04-918251-00-00-386321a8-4157-453a-8cf0-a5e68641c2ea"

# Get the status of the job returned by push QLI API
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/?id=1"

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/v1/bulk_metadata/job'

# Add a url encoded job name
# Alernatively you can use urllib.quote(<job_name>) to urlencode the job name
job_name = "MetadataExtraction%231_Virtual_2017-01-12-23-52-34-272077-00-00-f11a1877-2ce7-4f6c-98e7-9bf5f8c0abf2"

# Get the details of a job with name
response = requests.get(BASE_URL + '/?name=' + job_name, headers=headers)
job_details = json.loads(response.text)
result = json.loads(job_details['result'])
print ("Status: %s, Message: %s, Updated Objects: %s" % (job_details['status'], job_details['msg'], result['updated_objects']))

# Get the details of a job with integer identifier
response = requests.get(BASE_URL + '/?id=1', headers=headers)
job_details = json.loads(response.text)
print ("Status: %s, Message: %s, Result: %s" % (job_details['status'], job_details['msg'], job_details['result']))

Sample Request and Response

Get the status of the job by its name

URL

Success Response

{
    "status": "successful",
    "msg": "Job finished in 2.0 seconds at 2017-10-05 19:36:48.374593+00:00",
    "result": "{\"updated_objects\": 1, \"number_received\": 2, \"error_objects\": [\"Line 1. Key: schema_b. Datasource id in key does not match the id in the request\"], \"error\": \"1 errors were ignored\"}"
}

Get the status of the job by its integer ID

URL

Success Response

{
    "status": "successful",
    "msg": "Job finished in 0.585993 seconds at 2017-11-30 18:59:10.445133+00:00",
    "result": "Bulk Query Ingestion Succeeded: 0 new events ingested, 1 previously-ingested events skipped."
}