Imagine the following scenario: A new software update was distributed to many thousand devices using the auto assignment feature. After a few hundred devices have downloaded the update, a major issue within the software is detected and any further software rollout needs to be stopped immediately.

In Bosch IoT Rollouts it is possible to stop the rollout of an assigned distribution set and thus mass-cancel pending updates on further devices.

Table of contents:

Mass cancel through distribution set invalidation
Consequences of invalidating a distribution set
Invalidation options
Required permissions

Mass cancel through distribution set invalidation

The mass-canceling of running update actions can be achieved by invalidating the distribution set the major issue was detected on. The invalidation can be done either via the Management API or the UI.

The Management API provides an endpoint for invalidating a distribution set through the resource Distribution sets - HTTP API. In the UI, the invalidation of a distribution set is possible in the Deployment view, since canceling an update action is seen as part of the deployment itself. Whereas the general management of distribution sets is part of the Distribution view, where the software distributions are managed, versioned and grouped.

Consequences of invalidating a distribution set

An invalidated distribution set cannot be used for future deployments:

The distribution set cannot be assigned to targets, neither through a rollout, auto-assignment nor a single assignment.
Invalidated distribution sets cannot be valid again, but remain invalid.
The invalidation is not repeatable. If no cancelation type was selected during invalidation, it is not possible to execute the mass-cancel retrospectively.

Invalidating a distribution set will affect other entities that reference the distribution set, depending on the options that are selected during invalidation:

auto-assignment
rollouts
actions

The invalidation options and their effects on those entities are described in more detail in the next section.

Invalidation options

For the invalidation of a distribution set several options can be set to define the consequences the invalidation shall have of already existing entities, that relate to that distribution set. Those options allow to perform a mass-cancel on running updates, or keep running updates alive until finished by the target itself.

The following table provides an overview of the different scenarios and their effects on other entities:

Type of cancelation	Stop rollouts	Effects on other entities
None	false	Auto-assignments are removed Rollouts remain running Actions remain running
None	true	Auto-assignments are removed Rollouts are stopped and put into state FINISHED Actions remain running until the device finishes the update as usual
Soft	true	Auto-assignments are removed Rollouts are stopped and put into state FINISHED Regardless of the state, all open actions of this distribution set are soft-canceled This option requires the device to support cancel flow The device will be informed about the cancelation. The action remains running in state CANCELING. When the device confirms the cancelation, the action will be closed with state CANCELED In the action history of the Deployment view this option corresponds to the cancel icon for a single action:
Force	true	Auto-assignments are removed Rollouts are stopped and put into state FINISHED Regardless, of the state or whether the device supports the cancel flow, each action is force-quit The action is closed and CANCELED state is displayed No further feedback is expected from the device The displayed status can differ from the actual status of the device In the action history of the Deployment view this option corresponds to the force quit icon for a single action:

Required permissions

The invalidation of a distribution set requires different permissions, depending on the chosen options during invalidation:

UPDATE_REPOSITORY - always required to set the distribution state into the invalid state
UPDATE_TARGET - required, if running actions shall be canceled
UPDATE_ROLLOUT - required, if rollouts shall be stopped

The permissions can be adapted in the User management view. Read more about permissions in the Authorization chapter.