User consent flow
User consent flow is a feature introduced by Bosch IoT Rollouts to support its customers in rolling out software updates to their managed devices in compliance with the European Directive concerning contracts for the supply of digital content and digital services. The requirements of the Directive apply to all devices sold from January 1st 2021 onward.
Some highlights of the directive are that a trader, i.e. in our scenario the one who sells a device to an end user of the device (consumer), is obliged to ensure that the consumer is informed of and supplied with updates, including security updates, that are necessary to keep the digital content or digital service in conformity with their contract. The consumer must be informed of upcoming modifications in a clear and comprehensible manner. Further, the consumer must be informed about the availability of the update and the consequences of his or her failure to install it.
In particular, the end user of a device needs to be asked for confirmation for each software update that is going to be made on his or her device, and the responsible to obtain such a confirmation is the one who sells the device.
Thus, the update can be rolled out only after the end user has explicitly agreed to its installation.
The given consent does not have to be persisted or auditable, however, the update process must ensure that the consent has been requested.
As Bosch IoT Rollouts is not an end-user facing service, it is not responsible to ensure that its customers comply with the requirements described above. However, by introducing the user consent flow feature, Bosch IoT Rollouts enables its customers to become compliant in a timely and efficient manner.
There are important things to consider before activating this feature though, described later on this page.
Overview
By default, when a distribution set is assigned to a target Bosch IoT Rollouts exposes the artifacts or binaries to the respective targets via APIs. The devices then download these artifacts and flash themselves to complete the update.
However, when the user consent flow feature is enabled for the particular tenant, Bosch IoT Rollouts introduces an interim step where the consent of the end user of the device is requested for a pending software update. Only after such consent is granted can the devices proceed with downloading the artifacts and completing the update.
The feature can be enabled and disabled at any time via both the Bosch IoT Rollouts UI and Management API on tenant level.
Once enabled, the feature offers two scenarios - confirmation required (on assignment/rollout level) and auto-confirmation (on target level), each described below.
Confirmation required
After the user consent flow feature is enabled on tenant level, there is a confirmation required option for every assignment of a distribution set to a target (manual or automatic) and for every rollout campaign on rollout group level. This option is activated by default, meaning that confirmation of the end user of each device (target) will be awaited before proceeding with the download/install process. Until such confirmation is received, the action will stay in a WAIT_FOR_CONFIRMATION state (see Flow).
The confirmation required option is applicable per assignment (manual and automatic) and per rollout group. Therefore, it should be activated/deactivated for each assignment and/or rollout group explicitly.
See how the process looks like at:
Auto-confirmation
In contrast to confirmation required where the device needs to confirm each single update, it is possible to confirm all future updates on target level automatically.
Enabling auto-confirmation means that the user gives consent for all future updates on the specific target and does not have to confirm each one separately.
Learn how to enable and disable the auto-confirmation feature:
Flow
Once the user consent flow feature has been enabled for the particular tenant,
a new state (WAIT_FOR_CONFIRMATION)
is introduced
in the action state machine.
Read more about it at Action state machine.
Even if the user consent flow feature has been enabled for the tenant, the
confirmation required
can be deactivated per assignment or rollout group explicitly
.
In that case, the action state machine treats the user consent as granted and directly moves from the wait for confirmation state to the running state.
Things to consider before enabling the feature
You can enable and enforce the user consent flow feature on your tenant with just a couple of clicks, but before you do that, please consider the following changes that in such a case will affect any future updates:
As there will be a change in the payload, the device needs to be aware of what to expect.
Your devices need to be ready to respond to such a new consent-requesting logic.
Depending on which API you are using, refer to the corresponding pages to see the new messages, states etc.:
Normally, when an assignment or a rollout is started via the DDI API, the payload exposes a deployment base link to show to a device (when polling) that there is a pending action (update). If the user consent flow feature is activated, instead of a deployment base, the payload exposes a confirmation base.
On the other hand, when the DMF API is used and the user consent flow feature is activated, Bosch IoT Rollouts sends an additional message to the device to initialize a confirmation task. The message topic is CONFIRM and it signals the wait for confirmation state. The device responds via the UPDATE_ACTION_STATUS message with a value of either CONFIRMED or DENIED.