Bulk actions
Bulk actions are a set of actions to be performed on multiple entities at once. For example, there is a bulk action to update desired configurations on many devices at once.
This kind of actions can be more time consuming than regular platform use due to the amount of changes it involves, as well as potentially accessing external services (Azure IoT Hub for instance). This is why bulk actions are asynchronous. When a user requests a bulk action, it will not be executed instantly. It will rather be treated like a background task to be completed.
Bulk actions happen as follows:
- the user sends a bulk action request to Kamea, providing one action to perform on a set of entities
- the API schedules a job for this bulk action, and provides a job ID to track its progress
- at any time, the user can check on this job's progress
Multiple bulk actions can run alongside each other.
Authorization
To create and read bulk action jobs, users need the Create.Job and Read.Job permissions.
Depending on the type of bulk action, users will need additional permissions. These are the same as if the user would perform the action on each entity separately.
For example, to bulk update multiple devices' configurations, the user would still need the Write.Device Configuration permission on each device (assigned through a Tenant or Folder like usual).
Job status
When checking on a job's progress, you can see the various steps that it needs to perform.
Each job and all its steps (also called sub jobs) have statuses:
| Status | Meaning |
|---|---|
| created | has not been started yet |
| in progress | is currently being processed |
| waiting | has been processed, and is waiting for other steps or external resources |
| success | has finished successfully |
| failed | at least part of the step has failed. There is some error detail in the job to find out what went wrong. |
When a job or sub job has failed, it mean something in the job failed, but it still is possible that a part of it succeeded. The jobs details should provide enough information to understand what happened in this kind of case.
Some failed steps can be retried automatically. This will appear in the steps details.
Types of bulk actions
This list shows the bulk actions that are currently available, with the additional permissions needed when requesting the bulk action.
Patch device configurations
Description
This bulk action is for applying a device configuration patch to multiple devices.
Devices that are provisioned on IoT Hub will also get their device Twins patched.
Permissions
- Write.Device Configuration on each device in the bulk action