Provisioning State Machines

Target state machine

A target has a current state which reflects the provisioning status of the device at this point in time. State changes are driven either by the update server by means of starting an update or by the controller on the provisioning target that gives feedback to the update server, e.g. “I am here”, “I am working on a provisioning”, “I have finished a provisioning”.

Defined target states

State Description
UNKNOWN Set by default for a pre-commissioned target until first status update received from the target. Is the initial starting point for targets created by UI or management API.
IN_SYNC Assigned DistributionSet is installed.
PENDING Installation of assigned DistributionSet is not yet confirmed.
ERROR Installation of assigned DistributionSet has failed.
REGISTERED Target registered at the update server but no DistributionSet assigned. Is the initial starting point for plug-and-play devices.

Target state transitions

Target status transitions

Action state machine

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 autoclose 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 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.
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 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

Action status transitions

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 as well as Device Management Federation API 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 a one our 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.