Campaigns
Overview
Campaigns are used to update the configuration of multiple devices at the same time. Once a campaign is launched, it can also be used to monitor the devices to check if they have the requested configurations and state. They can be created from the built-in front-end, or through the API.
Creating a campaign requires providing the following information: - A name to identify the campaign. - A list of devices that are part of the campaign. - Configurations that must be applied to all devices. - State values that the devices are expected to take once the campaign is complete.
Once created, the campaign can be updated until it is launched. After that, it cannot be edited anymore. Launching a campaign has two effects: - It starts a background job which will handle the configurations updates. - It creates a supervision used to monitor the devices.
The background job will start by updating the requested configurations in database for all the devices, and will then proceed with synchronizing those configurations on the interface on which the devices are provisioned. This means that you do not have to take the device connectivity into account when starting a campaign.
Info
Since the configurations are written in database before being synchronized to the different interfaces, it is possible that during a short amount of time after starting the campaign, devices are shown to have taken the expected configuration without having really been notified.
For more details on the technical aspects of the background tasks used by the campaigns, see jobs and bulk actions.
OTA update
Campaigns work particularly well with the firmwares feature. When combined, it is possible to trigger a mass update of a device fleet. There is no required formalism, here is a suggestion of campaign configuration for an OTA update campaign:
| Key | State | Configuration |
|---|---|---|
| firmware_version | 1.1 | 1.1 |
| firmware_url | - | https://your-asset-storage.com/fw/v1_1.bin |
| firmware_token | some_secret_token_value | |
| app_version | 5.1.9_beta01 | 5.1.9_beta01 |
| app_url | - | https://your-asset-storage.com/app/5.1.9_beta01.bin |
| app_token | some_secret_token_value |
When creating a campaign on the built-in front-end, an option is available to set those values based on the available firmwares for the device type that matches the selected devices.
Lifecycle
The jobs started by a campaign will run until completed, and will not start again. A campaign is a one-off operation, it does not guarantee that the devices will keep the requested values forever. For example, if a device takes the configuration requested by the campaign, and a users updates it afterwards, the campaign will not update it another time. The device will keep the value set by the user, and will be displayed with an invalid state in the related supervision.