Running Azure IoT Device Jobs
Azure IoT provides “Device Jobs” to allow scheduling a specific action on a subset of devices. The integration of device jobs with the ThingWorx Platform takes the form of ThingWorx remote services that provide the basic functionality of device jobs. These services are:
• AzureIotDeviceJobScheduleTwinUpdateJob
• AzureIotDeviceJobScheduleDeviceMethodJob
• AzureIotDeviceJobGetJob
• AzureIotDeviceJobFindJobs
• AzureIotDeviceJobCancelJob
 |
There is no upper limit on the number of devices that a job can target. Consider network traffic and the number of devices to target carefully to maintain the desired performance.
|
To run a device job, follow these steps:
1. Using one of the Schedule services listed above to create a job. Alternatively, you can obtain an ID using the FindJobs service.
2. To check the status of the job, use the returned ID for the job as a parameter to the GetJob service. The possible statuses that may be returned are:
◦ scheduled — The job has been created.
◦ pending — The start time passes.
◦ running — The job starts. At this point, the job can no longer be cancelled. The query for devices has been run. Devices added after this point is not part of this job. Note that individual devices run the job concurrently.
◦ completed — Either all the devices have processed the job or the number of seconds specified for maxExecutionTimeInSeconds passes.
failed — Any devices that did not run the job (they were offline) transition to this status.
3. Once the job has ended (a status of completed or failed), query for results using the QueryJobResults service.
For an example of using the device jobs services, refer to
Device Jobs Demo.
The following sections provide more information about these services.
ScheduleTwinUpdateJob Service
This service requires only one parameter, which is the patch document. This field is a JSON input field that you can enter through ThingWorx Composer when you select the service or through an HTTP API.
The patch document must contain one or both of the following keys:
• A desired key that is nested under properties
• A tags key
While the patch document may contain a reported section under properties, the content there will have no effect. Only a device may update the reported section.
In general, you create the patch document manually or use any code that creates the appropriate JSON. For more information about creating a patch document to update just a portion of the device twin document, refer to
https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-device-twins. In particular, look at the example device twin JSON document. You could use a sub-section of that document, as long as you keep the parent/child relationships in line. You do not need to specify the tag's parent if you just want to update the desired properties. However, you do need to specify everything down to the child level.
ScheduleDeviceMethodJob Service
This service requires only one parameter, methodName. If a payload is necessary, you need to create a local wrapper service with the desired payload type. An example of a wrapper service is included in the. distribution bundle for the Azure IoT Hub Connector. Since remote service calls are performed through DeviceMethods, a wrapper service is required to allow users to supply parameters for the service call in the same manner as standard ThingWorx remote service calls
|
|
The default connect timeout is infinite, so an offline device will cause the job to wait until the maxExecutionTime expires. As the number of concurrent jobs is limited to one on the lower service tiers and running jobs cannot be cancelled, this default setting may not be desirable. Set a non-zero connect timeout to avoid this behavior. You can set this timeout as a parameter of the ScheduleDeviceMethodJob service.
|
QueryJobResults Service
The query parameter for this service is a string of the iothub query language. This query selects from the special devices.jobs table, which contains results for each device affected by the job. As a consequence, a job is visible to this service only if at least one device has been affected. Jobs that have not yet run will never be returned through this service call.
|
|
Per the Azure documentation, this query can use only select *. Projections are not allowed.
|
FindJobs Service
You can locate existing jobs by specifying a type and/or status as input to this service. This service a very coarse-grained search method. It is recommended that you use QueryJobResults instead of FindJobs when searching for jobs that have terminated. However, this search is the only way to find jobs that have not yet run (jobs whose status is scheduled or pending).
CancelJob Service
You can cancel a job that has not started running by passing the job ID to this service. Once a job has started running, you cannot cancel it.