Managing jobs in Management API

Managing jobs in Management API#

This article documents how to list current jobs, list past jobs, obtain a status of jobs in progress, and how to stop jobs with the Management API.

Listing jobs#

Listing all jobs in an instance#

Use the API call documented in this section to list all currently running and scheduled jobs (for example, fetch jobs) in a whole instance.

To list all running and scheduled jobs, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/jobs

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/jobs/' \
--header 'Authorization: Token {{KEY}}'

The response to this request includes the state_label parameter with one of the following values assigned:

  • Scheduled

  • Running

  • Success

  • Cancelled

  • Failed

  • Discarded - this status is set in the following cases:

    • If a preceding job failed or was cancelled, the follow up jobs are discarded.

    • If a job does not start running within 2 days of the fetch start, it is discarded.

    • If a job is cancelled manually, it is discarded.

  • Stale - this status is not set currently. Generally, it can be used to label jobs that will not complete due to internal failures and lost or removed tasks.

Filtering the jobs#

You can filter the jobs returned from this endpoint with a number of parameters:

Parameter

Value

Description

datastream_id

{{DATASTREAM_ID}}

Use this parameter to list the jobs of a specific datastream.

start and end

Dates YYYY-MM-DD or timestamps YYYY-MM-DDT00:00:00Z

Use these parameters to list the jobs within a specific date or time range.

type

One of the options: Fetch, Enrich, Transfer

Use this parameter to list the jobs of a specific type.

For example, to list the jobs of a datastream, import the following request example as raw text to your HTTP client (such as Postman):

curl --location -g --request GET 'https://{{INSTANCE}}/api/jobs/?datastream_id={{DATASTREAM_ID}}/' \
--header 'Authorization: Token {{KEY}}'

For example, to list the jobs within a given date range, import the following request example as raw text to your HTTP client (such as Postman):

curl --location -g --request GET 'https://{{INSTANCE}}/api/jobs/?start=YYYY-MM-DD&end=YYYY-MM-DD' \
--header 'Authorization: Token {{KEY}}'

For example, to list the jobs within a more specific time rangeby using timestamps, import the following request example as raw text to your HTTP client (such as Postman):

curl --location -g --request GET 'https://{{INSTANCE}}/api/jobs/?start=YYYY-MM-DDT00:00:00Z&end=YYYY-MM-DDT00:00:00Z' \
--header 'Authorization: Token {{KEY}}'

For example, to list the jobs of a certain type, for example Fetch, import the following request example as raw text to your HTTP client (such as Postman):

curl --location -g --request GET 'https://{{INSTANCE}}/api/jobs/?type=Fetch' \
--header 'Authorization: Token {{KEY}}'

Obtaining the status of a job in progress#

To obtain a status of a job in progress, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/jobs/{{JOB_ID}}/imported/

    Find the value of JOB_ID parameter in the response of the API request described in the previous section. In this response, JOB_ID parameter is named as id.

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/jobs/{{JOB_ID}}/imported/' \
--header 'Authorization: Token {{KEY}}'

Stopping jobs#

To stop a job, list the currently running jobs, and find the JOB_ID of the job to stop. You can only stop jobs in the fetch stage.

To stop a job using JOB_ID, follow these steps:

  1. Create a POST request to the following endpoint:

    https://{{INSTANCE}}/api/jobs/{{JOB_ID}}/stop/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request POST 'https://{{INSTANCE}}/api/jobs/{{JOB_ID}}/stop/' \
--header 'Authorization: Token {{KEY}}'
Contents