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

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, from the client only, to finish the action, either as 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 API’s (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 cancelations 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 cancelation 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 cancelation but the action is closed right away. This is useful in scenarios where the client does not support the confirmation of cancelations. 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 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 cancelation 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 cancelation which results in a transition to CANCELED or it can decide to reject the cancelation 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 cancelation 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 Update server logs this state if the client has been calling the download resource. No state transition. Note: not supported for all download types.
intermediate feedback CANCEL_REJECTED Cancelation has been rejected by the client. The action moves back from CANCELING to RUNNING.

Transitions

Action status transitions