Bosch IoT Rollouts

Action state machine

Table of contents:

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.

Note: if repository.actions.autoclose.enabled is activated in system configuration (by Management API or UI) a new assignment will result in the transition from RUNNING to CANCELED.
In this case the client is not informed about a cancellation but the action is closed right away.
This is useful in scenarios, where the client does not support the confirmation of cancellations.

Keep in mind that one consequence of the auto-close is that if the client already started with the action it is not able anymore to confirm its (un-)successful execution (due to the closed state).

Defined action types

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

Icon

Action Type

Description

images/confluence/download/thumbnails/1680491217/roUi-concepts-forced-version-1-modificationdate-1698852213000-api-v2.png

Forced

The device is advised that the update has to be executed immediately.

images/confluence/download/thumbnails/1680491217/roUi-concepts-soft-version-1-modificationdate-1698852230000-api-v2.png

Soft

The device is advised that the update can be executed any time, e.g. with user approval or in future regular update time plan.

images/confluence/download/thumbnails/1680491217/roUi-concepts-downloadOnly-version-1-modificationdate-1698852255000-api-v2.png

Download Only

The device is advised that the update has to be only downloaded, and not installed.

images/confluence/download/thumbnails/1680491217/roUi-concepts-timeForcedRollout-version-1-modificationdate-1698852275000-api-v2.png

Time Forced

Configures a point in time where the rollout's type switches from Soft to Forced.

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.

Type

Status reported

Description

Action state

FINISHED

The action has completed successfully.
Target will switch to IN_SYNC if no further actions are pending, i.e. installed set is now equal to assigned set.

Action state

ERROR

The action has been completed with an error.
Target will switch to ERROR and assigned distribution set field will reset.
That allows users to re-assign the set for a retry.

Action state

CANCELED

The action has been canceled and this cancellation has been confirmed by the client (or repository.actions.autoclose.enabled is set).
Target will switch to IN_SYNC if no further actions are pending, i.e. installed set is now (again) equal to assigned set.

Action state,
intermediate status

RUNNING

Action is pending.
Feedback on this state will be logged but no state transition.

Action state

CANCELING

Action has been canceled but this change is not yet confirmed by the client.
The client can choose to confirm the cancellation which results in a transition to CANCELED
or it can decide to reject the cancellation with CANCEL_REJECTED (see below).

Note: as the client might not be aware of the transition change from RUNNING to CANCELING the update server still accepts regular feedback as if the cancellation never happened in the first place, i.e. when the update is already in process by the client.

Action state

SCHEDULED

Action is in waiting state, i.e. the action is scheduled in a rollout but the group it belongs to is not yet started.

Action state

WAIT_FOR_CONFIRMATION

Action is in waiting state, i.e. the action is scheduled in a rollout but the user has to confirm it first. Applicable only if the user consent flow feature has been enabled for the tenant prior to the start of the action.

Once the update is confirmed it moves to RUNNING state.

Intermediate feedback

WARNING

Action still running but client informs server about an issue at runtime.

Only for informational purposes and no state transition.

Intermediate feedback

RETRIEVED

Update server marks this state if the action has been pulled by the client in DDI case.
Technically only a hint as the update server does not know if the action was actually processed by the client.

In DMF case this status can be provided optionally by the device integration layer.

Intermediate feedback

DOWNLOAD

Device informed update server that it started the download.

Intermediate feedback

DOWNLOADED

Device informed update server that it completed the download.

If the assignment was of type Download Only, the action for the device will be considered successful and change its action state to FINISHED.

If the assignment is not of type Download Only and a maintenance window (see below) is activated, the device is supposed stop progress here until it enters the window.

Intermediate feedback

CANCEL_REJECTED

Cancellation has been rejected by the client.

The action moves back from CANCELING to RUNNING.

Action state transitions

images/confluence/download/attachments/1680491217/action-state-diagram-version-2-modificationdate-1619461645000-api-v2.png

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.

images/confluence/download/attachments/1680491217/ro_actionStateMachine_withWFC-version-1-modificationdate-1670402405000-api-v2.png

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 API and Device Management Federation 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).

Action weight (multi-assignments only)

When multi-assignments is enabled, weights are used to define the importance of one update over another. The value of a weight is between (and including) 0 and 1000. The higher the weight the more important is the assignment represented by the action. Also, when defining a rollout or an auto-assignment, and multi-assignments is enabled a weight value has to be provided. This value is passed to the actions created during the execution of these rollouts and auto-assignments. If no weight was provided the highest value of 1000 is used instead.

Consequences

While this feature provides more flexibility to the user and enables new use-cases, there are also some consequences one should be aware of:

Critical

  • This feature is in beta and may change unannounced.

  • For now, this feature is opt-in only. Once activated, it cannot be deactivated.

Minor

  • While on DMF-API a MULTI_ACTION request is sent, DDI-API only exposes the most urgent open action (according to the weight of the actions).

  • All information regarding the currently assigned or installed Distribution Set does only respect the last assignment, as well as the last successfully installed Distribution set.
    This also affects:

    • Pinning a target or Distribution Set in Deployment View.

    • Statistics about installed or assigned Distribution Sets.

  • Auto close running actions, when a new Distribution Set is assigned (repository.actions.autoclose.enabled) is deactivated.

  • Marking a Distribution Set to be a Required Migration Step is deactivated.