Introduction

During an update, the action moves through multiple states. Based on the current state, the client has different options for feedback. The update server requires a state from the client to finish the action, either successful or with error. Everything else, by means of intermediate feedback, is optional and the granularity of that feedback is up to the client. Be aware that both device integration APIs (i.e. DDI and DMF) will present only the oldest active action to the client, until that action is confirmed. Then the next action will be presented and so forth. As the update server can never be sure which actions the client started to work on, it will keep every action in line until confirmed. As a result, that can include cancellations for actions, the client never started to work on (e.g. as it was never online).

For example, if an update for set A, is followed by an update for set B, both actions (the one for A on CANCELING and the one for B on RUNNING) will be sent to the client, in the correct historical order. In this example the client has to confirm, that A is either installed or the cancellation is accepted (i.e. not installed), before the update for B is presented. This is, as mentioned above, even the case when the client was not aware of the update to A in the first place.

By default the update server does require from the client, to handle the canceled actions in the queue and to continue with the next waiting update as described. However, to handle the transition from RUNNING to CANCELING, is not required by the client. The update server will not enforce this (e.g. reject FINISHED update on an action that is in CANCELING), as this would overly complicate handling by the client. It is recommended, that the client sends a CANCEL_REJECTED, if it became aware of the transition change (e.g. in DDI case through continuous polling during the update), as this will make transparent to the operator why the update was completed, even if it was canceled.

Defined action types

The action type influences the state transitions of an Action. Different action types produce different behaviours.

Defined action states

In general the update server has two types of states.

Action state refers to states of the action itself, e.g. is it still running, not yet running or completed.

Other entries represent intermediate feedback that is stored in the history, but has no impact on the state of the action itself or the target. This is typically the case for feedback during the lifetime of an action.

Action state transitions

Action state transitions with user consent flow

When the user consent flow feature has been enabled for the tenant, a new WAIT_FOR_CONFIRMATION state is introduced, indicating that the action is waiting for confirmation by the end user of the target devices.

After you start a rollout or assign a distribution set, the action eventually reaches the WAIT_FOR_CONFIRMATION state. It then remains in this state until the user confirms or rejects the action:

• Accepting the action will change the state to RUNNING and the flow described above is pretty much the same as the default one.

• Rejecting the action will preserve the WAIT_FOR_CONFIRMATION state. The reason for that is to give the user a chance to accept it at some point in time, if needed.
  If you want to dispose of the action you could cancel it, which will change the state to cancelled and the action will be closed.

See also Deployment: Confirmation required.

Maintenance Window

In addition to the straight forward approach to inform the device (by DDI or DMF) to download and install the software in one transaction Rollouts supports the separation of download and installation into separate steps.

This feature is called Maintenance Window where the device will be informed to download the software first and then, when it enters a defined (maintenance) window, the installation triggers follows.

Rollouts allows as part of the provisioning action to define the maintenance window. It is based on defining the start time of the window (in Cron Quartz notation), a length and the timezone of the definition. The window can have a repeating character (e.g. “at 12pm (noon) every day”).

Both, in Direct Device Integration (DDI) API and Device Management Federation (DMF) API, Bosch IoT Rollouts will inform the device outside/before the window to download only. Only during the window the device gets the download and install command.

In DDI case Rollouts will optimize the sleep parameter provided to the device as well to tune DDI polls into the window. This is necessary to ensure that for example an one hour maintenance window is hit by devices that usually poll only once a day.

In DMF case the integrated device management or connectivity service has to ensure that the devices are guided into the window.

Note: maintenance window for the time being is only supported for direct distribution set to target assignments (by Management UI or Management API) and not by Rollout management

Multi-Assignments (beta)

One of the main paradigms of Bosch IoT Rollouts is, that a Distribution Set represents the currently installed software of a device. Hence, a device can have only one Distribution Set assigned/installed at a time. With Multi-Assignments enabled, this paradigm shifts. Multi-Assignments allows to assign multiple Distribution Sets to a device simultaneously, without cancelling each other. As a consequence, an operator can trigger multiple campaigns addressing the same devices in parallel.

This feature (multi.assignments.enabled) can be activated via system configuration (by Management API or UI).