DeviceJobs Resource

GET /deviceJobs

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

Example

GET /deviceJobs
Content-Type: */*
Accept: application/json

                
...
                
              

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

                
{
  "deviceJob" : [ {
    "status" : "WAITING_FOR_DEVICES",
    "cronRetryExpression" : "...",
    "endOn" : 12345,
    "cronNextRetryOn" : 12345,
    "retryEvery" : 12345,
    "resumed" : true,
    "requestTimeout" : 12345,
    "processOnConnect" : true,
    "sendWakeupSMS" : true,
    "wakeupTimeout" : 12345,
    "deviceInactivityTimeout" : 12345,
    "id" : 12345,
    "accountId" : 12345,
    "jobType" : "device_config_update",
    "displayName" : "...",
    "jobProperties" : "...",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "startOn" : 12345,
    "retryMaxAttempts" : 12345,
    "retryCount" : 12345,
    "optlock" : 12345
  }, {
    "status" : "RUNNING",
    "cronRetryExpression" : "...",
    "endOn" : 12345,
    "cronNextRetryOn" : 12345,
    "retryEvery" : 12345,
    "resumed" : true,
    "requestTimeout" : 12345,
    "processOnConnect" : true,
    "sendWakeupSMS" : true,
    "wakeupTimeout" : 12345,
    "deviceInactivityTimeout" : 12345,
    "id" : 12345,
    "accountId" : 12345,
    "jobType" : "device_certificate_update",
    "displayName" : "...",
    "jobProperties" : "...",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "startOn" : 12345,
    "retryMaxAttempts" : 12345,
    "retryCount" : 12345,
    "optlock" : 12345
  } ],
  "limitExceeded" : true
}
                
              

POST /deviceJobs

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

Target ClientIDs

Job Type

• Configuration Update: updates one or more components on the target ClientIDs
• Software Install: installs or updates a package on the target ClientIDs that supports DEPLOY-V1 application
• Software Install V2: installs or updates a package on the target ClientIDs that supports DEPLOY-V2 application
• Software Uninstall: uninstalls a package on the target ClientIDs that supports DEPLOY-V1 application
• Software Uninstall V2: uninstalls a package on the target ClientIDs that supports DEPLOY-V2 application
• Command: executes a remote command on the target ClientIDs

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:

• File: The package will be uploaded to EDC platform and then sent to all target device. The package file must be specified on the JobAttachment field. Please refer to JobAttachmentCreator documentation.
• URL: The package will be download directly by the target device using the URL given. Properties needs to be added to jobPropertiesMap field. Available properties for this type of job via URL are listed below.

Name	Type	Mandatory	Default Value
deployUrl	String	Yes

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.

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.

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.

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.

Job Scheduling

• Simple scheduling: defined by a start date and a fixed retry interval (and optional end date).
• Cron scheduling: defined by a Cron Expression and limited by a start date (and optional end date).

Simple scheduling

This scheduling needs:

• Start Date: the time of the first execution of this device job. This field is mandatory.
• End Date: the time after that the job must not be triggered anymore. This field is optional, and if not set the device job will stop when it reaches the max number of retries
• Max Number Of Retries: the number of times that a job can be re-triggered. If end date is set and is passed the job will not be triggered. This field is mandatory
• Retry Every: the interval in second between each retry. This field is mandatory. If set to 0 the job will be triggered only once and one time.

Cron scheduling

This scheduling needs:

• Start Date: the time after that executions of this device job will be triggered. This field is mandatory.
• End Date: the time after that the job must not be triggered anymore. This field is optional.
• Max Number Of Retries: the number of times that a job can be re-triggered. If end date is set and is passed the job will not be triggered. This field is mandatory.
• Cron Expression: this field represent the scheduling of this job following the Cron Expression syntax. Please refer to the Cron Expression Documentation.

Example

POST /deviceJobs
Content-Type: application/json
Accept: application/json

                
{
  "accountId" : 12345,
  "jobType" : "device_software_install",
  "jobDisplayName" : "...",
  "jobAttachment" : {
    "name" : "...",
    "contentType" : "BUNDLE",
    "body" : "..."
  },
  "targetClientIds" : [ "...", "..." ],
  "targetDeviceTag" : [ 12345, 12345 ],
  "startOn" : 12345,
  "endOn" : 12345,
  "timezoneInMins" : 12345,
  "cronRetryExpression" : "...",
  "retryEvery" : 12345,
  "retryMaxAttempts" : 12345,
  "selectAllClientIds" : true,
  "jobPropertiesMap" : {
    "parameter" : [ {
      "name" : "...",
      "value" : "..."
    }, {
      "name" : "...",
      "value" : "..."
    } ]
  },
  "requestTimeout" : 12345,
  "processOnConnect" : true,
  "sendWakeupSMS" : true,
  "wakeupTimeout" : 12345,
  "deviceInactivityTimeout" : 12345
}
                
              

HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "status" : "COMPLETED",
  "cronRetryExpression" : "...",
  "endOn" : 12345,
  "cronNextRetryOn" : 12345,
  "retryEvery" : 12345,
  "resumed" : true,
  "requestTimeout" : 12345,
  "processOnConnect" : true,
  "sendWakeupSMS" : true,
  "wakeupTimeout" : 12345,
  "deviceInactivityTimeout" : 12345,
  "id" : 12345,
  "accountId" : 12345,
  "jobType" : "device_software_install",
  "displayName" : "...",
  "jobProperties" : "...",
  "createdOn" : 12345,
  "createdBy" : 12345,
  "startOn" : 12345,
  "retryMaxAttempts" : 12345,
  "retryCount" : 12345,
  "optlock" : 12345
}
                
              

DELETE /deviceJobs/{deviceJobId}

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

Example

DELETE /deviceJobs/{deviceJobId}
Content-Type: */*

                
...
                
              

HTTP/1.1 204 No Content

              

GET /deviceJobs/{deviceJobId}

Return the device job specified in the path parameter

Example

GET /deviceJobs/{deviceJobId}
Content-Type: */*
Accept: application/json

                
...
                
              

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

                
{
  "status" : "STARTED",
  "cronRetryExpression" : "...",
  "endOn" : 12345,
  "cronNextRetryOn" : 12345,
  "retryEvery" : 12345,
  "resumed" : true,
  "requestTimeout" : 12345,
  "processOnConnect" : true,
  "sendWakeupSMS" : true,
  "wakeupTimeout" : 12345,
  "deviceInactivityTimeout" : 12345,
  "id" : 12345,
  "accountId" : 12345,
  "jobType" : "device_certificate_revoke",
  "displayName" : "...",
  "jobProperties" : "...",
  "createdOn" : 12345,
  "createdBy" : 12345,
  "startOn" : 12345,
  "retryMaxAttempts" : 12345,
  "retryCount" : 12345,
  "optlock" : 12345
}
                
              

PUT /deviceJobs/{deviceJobId}

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

The number set must greater of the current retries.

Example

PUT /deviceJobs/{deviceJobId}
Content-Type: application/json
Accept: application/json

                
{
  "status" : "STOPPED",
  "cronRetryExpression" : "...",
  "endOn" : 12345,
  "cronNextRetryOn" : 12345,
  "retryEvery" : 12345,
  "resumed" : true,
  "requestTimeout" : 12345,
  "processOnConnect" : true,
  "sendWakeupSMS" : true,
  "wakeupTimeout" : 12345,
  "deviceInactivityTimeout" : 12345,
  "id" : 12345,
  "accountId" : 12345,
  "jobType" : "device_certificate_update",
  "displayName" : "...",
  "jobProperties" : "...",
  "createdOn" : 12345,
  "createdBy" : 12345,
  "startOn" : 12345,
  "retryMaxAttempts" : 12345,
  "retryCount" : 12345,
  "optlock" : 12345
}
                
              

HTTP/1.1 204 No Content
Content-Type: application/json

                
{
  "status" : "STARTED",
  "cronRetryExpression" : "...",
  "endOn" : 12345,
  "cronNextRetryOn" : 12345,
  "retryEvery" : 12345,
  "resumed" : true,
  "requestTimeout" : 12345,
  "processOnConnect" : true,
  "sendWakeupSMS" : true,
  "wakeupTimeout" : 12345,
  "deviceInactivityTimeout" : 12345,
  "id" : 12345,
  "accountId" : 12345,
  "jobType" : "device_command",
  "displayName" : "...",
  "jobProperties" : "...",
  "createdOn" : 12345,
  "createdBy" : 12345,
  "startOn" : 12345,
  "retryMaxAttempts" : 12345,
  "retryCount" : 12345,
  "optlock" : 12345
}
                
              

GET /deviceJobs/{deviceJobId}/executions

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

Example

GET /deviceJobs/{deviceJobId}/executions
Content-Type: */*
Accept: application/json

                
...
                
              

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

                
{
  "deviceJobExecution" : [ {
    "status" : "STOPPED",
    "accountId" : 12345,
    "jobId" : 12345,
    "executionId" : 12345,
    "startedOn" : 12345,
    "endedOn" : 12345,
    "log" : "...",
    "optlock" : 12345
  }, {
    "status" : "STOPPED",
    "accountId" : 12345,
    "jobId" : 12345,
    "executionId" : 12345,
    "startedOn" : 12345,
    "endedOn" : 12345,
    "log" : "...",
    "optlock" : 12345
  } ],
  "limitExceeded" : true
}
                
              

GET /deviceJobs/{deviceJobId}/targets

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.

Example

GET /deviceJobs/{deviceJobId}/targets
Content-Type: */*
Accept: application/json

                
...
                
              

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

                
{
  "deviceJobTargets" : [ {
    "accountId" : 12345,
    "jobId" : 12345,
    "clientId" : "...",
    "createdOn" : 12345,
    "modifiedOn" : 12345,
    "status" : "CREATED",
    "statusMessage" : "...",
    "lastUpdateOn" : 12345,
    "progressPercentage" : 12345
  }, {
    "accountId" : 12345,
    "jobId" : 12345,
    "clientId" : "...",
    "createdOn" : 12345,
    "modifiedOn" : 12345,
    "status" : "CREATED",
    "statusMessage" : "...",
    "lastUpdateOn" : 12345,
    "progressPercentage" : 12345
  } ],
  "limitExceeded" : true
}
                
              

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

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

Example

GET /deviceJobs/{deviceJobId}/targets/{targetClientId}
Content-Type: */*
Accept: application/json

                
...
                
              

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

                
{
  "accountId" : 12345,
  "jobId" : 12345,
  "clientId" : "...",
  "createdOn" : 12345,
  "modifiedOn" : 12345,
  "status" : "REQUEST_FAILED_CERTIFICATE_UPDATE",
  "statusMessage" : "...",
  "lastUpdateOn" : 12345,
  "progressPercentage" : 12345
}
                
              

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

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

Example

POST /deviceJobs/{deviceJobId}/executions/{deviceJobExecutionId}/sendStopSignal
Content-Type: */*

                
...
                
              

HTTP/1.1 201 Created