Editing history for automations and scripts

[jpbede]

Context

Currently it is not possible for a user to easily revert an automation/script to a specific version/time after tinkering with it. This leads to a big use case for the backups, unpack the backup and restore a automation/script by copying and pasting the YAML. Which in turn leads to a major pain point with encrypted backups, you can't easily unpack them without an extra step.

Which all together makes it difficult for a non-technical user to revert an automation/script to a specific version/time.

Proposal

To solve this, my proposal would be a new history manager. This manager would store x entries (maybe configurable) of the last changes made to each automation/script via the UI. The version would be appended to a list, hold by the manager, each time it is saved via the UI.

The history manager would make use of the existing Store class like our other registries. The history manager holds a Store for each domain e.g. automation or script, which would result in a storage file for each domain e.g. core.automation_history to avoid one large JSON file. Each history entry will hold a reference to the related script/automation by its unique_id. Each history entry can be identified by its own entry_id.

{
    "version": 1,
    "minor_version": 0,
    "key": "core.automation_history",
    "data": {
        "history": [
            {
                "entry_id": "abc123",
                "unique_id": "1737280776631",
                "saved_at": "2025-01-19T12:45:33.924470+00:00",
                "config": # json representation of the automation/script config
            }
        ],
        "deleted": [
            {
                "entry_id": "123abc",
                "unique_id": "1737280776631",
                "saved_at": "2025-01-19T12:45:33.924470+00:00",
                "deleted_at": "2025-01-19T12:45:33.924470+00:00",
                "config": # json representation of the automation/script config
            }
        ]
    }
}

Deletion & Orphaned history entries

Upon automation/script deletion the history manager will store the last entry with a deletion timestamp. Orphaned history entries will be stored for 30 days after deletion of the related automation/script.

Websocket API

List history entries

A new Websocket API would allow the frontend to request a list of all entries for a particular automation/script from the manager:

Request

{
    "type": "config/history/list",
    "scope": "automation",
    "unique_id": "1737280776631"
}

Response

{
    "entry_id": "abc123",
    "saved_at": "2025-01-19T12:42:35.573717+00:00"
}

Retrieve config

A second Websocket API would allow the frontend to request the actual configuration for an entry in the history, to avoid sending a large chunk of data via the list endpoint to the frontend.

Request

{
    "type": "config/history/retrieve",
    "scope": "automation",
    "unique_id": "1737280776631",
	"entry_id": "abc123"
}

Response

Would return the actual stored config (saved by the frontend), which can be used by the frontend directly, e.g.:

{
    "id": "1737280776631",
    "alias": "New automation",
    "description": "",
    "triggers": [
        {
            "type": "changed_states",
            "device_id": "2f379241e3120f9d71bed28ad88a686b",
            "entity_id": "6984bc0396b6c8aa9957e889ffd1448c",
            "domain": "switch",
            "trigger": "device"
        }
    ],
    "conditions": [],
    "actions": [
        {
            "type": "turn_off",
            "device_id": "2f379241e3120f9d71bed28ad88a686b",
            "entity_id": "6984bc0396b6c8aa9957e889ffd1448c",
            "domain": "switch"
        }
    ],
    "mode": "single"
}

List deleted

A third websocket API would allow the frontend to display a list of deleted automations/scripts. This endpoint would only send the last history entry.

Request

{
    "type": "config/history/list_deleted",
    "scope": "automation",
}

Response

[
    {
        "unique_id": "1737280776751",
        "entry_id": "123abc",
        "saved_at": "2025-01-18T12:42:35.573717+00:00",
 	    "deleted_at": "2025-01-19T12:45:33.924470+00:00",
        "name": "My awesome automation"
    }
]

Final words

The frontend would then provide a list of the existing version in the history manager. The user would then load the specific entry for that time, review it and decide if they want to save/restore it.

This would give us a simple and user-friendly way to restore an automation/script without having to decrypt or restore a full backup, which could be used in other parts of Home Assistant.

Quick PoC

Bildschirmaufnahme.2025-01-19.um.18.06.11.mov

Changes

2025-01-19: Added restore of deleted automation/script
2025-01-19: Replace key with unique_id

[tetele]

One thing which doesn't seem covered which i think is important is deleted scripts/automations. There i times when i delete an automation after refactoring more into one and then wanting to go back to a previous snapshot.

[tetele]

As an extension to this mention, i think that there are sufficient cases in which the snapshot of the whole collection of automations/scripts/helpers/other configs is more useful than individual automation history, as they tend to be used in tandem.

[jpbede]

Yes indeed, thanks for pointing out. Restoring a automation/script would be possible with that, I've updated the proposal to include restoring after deletion.

[tetele]

Orphaned history entries will be stored for 30 days after deletion of the related automation/script.

Why 30 days? Why not more? Why not less?

In my opinion experience, if you don't need a backup within a day of deleting the automation/script, then the next time you need it is half a year later 😅

[jpbede]

It is just the same amount of days we have in the entity registry, so no preferred number here 😄

[arturpragacz]

Each history would be grouped by a id e.g. automation id or the script entity id

We should always store things based on their unique_id, so that for example a renamed automation still holds the same history.

[jpbede]

Good point, I've updated the suggestion and replaced key with unique_id because for the automation ID and script ID it would have been unique_id.