Thing Jobs API

The Thing Jobs REST API is used to manage thing jobs.

GENERATE_UPLOAD_URL

Required role: ReadWrite
Required privilege: ThingJobs.CREATE on the specified domain

Each job needs to have a job document. Use this endpoint to generate a signed url that can be used for a HTTP PUT request with the document data.

API Endpoint: [POST]: thing-jobs/documents

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Body

documentName: A human readable document name. Maximum length is 64 characters. required
domain: The id of the domain that the job document should belong to. required

Example body

{
    "documentName": "My document",
    "domain": "root"
}

Response

documentName: The provided document name.
documentId: The id that the uploaded document will get. Use this value in the CREATE endpoint.
signedUrl: The signed url that can be used to upload a document through a HTTP PUT call.

Example usage

The response of a successful GENERATE_UPLOAD_URL request contains documentName, documentId and signedUrl parameters.

Upload a document

With curl:

curl -H 'Content-Type: application/json' -T '<your-json-document>' '<signedUrl>'

Off course other programs than curl can be used, but the Content-Type and Content-Length headers should be provided.

Create a job

Refer to the CREATE endpoint below, use the documentId as the jobDocumentId parameter.

Errors

Key	Property	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized for the operation.
`PROPERTY_REQUIRED`		Returned if a required parameter is missing.
`INVALID_ARGUMENTS`		Returned if a parameter does not fulfil requirements.
`NOT_AUTHORIZED_DOMAIN`	`domain`	Returned if the domain does not exist.

CREATE

Required role: ReadWrite
Required privilege: ThingJobs.CREATE on the specified domain
Required privilege: ThingJobs.READ on the specified domain
Optional privilege: ThingGroups.READ required if groups is included in the targets of the request
Optional privilege: Things.READ required if things is included in targets part of the request

Create a job.

There are two strategies for selecting targets for a jobs: continuous and snapshot. When a snapshot job is created, it will execute for all targets and then be completed. When a continuous job is created, it will execute for all targets. If a thing is later added to a group in the target list, the job will execute for the new thing as well. Ergo, a continuous job is never completed. These strategies are referred to as targetSelection below.

API Endpoint: [POST]: thing-jobs/jobs

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Body

domain: The domain the job is created on, must be the same as the job document’s domain. required
description: A job description. required
jobDocumentId: The id of the job document, returned by the GENERATE_UPLOAD_URL endpoint. required
targets:
- things[]: A list of thing id’s that should execute the job. optional
- groups[]: A list of thing group id’s that should execute the job. optional
targetSelection: Should be either “CONTINUOUS” or “SNAPSHOT”. See explanation above. required
maximumPerMinute: The maximum number of things that should start to execute the job in a minute. Should be an integer between 1 and 1000. optional

Either targets.things or targets.groups has to be provided. The maximum number of targets (meaning things and groups) is 100.

Example payload with specific Things as a target

This payload would require the optional privilege Things.READ on the domain where myThingName exists.

{
    "domain": "myDomain",
    "description": "This is a job description",
    "jobDocumentId": "someId12389123981239",
    "targets": {
        "things": ["myThingName"]
    },
    "targetSelection": "SNAPSHOT",
    "maximumPerMinute": 10
}

Example payload for Thing Groups as a target

This payload would require the optional privilege ThingGroups.READ on the domain where the Thing Group(s) exist.

{
    "domain": "myDomain",
    "description": "This is a job description",
    "jobDocumentId": "someId12389123981239",
    "targets": {
        "groups": ["myThingGroupName"]
    },
    "targetSelection": "SNAPSHOT",
    "maximumPerMinute": 10
}

Response

jobId: A generated id for the job.
domain: The job’s domain.
description: The description.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`PROPERTY_REQUIRED`			Returned if a required parameter is missing.
`INVALID_ARGUMENTS`			Returned if a parameter does not fulfil requirements.
`FILE_NOT_FOUND`			Returned if the job document does not exist.
`THING_NOT_FOUND`			Returned if a targeted thing does not exist.
`THING_GROUP_NOT_FOUND`			Returned if a targeted thing group does not exist.

CANCEL

Required role: ReadWrite
Required privilege: ThingJobs.UPDATE on the domain specified in the job document

Cancel a job.

API Endpoint: [PATCH]: thing-jobs/jobs/{jobId}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path

jobId: The id of the thing type to get. required

Body

comment: A comment. optional

Example body

{
    "comment": "Replaced by other job"
}

Response

jobId: The id of the job.
description: The description of the job.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`PROPERTY_REQUIRED`			Returned if a required parameter is missing.
`INVALID_ARGUMENTS`			Returned if a parameter does not fulfil requirements.
`THING_JOB_NOT_FOUND`			Returned if the job does not exist.

DESCRIBE

Required role: Read
Required privilege: ThingJobs.READ on the domain specified in the job document

Describe a job.

API Endpoint: [GET]: thing-jobs/jobs/{jobId}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path

jobId: The id of the job. required

Response

jobId: The job id,
description: The job description.
comment: A comment provided when the job was updated.
status: The job status.
targetSelection: The target selection strategy of the job, either "CONTINUOUS" or "SNAPSHOT".
createdAt: The timestamp when the job was created.
lastUpdatedAt: The timestamp when the job was last updated.
completedAt: The timestamp when the job was completed.
targets: A map of the job targets.
- groups[]: A list of thing group names processing the job.
- things[]: A list of thing names processing the job.
jobProcessDetails: A map detailing the job processing.
- numberOfCanceledThings: The number of things that have canceled execution of the job.
- numberOfFailedThings: The number of things that have failed execution of the job.
- numberOfInProgressThings: The number of things that are executing of the job.
- numberOfQueuedThings: The number of things that have queued execution of the job.
- numberOfRejectedThings: The number of things that have rejected execution of the job.
- numberOfRemovedThings: The number of things that have been removed from the job.
- numberOfSucceededThings: The number of things that have succeeded execution of the job.
- processingTargets:
  - groups[]: A list of thing group names processing the job.
  - things[]: A list of thing names processing the job.
maximumPerMinute: The maximum number of things that will get the job in a minute.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`PROPERTY_REQUIRED`			Returned if a required parameter is missing.
`INVALID_ARGUMENTS`			Returned if a parameter does not fulfil requirements.
`THING_JOB_NOT_FOUND`			Returned if a targeted thing group does not exist.

LIST

Required role: Read
Required privilege: ThingJobs.READ on one or more domains containing a Thing Job
Optional privilege: ThingGroups.READ required if group is included in the query

List created jobs. Optional filter parameters can be added.

API Endpoint: [GET]: thing-jobs/jobs?status={status}&targetSelection={targetSelection}&group={group}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Query

status: The status for jobs, either "IN_PROGRESS", "CANCELED" or "COMPLETED". optional
group: the id of a thing group a job should belong to. optional
targetSelection: The target selection strategy for jobs, either "CONTINUOUS" or "SNAPSHOT".optional

Response

A list of jobs with attributes:

jobId: The id of the job.
status: The status of the job.
targetSelection: The target selection strategy for the job.
lastUpdatedAt: The timestamp when the job was last updated.
completedAt: If the job has status "COMPLETED", this will be timestamp when the job was completed.
canceledAt: If the job has status "CANCELED", this will be timestamp when the job was canceled.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`INVALID_ARGUMENTS`			Returned if a parameter does not fulfil requirements.
`THING_GROUP_NOT_FOUND`			Returned if the thing group to filter on does not exist.

LIST_JOB_EXECUTIONS

Required role: Read
Required privilege: ThingJobs.READ on the domain specified in the job document

Get a list job execution summaries for things in a job.

API Endpoint: [GET]: thing-jobs/jobs/{jobId}/job-executions

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path

jobId: The id of the job. required

Query

status: Filter the results to only contain summaries with a specific status. Valid statuses are “QUEUED”, “IN_PROGRESS”, “SUCCEEDED”, “FAILED”, “REJECTED”, “REMOVED” and “CANCELED”. optional

Example url

{ApiBaseUrl}/thing-jobs/jobs/{jobId}/job-executions?status=CANCELED

Response

A list of summaries, each containing:

jobId: The id of the job.
thingName: The name of the thing.
jobExecutionSummary:
- status: The status of the execution.
- queuedAt: The date when the job execution was queued.
- startedAt: The date when the job execution was started.
- lastUpdatedAt: The date when the job execution was last updated.
- executionNumber: A string with a unique id for this job execution.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`PROPERTY_REQUIRED`			Returned if a required parameter is missing.
`INVALID_ARGUMENTS`			Returned if a parameter does not fulfil requirements.
`THING_JOB_NOT_FOUND`			Returned if a targeted thing job does not exist.

ASSOCIATE_TARGETS_WITH_JOB

Required role: ReadWrite
Required privilege: ThingJobs.UPDATE on the domain specified in the job document

Associates a group with a continuous job.

API Endpoint: [POST]: thing-jobs/jobs/{jobId}/targets

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path

jobId: The id of the job. required

Body

targets: A list of thing group that define the targets of the job. required
comment: An optional comment string describing why the job was associated with the targets. optional

Example url

`{ApiBaseUrl}/thing-jobs/jobs/{jobId}/targets

Example body

{
    "targets": ["group1", "group2"],
    "comment": "an optional comment"
}

Response

jobId: The id of the job.
description: A job description.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`PROPERTY_REQUIRED`			Returned if a required parameter is missing.
`INVALID_ARGUMENTS`			Returned if a parameter does not fulfil requirements.
`THING_JOB_NOT_FOUND`			Returned if a targeted thing job does not exist.

GET_JOB_EXECUTION

Required role: Read
Required privilege: ThingJobs.READ on the domain specified in the job document

Get a job execution for a thing in a job.

API Endpoint: [GET]: thing-jobs/jobs/{jobId}/job-executions/{thingName}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path

jobId: The id of the job. required
thingName: The name of the thing. required

Query

executionNumber: A number (consisting of a digit, starting at “1” for the first execution and increments for each new execution, which is used to specify a particular job execution on a particular device. optional If parameter not present, the job execution with the highest number will be returned.

Example url

{ApiBaseUrl}/thing-jobs/jobs/{jobId}/job-executions/{thingName}?executionNumber=1

Response

A job execution with attributes:

jobId: The id of the job.
status: The status of the job execution (IN_PROGRESS, QUEUED, FAILED, SUCCESS, CANCELED, or REJECTED).
queuedAt: The time, in milliseconds since the epoch, when the job execution was queued.
startedAt: The time, in milliseconds since the epoch, when the job execution started.
lastUpdatedAt: The time, in milliseconds since the epoch, when the job execution was last updated.
executionNumber: A number (consisting of the digits “0” through “9” which is used to specify a particular job execution on a particular device.
versionNumber: The version of the job execution. Job execution versions are incremented each time they are updated by a device.
statusDetails: A collection of name/value pairs that describe the status of the job execution.
forceCanceled: Will be true if the job execution was canceled with the optional force parameter set to true.
approximateSecondsBeforeTimedOut: The estimated number of seconds that remain before the job execution status will be changed to TIMED_OUT. The actual job execution timeout can occur up to 60 seconds later than the estimated duration.

NOTE statusDetails is returned if the device decides to. When the device is finished executing the job, it calls the UpdateJobExecution MQTT API. If the job was successful, set status to SUCCEEDED and, in statusDetails in the message payload, add other information about the job as name/value pairs. The in progress and step timers end when job execution is complete.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`PROPERTY_REQUIRED`			Returned if a required parameter is missing.
`INVALID_ARGUMENTS`			Returned if a parameter does not fulfil requirements.
`THING_JOB_NOT_FOUND`			Returned if a targeted thing job does not exist.

CANCEL_JOB_EXECUTION

Required role: ReadWrite
Required privilege: ThingJobs.UPDATE on the domain specified in the job document

Cancel a job execution for a thing in a job.

API Endpoint: [PATCH]: thing-jobs/jobs/{jobId}/job-executions/{thingName}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path

jobId: The id of the job. required
thingName: The name of the thing. required

Query

force: false (default) or true. optional
expectedVersion: A number (consisting of the digits “0” through “9” which is used to specify a particular job execution on a particular device. optional

When force is true, you can cancel a job execution which is “IN_PROGRESS”.

Example url

{ApiBaseUrl}/thing-jobs/jobs/{jobId}/job-executions/{thingName}?expectedVersion=1&force=true

Response

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`PROPERTY_REQUIRED`			Returned if a required parameter is missing.
`INVALID_ARGUMENTS`			Returned if a parameter does not fulfil requirements.
`THING_JOB_NOT_FOUND`			Returned if a targeted thing job does not exist.

DELETE_JOB_EXECUTION

Required role: ReadWrite
Required privilege: ThingJobs.DELETE on the domain specified in the job document

Delete a job execution for a thing in a job.

API Endpoint: [DELETE]: thing-jobs/jobs/{jobId}/job-executions/{thingName}/executionNumber/{executionNumber}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path

jobId: The id of the job. required
thingName: The name of the thing. required
executionNumber: The name of the thing. required

Query

force: false (default) or true. optional

When force is true, you can delete a job execution which is “IN_PROGRESS”.

Example url

{ApiBaseUrl}/thing-jobs/jobs/{jobId}/job-executions/{thingName}?expectedVersion=1&force=true

Response

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`PROPERTY_REQUIRED`			Returned if a required parameter is missing.
`INVALID_ARGUMENTS`			Returned if a parameter does not fulfil requirements.
`THING_JOB_NOT_FOUND`			Returned if a targeted thing job does not exist.

DELETE

Required role: ReadWrite
Required privilege: ThingJobs.DELETE on the domain specified in the job document

Delete a job.

API Endpoint: [DELETE]: thing-jobs/jobs/{jobId}?force={force}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Query Parameters

force: true or false (default). optional

When force is true, you can delete a job which is “IN_PROGRESS”.
Otherwise, you can only delete a job which is in a terminal state (“COMPLETED” or “CANCELED”) or an exception will occur.

NOTE Deleting a job execution which is “IN_PROGRESS”, will cause the device to be unable to access job information or update the job execution status. Use caution and ensure that the device is able to recover to a valid state.

Example request

DELETE {ApiBaseUrl}/thing-jobs/jobs/myJobId?force=true

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`PROPERTY_REQUIRED`			Returned if a required parameter is missing.
`INVALID_ARGUMENTS`			Returned if a parameter does not fulfil requirements.
`THING_JOB_NOT_FOUND`			Returned if a targeted thing job does not exist.

GET_JOB_DOCUMENT

Required role: Read
Required privilege: ThingJobs.READ on the domain specified in the job document

Get job document

API Endpoint: [GET]: thing-jobs/documents/{jobId}

Request

Headers

Authorization: The Authorization token returned from /auth/login
x-api-key: The API Key to identify the request

Path

jobId: The id of the job. required

Example url

{ApiBaseUrl}/thing-jobs/documents/{jobId}

Response

A job document:

document: The job document.

Errors

Key	Params	Property	Description
`NOT_AUTHORIZED`			Returned if the user is not authorized for the operation.
`PROPERTY_REQUIRED`			Returned if a required parameter is missing.
`INVALID_ARGUMENTS`			Returned if a parameter does not fulfil requirements.
`THING_JOB_NOT_FOUND`			Returned if the job does not exist.