Proposal: Add confirmation to update entity

[marcelveldt]

Context

Within Home Assistant it is possible to update devices or services by using the update entity. While the update entity has some way to show release notes (including markdown for warnings etc.), it can be said that updating is too easy.

A user can just click a single button to start the update which is not always desired, especially with devices.
For example, we are familiar with devices (or specific device updates) that require a device to be re-paired to the controller or other examples where it takes a while for the device to restore its connection after updating or something else.

In general vendor/device specific apps will show a message specific to the device and/or update, so the user is aware of the consequence. Home Assistant is a generic platform that allows updating of all supported devices and services.

Device vendors (but this could also apply to a service with a breaking change for example) are a bit cautious to allow updating through Home Assistant because when things go south (because the user didn't read or understand the consequence), they wil get the support load on their helpdesk.

Proposal

We like to extend the entity model for the Update entity so that an integration can mark an update to need an additional confirmation from the user with an integration, device or update specific warning.

• Add an optional property confirmation to the UpdateEntity, which is a string (supporting Markdown in the UI).

• When the confirmation property has been set, this will require an additional confirmation boolean in the service call for the update entity update service.

• When the confirmation property has been set, this will trigger an confirmation dialog in the frontend which shows the explicit message/warning set by the integration where the user agrees to know the consequence and continue the update process (or abort).

TBD

The name of the property can also be something else, confirmation felt the most clear to us while writing the proposal.

We need to decide how to show the confirmation to the user. After a quick discussion with a few members we came up with these ideas, feel free to propose another one;

1. When the confirmation is required for an update, it triggers a confirmation dialog on install showing the confirmation message with a I'm sure continue button or something.

2. When the confirmation is required for an update, it triggers a confirmation dialog on install showing the confirmation message, a checkbox I've read and understood the message with a continue button.

3. When the confirmation is required for an update, it triggers a confirmation dialog on install showing the confirmation message with a I'm sure continue button or something that is disabled for the first 10 seconds with countdown (which most people find annoying but it is really safe/effective maybe)

Consequences

By adding the confirmation to the service call (default set to False) existing automations that auto-update entities in HA, will keep working but updates marked with the additional confirmation will simply fail. A user could still automate update with that boolean set but that is its own responsibility, we can/should not prevent that.

Integrations can sort out for themselves if an update, device(vendor/model) or maybe the whole integration needs the confirmation. They can implement the new feature as they wish and the old behavior will keep working as-is.

For Z-Wave and Matter we have the idea to go with an integration-wide confirmation at all times. It is just risky to update all devices without that extra confirmation, unless we are 100% sure it can be done without any additional warnings. We will chew a bit on some generic warning that applies to all devices. When we are aware of device- model- or vendor specific instructions we will use those. The same applies the other way around, if we are 100% sure that an update is safe to apply without confirmation (and even auto-updates), we skip the confirmation for a device or update. This is integration specific.

I can imagine other integrations have a similar path they like to follow.

Future extension

At some point in the future we could maybe use the device database as a reference for the device/manufacturer specific warnings.

[codemunkie15]

It would be great if HA users could configure this too for specific integrations (official or HACS).

Sometimes I end up manually editing the source code for a custom integration or card (to fix a bug or maybe include a PR that isn't yet merged to the repo) and sometimes I forget to re-apply the changes after an update. If I could use this functionality to manually say I want a warning on X update entity to remind me I've manually edited the source code it would help immensely!

Many thanks

[MartinHjelmare]

I think the proposal sounds good. I think the confirmation string, should be a translation key though, so we can add translations for the message. Ie, the message is not set in the confirmation property but is put in strings.json for translations.

This point:

Add an optional property confirmation to the UpdateEntity, which is a string (supporting Markdown in the UI).

[joostlek]

Let's also allow translation placeholders so we can give the possibility to add links or manufacturer supplied extra info, since we can't translate those upfront.

[gjohansson-ST]

I like the idea but I think we should limit ourselves to entity level for the confirmation and not per update.
So use a need_confirmation property which is a bool and use the translation_key for supporting translation.

For frontend I would think option 1 is sufficient and enough.

[marcelveldt]

if its at entity level, the integration itself can decide wether to use it for each update.

[gjohansson-ST]

Right, I was more thinking it's checked once at startup and then it's either True or False so it's not allowed to switch back and forth.
An integration could have several update entities which could then have it differently set for each.