Migrating from alert and Alert2

Migrating from alert and Alert2

If you already have alerts, in Home Assistant's built-in alert integration or in Alert2, you don't have to recreate them by hand. The repository has two converters that turn your existing YAML into an Alert Redux import file. They report anything they couldn't convert exactly.

The converters aren't part of the integration (HACS doesn't install them). Run them from a copy of the repository, anywhere with Python 3.10 or later and PyYAML; Home Assistant isn't needed.

git clone https://github.com/arkane-systems/ha-alert-redux
cd ha-alert-redux
pip install pyyaml

Step by step

1. Convert, and read the report.

   python3 tools/convert_alert.py alerts.yaml -o alert-redux.yaml

   or, for Alert2:

   python3 tools/convert_alert2.py alert2.yaml -o alert-redux.yaml

   The input can be your alert: section, a whole configuration.yaml, an alert2: block, or a single Alert2 alert as its Alert Manager card shows it. The report, on the screen, lists what was converted, what wasn't (and why), and the notifier groups the file needs.

2. Settle the notifier groups. Alert Redux alerts send to notifier groups, not to notify actions. By default each old notifier becomes a group of the same name (mobile_app_alices_phone). Usually it's better to merge them into a few groups, with a group map:

   # map.yaml: old notifier -> group name (or a list of names; empty drops it)
   mobile_app_alices_phone: Phone
   mobile_app_bobs_phone: Phone
   alexa_kitchen: Speakers
   persistent_notification: Persistent

   python3 tools/convert_alert.py alerts.yaml --group-map map.yaml -o alert-redux.yaml

   Create those groups in Alert Redux (Getting Started shows how): an import naming a group that doesn't exist is refused.

3. Check the import. On the admin card, Import, paste the file, and Check. That's a dry run: it makes every check a real import would, and changes nothing. Fix and repeat until it's clean.

4. Import it, and look. Check the alerts on the admin card. Its Summary button describes each alert in words, which is a quick way to read them through.

5. Run both side by side for a while, if you can: keep the old alerts (perhaps with their notifiers off) until the new ones have fired, notified, and been acknowledged the way you expect. Then remove the old configuration.

6. Keep the files. Importing the same file again is harmless: alerts match by name.

From the built-in alert

Every alert: entry becomes a State alert:

alert	Alert Redux
entity_id, state	Entity, State
repeat	Reminder schedule
can_acknowledge	Acknowledgeable
message, done_message	On message, Done message
notifiers	Notifier groups (with the group map)
skip_first	nothing exact; with --skip-first-as-delay, a delay before firing of the first repeat
title	notifications are titled with the alert's name
data	set it on the group's members instead

Before:

alert:
  garage_door:
    name: Garage door left open
    entity_id: binary_sensor.garage_door
    state: "on"
    repeat: [15, 30, 60]
    can_acknowledge: true
    skip_first: true
    message: The garage door has been open for a while.
    done_message: The garage door is closed.
    notifiers:
      - mobile_app_alices_phone
      - mobile_app_bobs_phone

After (--skip-first-as-delay, with the group map above):

format: alert_redux
version: 1
alerts:
- name: Garage door left open
  kind: state
  entity_id: binary_sensor.garage_door
  target_state: 'on'
  acknowledgeable: true
  reminder_schedule:
  - 15
  - 30
  - 60
  message: The garage door has been open for a while.
  done_message: The garage door is closed.
  notifier_groups:
  - Phone
  delay_on:
    seconds: 900
generators: []

About skip_first: in the built-in integration, the alert turns on at once but the first notification waits. Alert Redux's nearest equivalent is a delay before firing: the alert doesn't fire at all until the condition has held that long, so a shorter blip is never seen. That's usually what people meant, which is why the option exists, but it's not identical, so the converter only does it when asked.

From Alert2

Alert2	Alert Redux
condition (an entity, or a template comparing one entity's state)	State alert
condition (any other template)	Template alert
condition_on / condition_off, trigger_on / trigger_off	On/off alert
trigger	Trigger alert
threshold	Threshold alert
no condition (raised with alert2.report)	Manual alert that ends by itself
priority low / medium / high	Notice / Warning / Critical
delay_on_secs, reminder_frequency_mins, throttle_fires_per_mins	delay before firing, reminder schedule, throttle
ack_required	Keep until acknowledged
supersedes	supersedes
notifier	notifier groups

Before:

alert2:
  alerts:
    - domain: freezer
      name: too_warm
      friendly_name: Freezer too warm
      condition: "{{ states('sensor.freezer_temperature') | float > -12 }}"
      delay_on_secs: 1200
      priority: high
      reminder_frequency_mins: [10, 30]
      ack_required: true
      message: "The freezer is {{ states('sensor.freezer_temperature') }} °C."
      notifier: mobile_app_alices_phone
    - domain: house
      name: power_low
      threshold:
        value: "{{ states('sensor.ups_battery_charge') }}"
        hysteresis: 5
        minimum: 30
      priority: medium
      notifier: [mobile_app_alices_phone, alexa_kitchen]

After (with the group map above):

format: alert_redux
version: 1
alerts:
- name: Freezer too warm
  kind: template
  template: '{{ states(''sensor.freezer_temperature'') | float > -12 }}'
  priority: critical
  delay_on:
    seconds: 1200
  reminder_schedule:
  - 10
  - 30
  message: The freezer is {{ states('sensor.freezer_temperature') }} °C.
  notifier_groups:
  - Phone
  latching: true
- name: House Power low
  kind: threshold
  value_template: '{{ states(''sensor.ups_battery_charge'') }}'
  minimum: 30
  hysteresis: 5
  priority: warning
  notifier_groups:
  - Phone
  - Speakers
generators: []

Alert2 generators can't be converted (Alert Redux generators choose their targets differently), but the report suggests the settings for an equivalent generator, to create in the form.

Not converted, and reported: early_start, manual_on, manual_off, actions_on, title, target, data, done_notifier: false, and notifiers given as templates or entities.

After converting: what to check by hand

The converters are literal. Once your alerts are in, a few improvements are often worth making:

• Comparisons that should be thresholds. Above, Freezer too warm became a Template alert, because that's what it was. As a Threshold alert (Maximum −12) it would get hysteresis, and say exactly which sensor is missing when it goes offline. See Freezer too warm.
• Messages. The built-in alert's notifications were titled with your title; Alert Redux titles them with the alert's name. Check that the names read well as titles, and give alerts without messages real ones (the default is "{{ name }} is firing.").
• Priorities. Converted alerts are Warning (from alert), or mapped from Alert2's three levels. Five are available: make the important ones Critical or Emergency, the chores Informational. Priorities drive the card, quiet hours, and iPhone interruption levels.
• Mobile app data. Things like notification channels and clear_notification belong on the group's members now (and clearing is automatic for mobile app actions).
• New possibilities. Pairs of alerts that would be better as open / left open with supersession; near-identical alerts that could be one generator; automations that escalated alerts, which an Alert state alert can replace.