Job API

Jobs are started (e.g. to import or export metadata) and run in the background. Jobs allow certain processes to be run asynchronously without blocking the caller of the job. The result of a job can be queried or downloaded when the job has completed.

Note

In the following examples, the server https://www.myserver.com and the database test as well as the scheme MyModel are used for illustration purposes (e.g. in the path https://www.myserver.com/api/test/schemes/MyModel). The server and the database as well as the scheme must be replaced accordingly in all actual requests. Depending on the configuration, the URL may also have to be extended by the context path (e.g. https://www.myserver.com/dataspot/api/test/schemes/MyModel).

The job API is a programming interface that allows jobs to be queried and controlled.

Asynchronous upload and download

An asynchronous upload starts a job and returns the corresponding job ID. The job runs in the background and performs the upload. The status of the job can be polled with the job ID. When the job has completed, the statistics and any existing logs can be queried.

An asynchronous download starts a job and returns the corresponding job ID. The job runs in the background and performs the download. The status of the job can be polled with the job ID. When the job has completed, the data can be downloaded and the statistics and any existing logs can be queried.

Methods

A job is identified by a unique job ID. The job ID is returned when the job is started and must be used in all subsequent requests.

The job API supports the following HTTP methods and endpoints.

`/statistics`

The status and statistics of a job with the job ID id can be queried with GET /jobs/id/statistics:

GET /api/test/jobs/id/statistics HTTP/1.1
Host: www.myserver.com

The HTTP status code indicates whether the job is still running or has completed:

HTTP status code	Description
`200`	The job has completed
`202`	The job is still running

The HTTP message contains the current status of the job and a list of statistics:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "messages": [
        {
            "icon": "solid-circle-check",
            "level": "INFO",
            "message": "*Create BusinessObjects.json* successful (00:00:00)."
        },
        {
            "dateGenerated": 1685224497160,
            "icon": "file-code",
            "level": "INFO",
            "message": "105 objects exported."
        }
    ],
    "status": "COMPLETED"
}

`/download`

The data provided by a completed job with the job ID id can be downloaded with GET /jobs/id/download:

GET /api/test/jobs/id/download HTTP/1.1
Host: www.myserver.com

The HTTP message contains the downloaded data. The <media type> and the <filename> depend on the options (format, report, target database, etc.) specified when starting the asynchronous download.

HTTP/1.1 200 
Content-Type: <media type>
Content-Disposition: filename="<filename>"

`/stop`

A job with the job ID id can be stopped with PUT /jobs/id/stop:

PUT /api/test/jobs/id/stop HTTP/1.1
Host: www.myserver.com

The HTTP message indicates whether the job could be stopped successfully:

HTTP message	Description
`true`	The job was stopped successfully
`false`	The job couldn't be stopped (job not running, unknown job ID, etc.)

`/logs`

The logs of a job with the job ID id can be queried with GET /jobs/id/logs:

GET /api/test/jobs/id/logs HTTP/1.1
Host: www.myserver.com

The HTTP message contains a list of messages:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "totalCount": 1,
    "data": [
        {
            "dateGenerated": 1685213572610,
            "level": "ERROR",
            "message": "BusinessObject.inCollection, line: 209: Asset *Organizations* was not found in Business data model *BusinessObjects*!"
        }
    ]
}

Examples

For the following examples the open source tool curl is used. Alternatively, any library that can communicate over HTTP is also suitable.

Note

The job API requires appropriate login credentials (e.g. jdoe and s3cr3t). Depending on the authentication method (Login ID and password, Single sign-on, Same sign-in, OpenID Connect) and used tools (e.g. curl), different mechanisms (e.g. basic authentication, bearer token) may be necessary to provide the credentials.

The report Metadata_pdf.xsl is started asynchronously in the model MyModel:

curl -X POST -u jdoe:s3cr3t https://www.myserver.com/api/test/schemes/MyModel/download?xsl=Metadata_pdf.xsl

POST /api/test/schemes/MyModel/download?xsl=Metadata_pdf.xsl HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200 OK
Content-Type: application/json

{ "id":"5373479c-d029-4f01-b1a8-703822138d95" }

The returned job ID is used to poll the status of the job and wait for it to complete:

curl -X GET -u jdoe:s3cr3t https://www.myserver.com/api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/statistics

GET /api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/statistics HTTP/1.1
Host: www.myserver.com

The HTTP status code 202 (Accepted) indicates the job is still running:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "messages": [
    {
      "icon": "spin-arrows-spin",
      "level": "WARNING",
      "message": "*Create Metadata Report* in progress... (00:00:01)"
    }
  ],
  "status": "STARTED"
}

The HTTP status code 200 (OK) indicates the job has completed:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "messages": [
    {
      "icon": "solid-circle-check",
      "level": "INFO",
      "message": "*Create Metadata Report* successful (00:00:02)."
    },
    {
      "dateGenerated": 1685232894059,
      "icon": "file-pdf",
      "level": "INFO",
      "message": "Generating PDF report (1 MB)"
    }
  ],
  "status": "COMPLETED"
}

When the job has completed, the generated report can be downloaded and saved in a file:

curl -X GET -u jdoe:s3cr3t -o "Metadata Report_MyModel.pdf" https://www.myserver.com/api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/download

GET /api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/download HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200 OK
Content-Type: application/pdf

Content-Disposition: filename="Metadata Report_MyModel.pdf"

Alternatively, the running job can be stopped:

curl -X PUT -u jdoe:s3cr3t https://www.myserver.com/api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/stop

PUT /api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/stop HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200 OK
Content-Type: application/json

true

Asynchronous upload and download​

Methods​

/statistics​

/download​

/stop​

/logs​

Examples​