Schedule jobs on multiple devices

Overview

As described by previous articles, Azure IoT Hub enables a number of building blocks (device twin properties and tags and direct methods). Typically, back-end apps enable device administrators and operators to update and interact with IoT devices in bulk and at a scheduled time. Jobs encapsulate the execution of device twin updates and direct methods against a set of devices at a schedule time. For example, an operator would use a back-end app that would initiate and track a job to reboot a set of devices in building 43 and floor 3 at a time that would not be disruptive to the operations of the building.

When to use

Consider using jobs when: a solution back end needs to schedule and track progress any of the following activities on a set of device:

  • Update desired properties
  • Update tags
  • Invoke direct methods

Job lifecycle

Jobs are initiated by the solution back end and maintained by IoT Hub. You can initiate a job through a service-facing URI ({iot hub}/jobs/v2/{device id}/methods/<jobID>?api-version=2016-11-14) and query for progress on an executing job through a service-facing URI ({iot hub}/jobs/v2/<jobId>?api-version=2016-11-14). Once a job is initiated, querying for jobs enables the back-end app to refresh the status of running jobs.

Note

When you initiate a job, property names and values can only contain US-ASCII printable alphanumeric, except any in the following set: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}.

Reference topics:

The following reference topics provide you with more information about using jobs.

Jobs to execute direct methods

The following is the HTTP 1.1 request details for executing a direct method on a set of devices using a job:

```
PUT /jobs/v2/<jobId>?api-version=2016-11-14

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8
Request-Id: <guid>
User-Agent: <sdk-name>/<sdk-version>

{
    jobId: '<jobId>',
    type: 'scheduleDirectRequest', 
    cloudToDeviceMethod: {
        methodName: '<methodName>',
        payload: <payload>,                 
        responseTimeoutInSeconds: methodTimeoutInSeconds 
    },
    queryCondition: '<queryOrDevices>', // query condition
    startTime: <jobStartTime>,          // as an ISO-8601 date string
    maxExecutionTimeInSeconds: <maxExecutionTimeInSeconds>        
}
```

The query condition can also be on a single device Id or on a list of device Ids as shown below

Examples

queryCondition = "deviceId = 'MyDevice1'"
queryCondition = "deviceId IN ['MyDevice1','MyDevice2']"
queryCondition = "deviceId IN ['MyDevice1']

IoT Hub Query Language covers IoT Hub query language in additional detail.

Jobs to update device twin properties

The following is the HTTP 1.1 request details for updating device twin properties using a job:

```
PUT /jobs/v2/<jobId>?api-version=2016-11-14
Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8
Request-Id: <guid>
User-Agent: <sdk-name>/<sdk-version>

{
    jobId: '<jobId>',
    type: 'scheduleTwinUpdate', 
    updateTwin: <patch>                 // Valid JSON object
    queryCondition: '<queryOrDevices>', // query condition
    startTime: <jobStartTime>,          // as an ISO-8601 date string
    maxExecutionTimeInSeconds: <maxExecutionTimeInSeconds>        // format TBD
}
```

Querying for progress on jobs

The following is the HTTP 1.1 request details for querying for jobs:

```
GET /jobs/v2/query?api-version=2016-11-14[&jobType=<jobType>][&jobStatus=<jobStatus>][&pageSize=<pageSize>][&continuationToken=<continuationToken>]

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8
Request-Id: <guid>
User-Agent: <sdk-name>/<sdk-version>
```

The continuationToken is provided from the response.

Jobs Properties

The following is a list of properties and corresponding descriptions, which can be used when querying for jobs or job results.

Property Description
jobId Application provided ID for the job.
startTime Application provided start time (ISO-8601) for the job.
endTime IoT Hub provided date (ISO-8601) for when the job completed. Valid only after the job reaches the 'completed' state.
type Types of jobs:
scheduledUpdateTwin: A job used to update a set of desired properties or tags.
scheduledDeviceMethod: A job used to invoke a device method on a set of device twins.
status Current state of the job. Possible values for status:
pending : Scheduled and waiting to be picked up by the job service.
scheduled : Scheduled for a time in the future.
running : Currently active job.
cancelled : Job has been cancelled.
failed : Job failed.
completed : Job has completed.
deviceJobStatistics Statistics about the job's execution.

deviceJobStatistics properties.

Property Description
deviceJobStatistics.deviceCount Number of devices in the job.
deviceJobStatistics.failedCount Number of devices where the job failed.
deviceJobStatistics.succeededCount Number of devices where the job succeeded.
deviceJobStatistics.runningCount Number of devices that are currently running the job.
deviceJobStatistics.pendingCount Number of devices that are pending to run the job.

Additional reference material

Other reference topics in the IoT Hub developer guide include:

Next steps

If you would like to try out some of the concepts described in this article, you may be interested in the following IoT Hub tutorial: