REST API Job Commands#

TIP

Add the following command after the username and password to receive more meaningful HTTP errors:

-w"\n%{http_code}\n"

This command can be added to each call.

Job Status#

Request Method - GET
Description - Returns the id and current status of a specified job.
URI Syntax - curl -u <username>:<password> -X GET 'http://<Spectrum-serverIP>:<port-number>/api/job-execution/<file-id>|<uuid>|<path>/status'

Example Response

For a job that has never been run:

{
  "status": "success",
  "job-status": "_NONE"
}

For a running job:

{
  "status": "success",
  "file-id": 48,
  "job-execution-id": 3,
  "job-status": "RUNNING",
  "start-time": "Sep 28, 2018 6:44:56 PM",
  "estimate-time":"11s",
  "job-progress":"0"
}

For a completed job:

{
  "status": "success",
  "file-id": 48,
  "job-execution-id": 3,
  "job-status": "COMPLETED",
  "start-time": "Sep 28, 2018 6:44:56 PM",
  "stop-time": "Sep 28, 2018 6:44:58 PM"
}

For a completed job with errors:

{
  "status": "success",
  "file-id": 46,
  "job-execution-id": 4,
  "job-status": "COMPLETED_WITH_WARNINGS",
  "start-time": "Sep 28, 2018 10:09:47 AM",
  "stop-time": "Sep 28, 2018 10:09:52 AM"
}

For a queued job:

{
  "status": "success",
  "file-id": 48,
  "job-execution-id": 4,
  "job-status": "QUEUED",
  "start-time": null
}

For a canceled job:

{
  "status": "success",
  "file-id": 48,
  "job-execution-id": 4,
  "job-status": "CANCELED",
  "start-time": null,
  "stop-time": "Sep 28, 2018 6:58:41 PM"
}

INFO: If the example job had been running and was then canceled, a "start-time" would also be displayed.

For a triggered job:

{
  "status": "success",
  "job-execution-id": 3,
  "job-execution-user": "analyst",
  "job-execution-trigger": "RESTAPI"
}

For a job that has been stopped:

There isn't a response if the job was successfully stopped.

For an error:

{
  "status": "failure",
  "reason": "File doesn’t exist or isn’t accessible with current permissions"
}

Job History#

Request Method - GET
Description - Returns a specified number of job status results for a job.
URI Syntax - curl -u <username>:<password> -X GET 'http://<Spectrum-serverIP>:<port-number>/rest/job-configuration/job-history/<job-configuration-id>?start=0&length=10'

Example Response

[
    {
        "id": 30,
        "jobStatus": "COMPLETED"
    },
    {
        "id": 27,
        "jobStatus": "COMPLETED"
    },
    {
        "id": 23,
        "jobStatus": "COMPLETED"
    }
]

Job Details#

Request Method - GET
Description - Returns data about a job including the job counters, failure count, status, start/stop time, successful record count, the jobConfigurationId, file-id, and uuid.
URI Syntax - curl -u <username>:<password> -X GET 'http://<Spectrum-serverIP>:<port-number>/rest/job-execution/job-details/<job-execution-id>'

Example Response

{
  "startTime": "Jul 18, 2018 1:46:38 PM",
  "stopTime": "Jul 18, 2018 1:47:03 PM",
  "jobStatus": "COMPLETED",
  "jobConfigurationId": 4,
  "file": {
    "id": 6,
    "uuid": "f8d450cd-f065-4abb-a232-27cd20c48c2b"
  },
  "successCount": 7,
  "failureCount": 0,
  "counters": {
    "IMPORT_RECORDS": 7,
    "IMPORT_PREVIEW_RECORDS": 7,
    "IMPORT_OUTPUT_BYTES": 4167,
    "IMPORT_DROPPED_SPLITS": 0,
    "IMPORT_DROPPED_RECORDS": 0
  }
}

List Active Jobs#

Request Method - GET
Description - Returns a list of all the active jobs in Spectrum. This list displays the job status, file name, job name, file ID, UUID, creation date, job execution ID, estimated time and start time.
URI Syntax - curl -u <username>:<password> -X GET 'http://<Spectrum-serverIP>:<port-number>/api/job-execution/list-running'

Example Response

[
  {
    "jobStatus": "RUNNING",
    "fileName": "Workbook1",
    "jobName": "Workbook job",
    "fileId": 5,
    "uuid": "73b2800b-ed90-47ef-abdc-ce516a980173",
    "creationDate": 1580808994422,
    "jobExecutionId": 3,
    "dapJobConfigurationId": 4,
    "estimatedTime": 0,
    "startTime": 1582878238075
  }
]

Trigger Job#

Request Method - POST
Description - Triggers a job to run.
URI Syntax - curl -u <username>:<password> -X POST 'http://<Spectrum-serverIP>:<port-number>/api/job-execution/<file-id>|<uuid>|<path>/trigger'

Example Response

{
  "status": "success",
  "job-execution-id": 11,
  "job-execution-user": "admin",
  "job-execution-trigger": "RESTAPI"
}

Sequential Trigger Job#

Request Method - POST
Description - Triggers multiple Spectrum jobs to run in a defined sequence. For this to happen, the Workbooks within this dependency chain all have to be data-driven (which can be set in Workbook configuration). The request triggers the provided artifacts, as well as all downstream dependencies. The new API version supports the setting of Workbook variables.
URI Syntax - curl -X POST -u <user>:<password> -d '{ variables : { "foo": "fooValue" }, "fileIds" : [4, ]}' -H "Content-Type: application/json"

Example Response

{
  "status": "success",
  "execution-plan": [
    {
      "job-configuration-name": "apache_log",
      "job-configuration-id": 3,
      "trigger": true,
      "job-execution-id": 16
    },
    {
      "job-configuration-name": "categorization",
      "job-configuration-id": 4,
      "trigger": true,
      "job-execution-id": 17
    }
  ]
}

Stop Job#

Request Method - POST
Description - Stops a job that is running.
URI Syntax - curl -u <username>:<password> -X POST 'http://<Spectrum-serverIP>:<port-number>/api/job-execution/<file-id>|<uuid>|<path>/stop'
Example Response - This command doesn't return a response.

Delete Job#

INFO

If your file name includes " " (empty spaces), replace those spaces with "+".

Request Method - DELETE
Description - Removes a job from Spectrum.
URI Syntax - curl -u <username>:<password> -X DELETE 'http://<Spectrum-serverIP>:<port-number>/rest/data/<data-id>'

Example Response

No job or data available:

{
  "status": "failure",
  "reason": "Entity of type 'Data' with id '272' not found."
}

Job and data are available, but data has already been deleted or marked for deletion:

{
  "status": false
}

Job and data have been marked for deletion:

{
  "status": true
}