DeviceJobs

The following resources are applicable:

/deviceJobs

Mount Point: /v2/deviceJobs

POST

Creates and schedule a Device Job based on the information in the DeviceJobCreator.

Target ClientIDs

In a Device job target clientIDs can be specified specifically and/or specifying tagIDs that groups them. It is possible to use any combination of both declaration, and duplicates are automatically detected and removed.

Job Type

The following operation are supported in a Device Job:

Configuration Update

This Job is used to change the configuration of one ore more components on all target ClientIDs.
The configuration file must be specified on the JobAttachment field, while anything wrote in the jobPropertiesMap field is ignored.
Please refer to JobAttachmentCreator documentation.

Software Install

This Job is used to install or update a package on all target ClientIDs that support DEPLOY-V1 application.
The package to be installed via:

Software Install V2

This Job is used to install or update a package on all target ClientIDs that support DEPLOY-V2 application.
Properties needs to be added to jobPropertiesMap field. Available properties for this type of job are listed below.

Name Type Mandatory Default Value Description
dp.uri String Yes The deployment package (or .sh script) URI where to download the file.
dp.name String yes The deployment package name to install.
This is used on the device to search for already installed version of this package.
dp.version String Yes The deployment package version to install.
This is used on the device to manage the updates of the packages.
dp.download.protocol String No HTTP The protocol used to download the file from the URI
Available protocols:
  • HTTP (which includes both HTTP and HTTPS)
dp.download.block.size Integer No null The size in Byte of the blocks used to download the DP via HTTP.
dp.download.block.delay Integer No 0 Delay in ms between block transfers.
dp.download.notify.block.size Integer No null The interval of Bytes between notification messages.
dp.download.timeout Integer No 60000 The timeout in ms to be used to download the DP via HTTP.
dp.download.resume Boolean No true Resume HTTP transfer if supported by the server.
dp.download.force Boolean No true Force the download of the file, even if it has been already downloaded and saved to the file system of the device.
dp.download.username String No null Username for password protected http download. No authentication will be tried if username is not present.
dp.download.password String No null Password for password protected http download. No authentication will be tried if password is not present.
dp.download.hash String No null The algorithm and value of the hash of the file used to verify the integrity of the download.
The format is of this property is: {algorithm}:{hashValue}
Available algorithm:
  • MD5
Examples:
  • MD5:46cbc7f212b94187cb6480fe9429a89c
dp.install Boolean No true Whether the package should be immediately installed after being downloaded.
dp.install.system.update Boolean No false Mark this install as a system install.
The device needs to know if this is a system update rather than a bundle/package update.
dp.install.verifier.uri String No null The verifier script URI to run after the installation of the system update.
If not given the device will consider the operation successfully completed if is able to run the system update.
dp.reboot Boolean No false Whether the system should be rebooted as part of the package installation process.
dp.reboot.delay Integer No 0 Delay in ms after which the device will be rebooted. Only meaningful if dp.reboot==true.

Software Uninstall

This Job is used to uninstall a package on all target Client IDs.
The package name must match the package name installed on the target client IDs that support DEPLOY-V1 application.
The package name must be declared in the JobProperties field. Anything set in JobAttachment field will be ignored.
Properties needs to be added to jobPropertiesMap field. Available properties for this type of job are listed below.

Name Type Mandatory Default Value
packageName String Yes

Software Uninstall V2

This Job is used to uninstall a package on all target ClientIDs that support DEPLOY-V2 application.
Properties needs to be added to jobPropertiesMap field. Available properties for this type of job are listed below.

Name Type Mandatory Default Value Description
dp.name String Yes The deployment package symbolic name to uninstall.
This is used on the device to select which package will be uninstalled.
dp.reboot Boolean No false Whether the system should be rebooted as part of the package uninstall process.
dp.reboot.delay Integer No 0 Delay in ms after which the device will be rebooted. Only meaningful if dp.reboot==true.

Command

This Job is used to execute a remote command on the target device.
The command must be a recognized command by the OS installed on your device. The working directory of the execution will be /tmp/ of the device.
It is possible to attach a file to this job that will be uploaded to the target device into /tmp/ directory. The file attached must be in a valid .zip compressed format, and it will be automatically decompressed by the device on receiving.

The command must be declared in the JobProperties field. The optional file attached must be specified on the JobAttachment field. Please refer to JobAttachmentCreator documentation.
Is not possible to concatenate more command using | (pipe) or > (close angular parenthesis).
For example the command "cat text.txt | grep test" does not work as concatenation of both commands, but all string except the first will be passed as parameters of the first string, that represent the command, with the result of executing cat of four files.
To achieve concatenation of parameters or more complicated executions please create a script and add it as attachment of the job and then use the command to run the script.

Properties needs to be added to jobPropertiesMap field. Available properties for this type of job are listed below.

Name Type Mandatory Default Value
command String Yes

Job Scheduling

There are two way to define the scheduling for a device job:

Simple scheduling

This scheduling needs:

Cron scheduling

This scheduling needs:

Request Body

element: deviceJobCreator
media types: application/xml
application/json

(no documentation provided)

Response Body

element: deviceJob
media types: application/xml
application/json

(no documentation provided)

GET

Returns the list of all Device Job of the current account with pagination.

Parameters

name description type default
displayName If specified result are filtered by display name. Display name is not unique so more than one result can be obtained. query
useLike If false the method matches the whole display name. If true the method matches all display names that starts with the specified display name. query false
limit Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 50
offset Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 0

Response Body

element: deviceJobsResult
media types: application/xml
application/json

The list of all Device Job of the current account

/deviceJobs/{deviceJobId}

Mount Point: /v2/deviceJobs/{deviceJobId}

The following operations are supported on this resource:

GET

Return the device job specified in the path parameter

Parameters

name description type default
deviceJobId (no documentation provided) path

Response Body

element: deviceJob
media types: application/xml
application/json

The requested device job

PUT

Updates the max number of retries for the specified device job.

The number set must greater of the current retries.

Parameters

name description type default
deviceJobId (no documentation provided) path

Request Body

element: deviceJob
media types: application/xml
application/json

(no documentation provided)

Response Body

element: deviceJob
media types: application/xml
application/json

(no documentation provided)

DELETE

Deletes the device job specified in the path parameter and related data of executions and target clientIDs.

Parameters

name description type default
deviceJobId (no documentation provided) path

/deviceJobs/{deviceJobId}/executions

Mount Point: /v2/deviceJobs/{deviceJobId}/executions

GET

Return the list of the executions for the specified Device Job supporting pagination. The device job executions contains the log of the execution.

Parameters

name description type default
deviceJobId (no documentation provided) path
fetchLogs (no documentation provided) query true
limit Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 50
offset Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 0

Response Body

element: deviceJobExecutionsResult
media types: application/xml
application/json

(no documentation provided)

/deviceJobs/{deviceJobId}/executions/{deviceJobExecutionId}/sendStopSignal

Mount Point: /v2/deviceJobs/{deviceJobId}/executions/{deviceJobExecutionId}/sendStopSignal

POST

Send a stop signal to the device job execution. The stop signal will be captured only at next target, so is not possible to stop the device job during the current item processed.

Be careful that stopping a device job can be harmful for the target devices

Parameters

name description type default
deviceJobId the device job id to stop path
deviceJobExecutionId (no documentation provided) path

/deviceJobs/{deviceJobId}/targets

Mount Point: /v2/deviceJobs/{deviceJobId}/targets

GET

Return the list of the target of the specified device job supporting pagination. It also supports filtering by DeviceJobTargetStatus. If not specified all DevicesJobTargetStatus are selected.

Parameters

name description type default
deviceJobId (no documentation provided) path
deviceStatuses (no documentation provided) query
limit Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 50
offset Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 0

Response Body

element: deviceJobTargetsResult
media types: application/xml
application/json

(no documentation provided)

/deviceJobs/{deviceJobId}/targets/{targetClientId}

Mount Point: /v2/deviceJobs/{deviceJobId}/targets/{targetClientId}

GET

Get the information for the specified Target Client ID in the specified Device Job

Parameters

name description type default
deviceJobId (no documentation provided) path
targetClientId (no documentation provided) path

Response Body

element: deviceJobTarget
media types: application/xml
application/json

(no documentation provided)