hass-alert2

KO | EN

gitlite — search

#python #javascript #typescript #docker #mysql #css #nodejs #php #react #machine-learning #java #html

★ 86 Open GitHub ↗

HomeAssistant alerting with native support for events and expressive conditions

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![GitHub Release](https://img.shields.io/github/v/release/redstone99/hass-alert2)](https://github.com/redstone99/hass-alert2/releases)
[![GitHub Release Date](https://img.shields.io/github/release-date/redstone99/hass-alert2)](https://github.com/redstone99/hass-alert2/releases)
[![GitHub commit activity](https://img.shields.io/github/commit-activity/y/redstone99/hass-alert2)](https://github.com/redstone99/hass-alert2/commits/master/)

# Alert2

Alert2 is a [Home Assistant](https://www.home-assistant.io/) component that supports alerting and sending notifications based on conditions and events. It's a retake on the original [Alert](https://www.home-assistant.io/integrations/alert/) integration.

## Table of Contents

- [New features](#new-features)
- [Installation](#installation)
- [Setup](#setup)
- [Description](#description)
- [Configuration](#configuration)
- [Generator patterns](#generator-patterns)
- [Front-end UI](#front-end-ui)
- [Actions and events](#actions-and-events)
- [Python alerting](#python-alerting)
- [Contributing](#contributing)

See also the companion guide, [Alert2 Recipes](Recipes.md), for additional examples to help you get started.

## New features

- **Native event-based alerting**. No need to approximate it with conditions and time windows.
- **Expressive condition-based alerts**
   - **Templates**.  No need for extra binary sensors. Also means the logic for an alert is in one place in your config file, which makes it easier to manage.
   - **Split on/off**.  Separately specify how a condition alert turns on & off.
- **Notification control**
   - **Snooze / disable / throttle notifications**. Handy for noisy sensors or while developing your alerts.
   - **Template notifiers**. Dynamically specify who gets notified.
   - **Superseding alerts**. Stage alerts to avoid redundant notifications from related alerts.
   - **Persistent notification details**. In your HA dashboard, you can view past alert firings as well as the message text sent in notifications.
- **Generator patterns**. Dynamically define multiple similar alerts, with wildcard support.
- **UI**
   - Create or edit alerts via the UI. Also reload YAML without restarting HA.
   - Overview card showing recently active alerts, prioritized, and custom, dynamic messages.
- **Hysteresis**. Reduce spurious alerts as sensors fluctuate.

Suggestions welcome! Start a [Discussion](https://github.com/redstone99/hass-alert2/discussions) or file an [Issue](https://github.com/redstone99/hass-alert2/issues).  Or follow the [development thread](https://community.home-assistant.io/t/alert2-a-new-alerting-component).

## Installation

<details>
<summary>HACS install (recommended)</summary>

1. If HACS is not installed, follow HACS installation and configuration instructions at https://hacs.xyz/.

1. Click the button below

[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=redstone99&repository=hass-alert2&category=integration)

or visit the HACS pane, type **Alert2** in the search field, expand "New" or "Available for download" if necessary, and click on **Alert2** to get to the details page.

If, for some reason, Alert2 does not show up as a HACS search result, you can add Alert2 manually by adding `https://github.com/redstone99/hass-alert2.git` as a custom repository of type `Integration` by following [these instructions](https://hacs.xyz/docs/faq/custom_repositories/).

1. The UI should now show the Alert2 doc page in HACS. Click "Download" button (bottom right of screen) to download the Alert2 integration.

If for some reason adding the repository did not take you to the Alert2 doc page, you may need to click again on the HACS pane, search for "Alert2" and click on it to get to the page (and the download button).

1. We strongly recommend also installing the [Alert2 UI](https://github.com/redstone99/hass-alert2-ui) card which is a compact way to view and manage Alert2 alerts.

</details>
<details>
<summary>Manual install</summary>

1. Download the `Source code (zip)` link from the repository [release section](https://github.com/redstone99/hass-alert2/releases) under "Assets" and extract it.

We do not recommend downloading directly from the `master` branch.

1. Create the directory `custom_components` in your Home Assistant configuration directory if it doesn't already exist.

Your configuration directory is the directory with `configuration.yaml`. It is commonly `/config`, or may be something like `~/.home-assistant/` for Linux installations.
   
1. Copy the `alert2` folder inside the `custom_components` directory in the `Source code` link you downloaded into the directory `custom_components` in your config.

Your config directory should look similar to this after copying:
 
 <config dir>/configuration.yaml
 <config dir>/custom_components/alert2/__init__.py
 <config dir>/custom_components/alert2/sensor.py
 ... etc...

1. We strongly recommend also installing the [Alert2 UI](https://github.com/redstone99/hass-alert2-ui) card which is a compact way to view and manage Alert2 alerts.

</details>

## Setup

Alert2 can be set up and managed either via the UI, via your `configuration.yaml` file, or both.

<details>
<summary>Setup via the UI</summary>

1. Go to Settings -> "Devices & Services" , then click on the "+ Add Integration" button

1. Search for and then click "Alert2", then "Finish"

1. Add the Alert2 Manager & Alert2 Overview cards from [Alert2 UI](https://github.com/redstone99/hass-alert2-ui).  You can created & edit alerts using the Manager card and view active alerts using the Overview card.

</details>

<details>
<summary>Setup via YAML</summary>

1. Add the following line to your `configuration.yaml`:

alert2:

The [Configuration](#configuration) section, below, has details on what else to add here.

1. Restart HomeAssistant

</details>

## Description

Alert2 supports two kinds of alerts:

- **Condition-based alerts**. The alert is "firing", aka "on", for a period of time, such as while a condition is true. This is similar to the existing [Alert](https://www.home-assistant.io/integrations/alert/) integration. Example: a temperature sensor that reports a high temperature.

- **Event-based alerts**. The alert is "firing" for just a moment, such as when a specified trigger occurs. Example: a problematic MQTT message arrives.

Configuration syntax and examples are in the [Configuration section]((#configuration)). Here is an overview:

### Condition alerts

Condition alerts can be specified in one of two modes:

1. **Standard**:  Condition alerts can specify a `condition` as a template or entity name. The alert turns on when the condition evaluates to true and turns off when the condition evaluates to false.

The alert can also specify a `threshold` dict that includes min/max limits and optional hysteresis.  If a threshold is specified, the alert is firing if the threshold is exceeded AND any `condition` specified is true.

2. **Separate on/off**: Alternatively, the alert can specify separate criteria for turning on and off. A set of config fields: `trigger_on`, `condition_on` and `manual_on` offer options for when the alert will turn on. And a corresponding set of config fields: `trigger_off`, `condition_off` and `manual_off` determine when the alert will turn off.

For either condition alert mode, hysteresis is available via the `delay_on_secs` parameter. If specified, the alert starts firing once the "on" criteria have been satisfied for the time interval specified. This is similar in motivation to the `skip_first` option in the old Alert integration.

The `supersedes` parameter specifies a hierarchical relationship between related condition alerts. If an alert is firing, notifications will be skipped for other alerts below it in the hierarchy.  An example might be one alert if the front door is open, and another superseding alert if the door is open and it's cold outside.

### Event alerts

Event alerts may be triggered either by an explicit `trigger` option in the config, or by the action `alert2.report`.
An event alert can also specify a `condition` as a template or entity name. The alert fires if it is triggered AND the condition evaluates to true.

### Common alert features

Each alert maintains a bit indicating whether it has been ack'd or not.  That bit is reset each time the alert fires. Ack'ing is done by clicking a button in the UI (described below) or calling the `alert2.ack` action. Ack'ing stops reminder notifications (see below) and is indicated visually in the UI.  The `alert2.unack` and `alert2.toggle_ack` actions are also available.

Each alert can specify a priority. Priority affects how the alert is displayed in the Alert2 UI Overview card.

### Notifications

Notifications are sent when an event alert fires, when a condition alert starts or stops firing, and periodically as a reminder that a condition alert is still firing.  You can optionally, via `acq_required`, request reminders until an alert is acked.  You can optionally request that notifications be sent at the end of periods when notifications where snoozed or throttled if there was any alert activity in the interval. This is via the `summary_notifier` config option.  We recommend setting `summary_notifier` to be notified when e.g., throttling ends.

Each notification by default includes some basic context information (detailed below).  An alert can also specify a template `message` to be sent  each time the alert fires. That message is sent out with notifications and also is viewable in the front-end UI.  Condition alerts can also specify a `done_message` to be sent when the alert stops firing, a `reminder_message` to customize reminder notifications, and if using `ack_required` an `ack_reminder_message` to customize the reminder that an alert has not yet been acked.

There are a few mechanisms available for controlling when and whether notifications are sent.

* `reminder_frequency_mins` - this config parameter specifies how often reminders are sent while an alert continues to fire. May be a list of values (similar to the `repeat` option in the old Alert integration).  May be set for condition alerts, or event alerts that have `ack_required` set.

* `throttle_fires_per_mins` - this config parameter throttles notifications for an alert that fires frequently. It affects notifications when an alert starts or stops firing. It does not affect alert reminder notifications.

* Ack'ing an alert prevents further reminders and the stop notification for the current firing of a condition alert. For both condition and event alerts, ack'ing also prevents any throttled notification of previous firings of the alert. Unack'ing an alert will restart notifications for a condition alert if it is still firing.

* Snoozing notifications for an alert implicitly acks the alert once and prevents any notifications from current or future firings of an alert for a specified period of time.

* Disabling notifications for an alert prevents any notifications until it is enabled again.  Snoozing & disabling affect only notifications. Alerts will still fire and be recorded for reviewing in your dashboard.

#### Notification text

The text of each notification by default includes some basic context information that varies based on the type of notification. That information may be augmented with the `message`, `done_message`, `reminder_message`, or `ack_reminder_message` options.  Notification text looks like:

* Event alert fires: `message` text prepended with name (or `friendly_name`) of alert.

Alert2 boiler_ignition_error: `message`

* Condition alert fires: `message` text prepended with name (or `friendly_name`) of alert.  Default message is "turned on" if no message specified. Alert name omitted if `annotate_messages` is false

Alert2 kitchen_door_open: turned on

* Condition alert reminder that it's still on. This can be customized via `reminder_message`. Alert name omitted if `annotate_messages` is false.

Alert2 kitchen_door_open: on for 5 m

* Condition alert stops firing: `done_message` text prepended with name (or `friendly_name`) of alert.  Default message is "turned off after ..." if no `done_message` specified. Only `done_message` text is sent if `annotate_messages` is false. Setting `annotate_messages` to false may be useful for notification platforms that parse the message (such as the "clear_notification" message of the `mobile_app` platform)

Alert2 kitchen_door_open: turned off after 10 m

* Either event or condition alert fires and exceeds `throttle_fires_per_mins`.  Message is prepended with "[Throttling starts]", which can not be overridden with `annotate_messages`:

[Throttling starts] Alert2 kitchen_door_open: turned on

* Throttling ends for event or condition alert that specified `throttle_fires_per_mins` and `summary_notifier` was specified.  Message includes information on what happened while the alert was throttled:

[Throttling ends] Summary: Alert2 kitchen_door_open: fired 10x (most recently 15m ago): turned off 19s ago after being on for 3m

* A reminder that the event or condition alert has not yet been acked.  Sent if `ack_required` is set and, if it's a condition alert, it is no longer firing (If it's still firing then you'll get normal reminder notifications). This can be customized via `ack_reminder_message`. Alert name omitted if `annotate_messages` is false.

Alert2 kitchen_door_open: not acked yet

#### Notifiers

You can specify which notifiers are used for alerting via the `notifier`, `done_notifier`, and `summary_notifier` config options. They may be a single notifier, a list of notifiers, a template resolving to a list of notifiers, or the name of an entity whose state is a list of notifiers. See [Notifier Config](#notifier-config) section, below.

During HA startup, HA initializes notifiers independently of the rest of HA.  So notifiers may not be ready even when HA declares that it has fully started.  Alert2 will automatically defer notifications during startup if a notifier does not yet exist. `notifier_startup_grace_secs` controls the length of the startup grace period.

You may also specify a YAML [notify group](https://www.home-assistant.io/integrations/group/#notify-groups). We recommend setting `defer_startup_notifications` if you choose to use a notify group. The issue is that HA may initialize the notify group early during startup, before the member notifiers are ready. And Alert2 can not see which member notifiers are ready. So Alert2 may notify a group with missing members, resulting in an internal error in the notify component. To avoid this, you can list your group names in `defer_startup_notifications` which will defer any notifications to those notifiers until `notifier_startup_grace_secs` has passed.

The current recommended way to notify groups is to create an entity, such as a template entity (e.g. `sensor.high_pri_group`), and set the members of the group as the state of the entity (example in [Notifier Config](#notifier-config) section, below).  Alert2 will then automatically defer notifications to notifiers in the group that do not yet exist during startup, without having to set `defer_startup_notifications`.

Alert2 does not yet support [Notify Entity Groups](https://www.home-assistant.io/integrations/group/#notify-entity-groups), but open an [discussion](https://github.com/redstone99/hass-alert2/discussions) and request the feature if interested.

Notifiers may be either legacy action names or the newer notify entity names.  Legacy action names can include or omit the "notify." prefix.  If notifier name could refer to either a notify entity or an action name, Alert2 will use the entity.

At present, notify entities support only the `message` and `title` fields. Specifying other fields like `data` with notify entities will result in an error.

Example:
```yaml
   # Uses the legacy notify.telegram_ha action
   notifier: telegram_ha
   
   # Uses the notify entity "notify.telegram_ha" if it exists
   # otherwise uses the legacy action "notify.telegram_ha".
   notifier: notify.telegram_ha
```

##### Telegram notifiers

If you're using telegram notifiers ([Telegram bot](https://www.home-assistant.io/integrations/telegram_bot/) integration), we recommend setting `parse_mode` in the notifier config to "html" (or "plain_text"). Telegram notifiers default to a parse_mode of "markdown".  If telegram can't parse a message, it throws an error and the message is not sent. "Markdown" is especially susceptible to such issues (e.g., if the message contains a "[").

### Alert2 internal errors

Alert2 automatically defines a few event alerts that fire internally:

* `alert2.alert2_global_exception` - This event alert fires if an HA task crashes due to an unhandled exception. This includes tasks for components outside Alert2.  For this alert, `throttle_fires_per_mins` defaults to `[20,60]` to limit alerts if some component goes into a crash loop. `exception_ignore_regexes` is also available to limit notifications from faulty components. See [Tracked](#tracked) section for an example.

* `alert2.alert2_warning` - This event alert fires if the config contains something that is likely wrong but not an error (for example setting `clear_notification` without setting `annotate_messages` to false).  It fires at most once for each type of warning over the lifetime of your HA install.

* `alert2.alert2_error` - This event alert fires on config errors and errors in Alert2 itself. If you specify a notifier that doesn't exist for `alert2_error` itself, then it falls back to `persistent_notification`.

Each of these alerts can be configured in your config, either YAML or via the UI.  To disable notifications for an alert, you can set the notifier to `null`. See example in the [Tracked](#tracked) section, below.

If you want to completely disable these internal alerts, you can set `skip_internal_errors` to true. However, note that if `alert2.alert2_error` fires indicating a problem, you may stop receiving alerts for things you do care about. So in a sense, this alert is at least as important as your most important alert.

## Configuration

Alert configuration is done through the `alert2:` section of your `configuration.yaml` file or via the [Alert2 UI](https://github.com/redstone99/hass-alert2-ui). There are examples below and also in [Alert2 Recipes](Recipes.md).

There are three subsections: `defaults`, `alerts`, and  `tracked`. If using the UI, config is done via the Alert2 Manager lovelace card.

We recommend that your config specify at least the following parameters:

```yaml
alert2:
  defaults:
    throttle_fires_per_mins: [ 10, 60 ] # throttle notifications for any alert that fires
                                        # more than 10x in 60 minutes
    notifier: foo # notifier name to use for most alerts
    summary_notifier: foo # notifier to use for summaries (e.g. when throttling ends)
```

Configuration may be reloaded on the fly by going to "Developer tools" -> "YAML" and clicking on "Alert2".  That deletes all alert2 alert entities and generators and then recreates them.  You can change defaults as well.  Reloading does not affect the startup-related config parameters `notifier_startup_grace_secs` and `defer_startup_notifications`.

### Top-level config options

The following are all optional.

| Key | Type | Description |
|---|---|---|
|`skip_internal_errors` | bool | If true, an entity for `alert2_error` will not be created, you will not receive any notifications for problems with your config file or Alert2 internal errors, and such errors won't show up in the Alert2 UI card.  Errors will still appear in the log file. Default is `false` |
| `notifier_startup_grace_secs` | float | Time to wait after HA starts for a notifier to be defined. See [Notifiers](#notifiers) section above for detailed explanation. Default is 30 seconds |
| `defer_startup_notifications` | bool or list | True means no notifications are sent until `notifier_startup_grace_secs` passes after startup. False means send notifications as soon as the notifier is defined in HA.  Or this parameter can be name of a single notifier or list of notifiers for those to defer during startup. Useful for notify groups. See [Notifiers](#notifiers) section above for more details |

Example:

alert2:
       skip_internal_errors: true
       notifier_startup_grace_secs: 60
       defer_startup_notifications: mygroup
       defaults:
         ...

### Defaults

The `defaults:` subsection specifies optional default values for parameters common to every alert. Each of these parameters may be specified either in this subsection or over-ridden on a per-alert basis.

| Key | Type | Description |
|---|---|---|
| `reminder_frequency_mins` | float or list | Interval in minutes between reminders that a condition alert continues to fire. May be a list of floats in which case the delay between reminders follows successive values in the list. The last list value is used repeatedly when reached (i.e., it does not cycle like the `repeat` option of the old Alert integration). If it is the empty list then no reminders are sent. Defaults to 60 minutes if not specified. Minimum is 0.01 min. Also used to control ack reminders for event or condition alerts that have `ack_required` set. |
| `reminder_message` | template | Template string evaluated each time a reminder notification will be sent. Variable `on_secs` contains float seconds alert has been on. Variable `on_time_str` contains time alert has been on as a string. The function `get_message()` will produce the `message` field. Defaults to: ` on for {{ on_time_str }}` Any message specified here will be prepended with alert domain and name unless `annotate_messages` is false.
| `notifier` | template | Name of notifiers to use for sending notifications. Notifiers are declared with the [Notify](https://www.home-assistant.io/integrations/notify/) integration. If specifying a legacy notifier, the action invoked will be `"notify." + notifier`. If specifying a notify entity, Alert2 calls `notify.send_message`. Defaults to `persistent_notification` (shows up in the UI under "Notifications"). Can be list of notifiers, an entity name whose state is a list of notifiers, a template that evaluates to either, or "null" to indicate no notification. See [Notifier Config](#notifier-config) section below for possibilities here. |
| `summary_notifier` | bool or template | True to send summaries (see [Notifiers](#notifiers) section for detail) using the same notifier as other notifications. False to not send summaries. Or can be a template similar to `notifier` parameter to specify notifier to use for summaries. Default is `false`. |
| `done_notifier` | bool or template | Controls notifier used to notify when a condition alert stops firing. True to use the `notifier` setting. False or null to not send done notifications. Or can be a template similar to `notifier` parameter to specify notifier to use for done notificaitons. Default is `true`. |
| `annotate_messages` | bool | If true, add extra context information to notifications, like number of times alert has fired since last notification, how long it has been on, etc. You may want to set this to false if you want to set done_message to "clear_notification" for the `mobile_app` notification platform. Defaults to true. |
| `throttle_fires_per_mins` | [int, float] | Limit notifications of alert firings based on a list of two numbers [X, Y]. If the alert has fired and notified more than X times in the last Y minutes, then throttling turns on and no further fire notifications occur until the rate drops below the threshold. For example, "[10, 60]" means you'll receive no more than 10 notifications of the alert firing every hour. Does not affect reminder notifications. Default is no throttling. You can set `summary_notifier` to be notified when throttling ends (by default you won't be). |
| `priority` | string | Can be "low", "medium", or "high". Affects display of alert in the Alert2 UI Overview card. Active alerts are sorted by priority and medium and high-priority alerts have a badge colored orange and red, respectively. May be template when used with generators. Default is "low" |
| `supersede_debounce_secs` | float | Suppress notifications of an alert if any superseding alert has fired within this many seconds of now. The purpose of this setting is to reduce extraneous notifications due to races between two alerts both turning on or off at almost the same time. Defaults to 0.5 seconds. Can be any value >= 0. |
| `icon` | string | Icon to display next to alert name in UI. Must be of form `prefix:name`. Defaults to `mdi:alert`. |
| `data` | dict or string | Dictionary passed as the "data" parameter to the notify action. May be either a dict or a template string that evaluates to a dict. Dict fields may be template strings. `data` may be overriden on a key-by-key basis for top-level keys. See doc in [Common alert features](#common-alert-features-1) |
| `persistent_notifier_grouping` | string | Can be "separate", "collapse" or "collapse_and_dismiss". When the `persistent_notification` notifier is used, controls how multiple notification messages for the same alert are handled. "separate" will keep each notification distinct. "collapse" will result in a single persistent notification (keeping only the most recent notification). "collapse_and_dismiss" is similar to "collapse" except the notification is also dismissed if the alert is a condition alert and it turns off. Defaults to "separate". |

Example:

alert2:
       defaults:
         reminder_frequency_mins: 60
         notifier: telegram
         annotate_messages: true
         throttle_fires_per_mins: [ 10, 60 ]
         icon: mdi:alert-rhombus

Note `reminder_frequency_mins` or `throttle_fires_per_mins` may be specified as a list using a YAML flow sequence or on separate lines. The following two are identical in YAML:

reminder_frequency_mins: [ 10, 20, 60 ]
        reminder_frequency_mins:
          - 10
          - 20
          - 60

### Alerts

The `alerts:` subsection contains a list of condition-based and event-based alert specifications. The full list of parameters for each alert are below.

Alert names are split into `domain` and `name`. The reason is partly for semantic clarity and also for future management features, like grouping alerts by domain. The entity name of an alert is `alert2.{domain}_{name}`. Alert2 requires that the entity name be unique after slugification ( which converts international symbols to ASCII and whitespace to "_", among other conversions ).

Entity name related fields:

| Key | Type | Required | Description |
|---|---|---|---|
|`domain` | string | required | part of the entity name of the alert. The entity name of an alert is `alert2.{domain}_{name}`. `domain` is typically the object causing the alert (e.g., garage door). Can be a template when used with [generator patterns](#generator-patterns). |
| `name` | string | required | part of the entity name of the alert. The entity name of an alert is `alert2.{domain}_{name}`. `name` is typically the particular fault occurring (e.g., open_too_long). Can be a template when used with [generator patterns](#generator-patterns). |
| `friendly_name` | template | optional | Name to display instead of the entity name. Surfaces in the [Alert2 UI](https://github.com/redstone99/hass-alert2-ui) overview card. Template tracks changes. |
| `icon` | string | optional | Override the default value of `icon` |

Alert firing related fields:

| Key | Type | Required | Description |
|---|---|---|---|
| `condition` | string | optional | Template string or entity name. Alert is firing if the template or entity state evaluates to truthy AND any optional `trigger` or `threshold` criteria are also satisfied. May not be combined with `condition_on`, `trigger_on`,`manual_on` or the "*_off" equivalents. |
| `trigger` | object | optional | A [trigger](https://www.home-assistant.io/docs/automation/trigger/) spec. Indicates an event-based alert. Alert fires when the trigger does, if also any `condition` specified is truthy. |
| `condition_on` | string | optional | Template string or entity name. Alert starts firing if the template or entity state switches to truthy AND any optional `trigger_on` criteria is also satisfied. This is edge-triggered - no change in alert state happens when `condition_on` becomes falsey. |
| `condition_off` | string | optional | Template string or entity name. Alert stops firing if the template or entity state switches to truthy AND any optional `trigger_off` criteria is also satisfied. This is edge-triggered - no change in alert state happens when `condition_off` becomes falsey. |
| `trigger_on` | object | optional | A [trigger](https://www.home-assistant.io/docs/automation/trigger/) spec. Alert turns on when the trigger triggers, if also any `condition_on` specified is truthy. |
| `trigger_off` | object | optional | A [trigger](https://www.home-assistant.io/docs/automation/trigger/) spec. Alert turns off when the trigger triggers, if also any `condition_off` specified is truthy. |
| `manual_on` | boolean | optional | Enables the action `alert2.manual_on` to turn the alert on. |
| `manual_off` | boolean | optional | Enables the action `alert2.manual_off` to turn the alert off. |
| `threshold:` | dict | optional | Subsection specifying a threshold criteria with hysteresis. Alert is firing if the threshold value exceeds bounds AND any `condition` specified is truthy. Not available for event-based alerts. |
| --&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`value` | string | required | A template or entity name that evaluates to a float to be compared to threshold limits. |
| --&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`hysteresis` | float | required | Compare `value` to limits using hysteresis. threshold is considered exceeded if value exceeds min/max, but does not reset until value increases past min+hysteresis or decreases past max-hysteresis. May be a (non-negative) float, template or entity name. (see description below) |
| --&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`maximum` | float | optional | Maximum acceptable value for `value`. May be a float, template or entity name. At least one of `maximum` and `minimum` must be specified. |
| --&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`minimum` | float | optional | Minimum acceptable value for `value`. May be a float, template or entity name. At least one of `maximum` and `minimum` must be specified. |
| `delay_on_secs` | float | optional | Specifies number of seconds that any `condition` must be true and any threshold specified must be exceeded before the alert starts firing. Similar in motivation to the `skip_first` option in the old Alert integration. Can be a template. Default is 0. |
| `early_start` | bool | optional | By default, alert monitoring starts only once HA has fully started (i.e., after the HOMEASSISTANT_STARTED event). If `early_start` is true for an alert, then monitoring of that alert starts earlier, as soon as the alert2 component loads. Useful for catching problems before HA fully starts. Not available for [generator patterns](#generator-patterns). |

Notification-related fields:

| Key | Type | Required | Description |
|---|---|---|---|
| `message` | template | optional | Template string evaluated when the alert fires. For event-based alerts, it can reference the `trigger` variable (see example below). Defaults to simple alert state change message like "... turned on". Any message specified here will be prepended with context information including the alert domain and name. Set `annotate_messages` to false to disable that behavior (eg if you want to send a notification command to the companion app mobile_app platform). |
| `done_message` | template | optional |Template string evaluated when an alert turns off. Defaults to simple alert state change message like "... turned off after x minutes". Any message specified here will be prepended with context information including the alert domain and name. Set `annotate_messages` to false to disable that behavior (eg if you want to send a notification command like "clear_notification" to the companion app mobile_app platform).
| `reminder_message` | template | optional | Override the default `reminder_message`. Can be set to `null` to cause Alert2 to use the system default reminder message. |
| `ack_reminder_message` | template | optional |Template string evaluated each time a reminder notification will be sent that an alert has not been acked. Used only is `ack_required` is set. `ack_reminder_message` defaults to: ` not acked yet` Any message specified here will be prepended with alert domain and name unless `annotate_messages` is false.
| `notifier` | template | optional | Override the default `notifier`. See [Notifier Config](#notifier-config) section below for examples. |
| `summary_notifier` | template | optional | Override the default `summary_notifier`. See [Notifier Config](#notifier-config) section below for examples. |
| `done_notifier` | template | optional | Override the default `done_notifier`. See [Notifier Config](#notifier-config) section below for examples. |
| `reminder_frequency_mins` | float | optional | Override the default `reminder_frequency_mins`|
| `annotate_messages` | bool | optional | Override the default value of `annotate_messages`. |
| `ack_required` | bool | optional | If set to truthy, reminder notifications will be sent until an alert has been acked. Reminders sent for events alert and condition alerts that have stopped firing. Default is false. |
| `ack_reminders_only` | bool | optional | If set to truthy, an acked condition alert will still send a notification when the alert stops firing. Default is false. |
| `title` | template | optional | Passed as the "title" parameter to the notify action |
| `target` | template | optional | Passed as the "target" parameter to the notify action |
| `data` | dict or string | optional | Dict or template string that evaluates to a dict. Overrides, on a key-by-key basis (for top-level keys), any default `data` dict specified. See doc in [Common alert features](#common-alert-features-1) |
| `throttle_fires_per_mins` | [int, float] | optional | Override the default value of `throttle_fires_per_mins` |
| `persistent_notifier_grouping` | bool | optional | Override the default value of `persistent_notifier_grouping`. |
| `exception_ignore_regexes` | string or list | optional | Only available for alerts with domain=alert2 name=global_exception, or tracked alert with name=unhandled_exception. When an exception occurs, the exception message concatenated with the stack trace is tested against the list of regexes. If a regex matches, no notification is sent, though the exception is still logged. Testing is done using python's re.search with re.DOTALL set, so the test searches within the string and '.' matches any character including newlines. See [Tracked](#tracked) section for an example. |

Generator-related fields:

| Key | Type | Required | Description |
|---|---|---|---|
| `generator` | template | optional | If specified, this alert is a [generator pattern](#generator-patterns). |
| `generator_name` | string | optional | Each generator creates a sensor entity with the name `sensor.alert2generator_[generator_name]`. See [generator patterns](#generator-patterns). If `generator_name` is not specified, a name like "anonymous_nnn" will be used, where "nnn" is a positive integer. |

Extra settings:
 
| Key | Type | Required | Description |
|---|---|---|---|
| `priority` | string | optional | Override the default value of `priority` |
| `display_msg` | template | optional | Message to display in the Alert2 UI overview card below the alert line. Appears while the alert is visible in the card. If not specified, no message is shown. |
| `supersedes` | List | optional | A list of domain+name pairs of alerts that this condition alert supersedes. Notifications will be skipped for superseded alerts while this alert is firing. Applies transitively. May use templates when used with generators. See [Supersedes](#supersedes) section below for examples. |
| `supersede_debounce_secs` | float | optional | Override the default value of `supersede_debounce_secs` |

#### Event-based alert

An event-based alert specifies a `trigger`, and fires when the trigger fires, as long as an optional `condition` is also true. Example:

alert2:
      alerts:
        - domain: boiler
          name: ignition_failed
          trigger:
           - platform: state
             entity_id: sensor.boiler_failed_ignition_count
          condition: "{{ (trigger.from_state is not none) and (trigger.to_state is not none) and (trigger.from_state.state|int(-1) > 0) and (trigger.to_state.state|int(-1) > 0) and (trigger.to_state.state|int > trigger.from_state.state|int) }}"
          #   can be an entity name, e.g.:
          # condition: binary_sensor.boiler_enabled
          message: "{{ trigger.from_state.state }} -> {{ trigger.to_state.state }}"

#### Condition-based alert

There are a few different forms of condition-based alerts.  The simplest is an alert that just specifies a `condition`. It is firing when the condition is true. The condition can be either a template or an entity name. Example of an alert to detect when the temperature is too low:

alert2:
 alerts:
 - domain: thermostat_fl2
 name: temperature_low
 condition: "{{ states('sensor.nest_therm_fl2_temperature')|float <= 50 }}"
 message: "Temp: {{ states('sensor.nest_therm_fl2_temperature') }}"
 
 - domain: thermostat_fl1
 name: temperature_low
 condition: binary_sensor.nest_therm_fl1_temperature_too_low
 message: ...

Notifications include by default context information, so the resulting text might be:

Alert2 thermostat_fl2_temperature_low: Temp: 45

An alert can alternatively specify a threshold with hysteresis.  So the previous temperature-low alert could be specified with hysteresis as:

alert2:
      alerts:
        - domain: thermostat_fl2
          name: temperature_low
          threshold:
            value: sensor.nest_therm_fl2_temperature
            #  can be a template. e.g.
            # value: "{{ states('sensor.nest_therm_fl2_temperature') }}"
            minimum: 50
            hysteresis: 5
          message: "Temp: {{ states('sensor.nest_therm_fl2_temperature') }}"

This alert would start firing if the temperature drops below 50 and won't stop firing until the temperature rises to at least 55.  A corresponding logic applies when a `maximum` is specified. Both `minimum` and `maximum` may be specified together.

A `condition` may be specified along with a `threshold`. In this case, the alert fires when the condition is true AND the threshold value is out of bounds.  `delay_on_secs` is another form of hysteresis that may be specified to reduce false alarms. It requires an alert condition be true or threshold be exceed for at least the specified number of seconds before firing. Note on a corner case: the count of seconds for delay_on_secs does not reset if the value switches instantaneously from exceeding the minimum to exceeding the maximum.

If a `condition` specifies an entity name, that's just syntactic shorthand for a `states()` expression. So `condition` may specify a template or an entity name, but not both at the same time. For example:

# ok
          condition: binary_sensor.room_basement

# equivalent
          condition: {{ states('binary_sensor.room_basement') }}

# not ok.
          # produces a string "binary_sensor.room_..." that is interpreted as a bool and errors.
          condition: binary_sensor.room_{{ genElem }}

# ok version
          # dynamically selects which binary_sensor to watch based on genElem variable (from generators)
          condition: {{ states('binary_sensor.room_' + genElem ) }}

##### Split on/off condition alerts

Instead of specifying `condition` or `threshold`, an alert may specify a combination of `condition_on`, `trigger_on`,`manual_on` and `condition_off`, `trigger_off`,`manual_off`.  At least one of the *_on must be specified and at least one of *_off must be specified.  Any combination is ok.

The semantics of trigger+condition are the same as for an event alert - e.g., if both `trigger_on` and `condition_on` are specified, the alert turns on if the trigger triggers and the condition is truthy.  Note that `condition_on` and `condition_off` are edge-triggered.  They cause state change only when the switch from falsey to truthy.  No alert state change happens when they switch back to falsey.

`delay_on_secs` is available with split on/off condition alerts.

Example:

alert2:
      alerts:
        # This alert starts firing when the smoke detector goes off, and continues to fire until
        # it is manually turned off.  The idea is to keep the alert firing until a person can
        # manually confirm the basement is ok, even if the smoke detector happens to turn off.
        - domain: basement
          name: possible_fire
          condition_on: "{{ states('binary_sensor.smoke_detector_basement') }}"
          manual_off: true
          display_msg: Smoke detector is "{{ states('binary_sensor.smoke_detector_basement') }}"

##### `supersedes`

The `supersedes` config parameter let's you set up a hierarchical relationship between related condition alerts. It is transitive. For example if A supersedes B, and B supersedes C, then that implies that A supersedes C.  And if an alert is firing, then notifications are skipped for alerts below it in the hierarchy. So if alert A is firing, then notifications are skipped for alerts B & C.

`supersedes` takes a list of domain+name pairs.  Here are some examples:

supersedes:
            - domain: test
              name: foo
            - domain: test
              name: foo2
              
          # Using yaml flow syntax
          # NOTE: space is required after the ':'.
          supersedes: [ { domain: test, name: foo }, { domain: test, name: foo2 } ]
                    
          # Can omit the [] if specifying a single alert
          supersedes: { domain: test, name: foo }

When used with a generator, `supersedes` also can take templates, in which case the variable `genPrevDomainName` is available and equals the domain+name of the previous generated element or null if it is the first element. Templates can be used to either produce the full dictionary or list of dictionaries, or may be used with individual domain / name items:

# String containing the domain/name dict        
          supersedes: "{ 'domain': 'test', 'name': '{{genElem}}_is_low' }"
          # Same
          supersedes: "{{ { 'domain':'test', 'name': genElem + '_is_low' } }}"

# YAML dict with template producing just the "name" field.
          supersedes: {  domain : test, name:  '{{ genElem }}_is_low' }

The following example creates two alerts, test_low_disk_20 and test_low_disk_10.  test_low_disk_10 will have `supersedes` set to `{ domain: "test", name: "low_disk_20" }`, and test_low_disk_20 will have `supersedes` set to `null`.

alert2:
 alerts:
 - domain: test
 name: "low_disk_{{ genElem }}"
 condition: "{{ states('sensor.disk_free_mb')|float < genElem }}"
 supersedes: "{{ genPrevDomainName }}"
 generator: [ 20, 10 ]
 generator_name: g1

To reduce spurious notifications due to races between two hierarchically-related alerts turning on or off at almost the same time, we offer the parameter `supersede_debounce_secs`, that defaults to 0.5 seconds. When an alert starts firing, the notification is delayed for `supersede_debounce_secs` to see if a superseding alert also starts firing.  Similarly, when an alert stops firing, the notifications of any superseded alerts are suppressed for the next `supersede_debounce_secs`.

#### Common alert features

Most template alert config fields can access the following extra variables for convenience: `alert_entity_id`, `alert_domain` and `alert_name`.

The variable `notify_reason` is also available to config fields related to notifications. `notify_reason` contains the reason for the notification and may take the following string values:

| Value | Description |
|---|---|
|`Fire` | A condition alert has started firing or an event alert fired. |
| `ReminderOn` | Reminder that a condition alert is still firing. |
| `StopFiring` | A condition alert has stopped firing. |
| `ReminderToAck` | Reminder that an alert has not yet been acked. |
| `Summary` | Summary of alert activity after notifications have been limited, either due to being snoozed or throttled. |

This should make it easier on iOS companion app to implement an "Ack" button in notifications and pass through the alert entity id to the event handler.

`notify_reason` is available to the fields:  `message`, `done_message`, `reminder_message`, `ack_reminder_message`, `target`, `title`, `notifier`, `done_notifier`, `summary_notifier` and `data`.

#### `Data` field

Alerts may pass additional data to the notifier via the `data` field. This is convenient for notification platforms such as [`mobile_app`](https://companion.home-assistant.io/docs/notifications/notifications-basic/). `data` can be either a dictionary or a template string that evaluates to a dict.  Values in the dict may be templates which produce string values. Dictionary can contain lists and sub-dictionaries. Templates can occur in nested sub-dictionaries.

For example:

alert2:
      alerts:
        - domain: cam_basement
          name: motion_while_away
          condition: "{{ (states('sensor.jdahua_basement_motion') == 'on') and
                         (states('input_select.homeaway') in [ 'Away-local', 'Away-travel' ]) and
                         ((now().timestamp() - states.input_select.homeaway.last_changed.timestamp()) > 5*60) }}"
          notifier: mobile_app_pixel_6
          title: "test title"
          data:
            group: motion-alarms
            timeout: 3
            sticky: true
            
            # String data field supports templates
            channel: "{% if notify_reason == 'Fire' %}channel-a{% else %}channel-b{% endif %}"
            channel: "{{ states('some entity id') }}"
            source_entity_id: "{{ alert_entity_id }}"

# nested dicts and templates
            actions:
              - action: foo
                title: "for-{{ notify_reason }}"

The `data` dict may be specified in multiple locations.  These are merged together to produce the final `data` dict passed to notifiers. The merge order is 1) `defaults` section of your YAML config, 2) "Defaults" in the UI "Alert Manager" card, 3) individual alert definition.  So the individual alert definition has the highest precedence.  The merge is done on a key-by-key basis for top-level keys.

For example, the following will result in a dict `{ a: 2, b: foo }` being sent to notifiers:

alert2:
      defaults:
        data: { a: 1 }
      alerts:
        - domain: test
          name: foo
          data: { a: 2, b: foo }

And the `data` field may be a single template string evaluating to a dict.  So the previous examlpe could also be written as follows. Note the extra quoting required:

alert2:
      defaults:
        data: "{{ { 'a': 1 } }}"
      alerts:
        - domain: test
          name: foo
          data: "{{ { 'a': 2, 'b': 'foo' } }}"

#### Notifier config

The `notifier` parameter can take a variety of different values. The basic usage can specify a single notifier or list of notifiers, or an entity whose state is a list of notifiers:

# Single notifier
          notifier: telegram_1

# List of notifiers (native YAML)
          notifier:
          - telegram_1              # legacy notifier
          - notify.telegram_bot_x_y # notify entity

# List of notifiers (YAML flow sequence, identical to list, above)
          notifier: [ telegram_1, telegram_2 ]

# List of notifiers as a string.
          # Will be interpreted as python literal, so inner quotes needed.
          notifier: "[ 'telegram_1', 'telegram_2' ]"

# Entity whose state is a list of notifiers (as a string)
          # for example, if sensor.my_notifier_list has state: "[ 'telegram_1', 'telegram_2' ]"
          # you might say:
          notifier: sensor.my_notifier_list

You can also specify a template that evaluates to either single notifier, a list of notifiers or to a single entity name that contains a list of notifiers

# The template can resolve to a single notifier
          notifier: "{% if states('binary_sensor.is_away')|bool %} mobile_app_a
                     {% else %} mobile_app_b {% endif %}"
          
          # It can resolve to a list of notifiers
          notifier: "{{ [ 'notifier_a', 'notifier_b' ] + [ 'notifier_c', 'notifier_d' ] }}"

# It can resolve to the name of an entity that has a notifier or list of notifiers
          # as its state.
          #
          # Suppose you have two entities, one with notifiers to use when away and another
          # to use when home.
          # say sensor.away_notifiers has state "[ 'notifier_a', 'notifier_b' ]"
          # and sensor.home_notifiers has state "notifier_c"
          # you could dynamically switch between them with:
          notifier: "{% if states('binary_sensor.is_away')|bool %} sensor.away_notifiers
                     {% else %} sensor.home_notifiers {% endif %}"

# Or say you want to conditionally notify a 3rd notifier, "mobile_app_josh":
          notifier: "{{ [ 'telegram_1', 'telegram_2' ] +
                        ( [ 'mobile_app_josh' ] if states('binary_sensor.is_away')|bool else [] ) }}"

A technical note on quoting and lists of notifiers: 
Templates evaluate to a string, even if they have a list inside. An entity's state also produces a string. Alert2 detects lists in such strings by evaluating the string as a python literal and seeing if a list results. So notifiers in such lists need to be quoted or the eval mechanism will think you're trying to name a variable.

An example of using an entity as an Alert2 native group.  Handles alerts fired during HA startup better than ["notify groups"](https://www.home-assistant.io/integrations/group/#notify-groups).

template:
      - sensor:
          - name: my_group
            state: "[ notifier1, notifier2 ]"
            # OR could be:
            state: "{{ [ 'notifier1', 'notifier2' ] }}"
    alert2:
      alerts:
        - domain: test
          name: motion_while_away
          condition: ...
          notifier: sensor.my_group

### Tracked

Alert2 internal alerts such as `alert2_error` or `alert2_global_exception` may be configured and support similar config fields as other alerts.

They may be configured via YAML or via the UI.  In a YAML config, they are configured in a separate `tracked` section of the config.  This section is for programatically triggered alerts and does not support the `message`, `trigger` or `condition` fields.

Example:

alert2:
      defaults:
        reminder_frequency_mins: 60
        notifier: telegram
      alerts:
        ...
      tracked:
        - domain: alert2
          name: error
          notifier: foo
          
        - domain: alert2
          name: global_exception
          # To limit frequency of messages
          throttle_fires_per_mins: [5, 60]
          # OR to completely disable messages
          notifier: null
          # To ignore certain exceptions
          exception_ignore_regexes: [ "a_flaky_component", "bar" ]
          ...

To configure an alert2 internal alert via the "Alert Manager" card in the UI, create an alert in the UI with domain `alert2` and the corresponding name.  E.g. domain `alert2` and name `global_exception`.  Then customize the fields you want. In the "Alert Manager" UI, the "Create" and "Delete" buttons create or delete a config entry for the internal alert; they don't create or delete the internal alert itself.

Lastly, the `tracked` config subsection is also for declaring your own event alerts that will only be triggered by invoking the action `alert2.report`. Declaring these alerts here avoids an "undeclared alert" alert when reporting, and also enables the system to restore the alert state when HomeAssistant restarts.

### Alert recommendations

We recommend setting a value for the default notifier or configuring `alert2_error` in the `tracked` section of the config so that alert2 error notifications will go somewhere you wish.

As described above in `early_start`, alerts by default don't start being monitored until HA fully starts.  This is to reduce template errors during startup due to entities not being defined yet.  However, the downside is that if some problem prevents HA from fully starting, none of your alerts will be monitored.  To prevent this, we provide a binary_sensor entity, `binary_sensor.alert2_ha_startup_done`, that turns on when HA has fully started. That entity also has an attribute, `start_time`, that is the time the module loaded. Together you can use them to alert if HA startup takes too long as follows:

alert2:
      alerts:
        - domain: general
          name: ha_startup_delayed
          # test against 'off' so we don't trigger during startup before binary_sensor has initialized
          condition: "{{ states('binary_sensor.alert2_ha_startup_done') == 'off' and
                (now().timestamp() - state_attr('binary_sensor.alert2_ha_startup_done', 'start_time').timestamp()) > 300 }}"
          message: "Starting for last {{ (now().timestamp() - state_attr('binary_sensor.alert2_ha_startup_done', 'start_time').timestamp()) }} seconds"
          early_start: true

If you have high-priority alerts, you might consider setting `notifier` to be a high-priority notifier and `summary_notifier` to be a low-priority notifier.  And set `priority` to `high` or `medium` as well to make them stand out in the Alert2 UI Overview card.

Also, alert2 entities are built on `RestoreEntity`, which backs itself up every 15 minutes. This means, alert firing may not be remembered across HA restarts if the alert fired within 15 minutes of HA restarting.

### Migrating from Alert

Here is an example of converting an old Alert-style config to Alert2. It shows many of the common options. You may find you don't need to set the `message` and `done_message` fields in some of your alerts since the default messaging in Alert2 conveys the alert name and whether it's turning on or off.

Old Alert:

````yaml
 garage_door:
   name: The Garage Door is open
   title: "[HA] Garage Door alert"
   message: The Garage Door is still open
   done_message: The Garage Door is now closed
   entity_id: cover.garage_door
   state: "open"
   repeat: # first notification after 30', then 60', then every 2h
     - 30
     - 60
     - 120
   can_acknowledge: true
   skip_first: true
   notifiers:
     - telegram_me
     - telegram_her
     - email_me
````

Converted to Alert2:

````yaml
 alerts:
    - domain: Garage Door
      name: Open for too long
      title: "[HA] Garage Door"
      message: The door is still open
      done_message: The door is now closed
      condition: "{{ states('cover.garage_door') == 'open' }}"
      delay_on_secs: 600 #first notif delayed for this  many secs
      reminder_frequency_mins: [30, 60, 120]
      # Example uses newer notify entities for telegram and the legacy notify action for email
      notifier: [notify.telegram_me, notify.telgram_her, email_me]
````

And note that Ack/Snooze can be managed via the [Alert2 UI](https://github.com/redstone99/hass-alert2-ui) Overview card.

## Generator patterns

Generator patterns let you create multiple, similar alerts dynamically, and can be based on a wild-card search of entities.  Here's an example of a generator watching for battery_plus entities reporting a low battery:

```yaml
alert2:
  alerts:
    - generator_name: low_bat
      generator: "{{ states.sensor|selectattr('entity_id','match','sensor.*_battery_plus')
                                  |map(attribute='entity_id')
                                  |list }}"
      domain: battery
      name: "{{ genEntityId|regex_replace('sensor.(.*)_battery_plus', '\\\\1') }}_is_low"
      condition: "{{ state_attr(genEntityId, 'battery_low') }}"
    #
    # or, slightly more succinctly using entity_regex()
    #
    - generator_name: low_bat
      generator: "{{ states.sensor|entity_regex('sensor.(.*)_battery_plus')|list }}"
      domain: battery
      name: "{{ genGroups[0] }}_is_low"
      condition: "{{ state_attr(genEntityId, 'battery_low') }}"
    #
    # or, with an explicit list of names
    #
    - generator_name: low_bat
      generator: [ 'dev1', 'dev2', 'dev3' ]
      domain: battery
      name: "{{ genElem }}_is_low"
      condition: "{{ state_attr('sensor.'+genElem+'_battery_plus'), 'battery_low') }}"
    
```

Suppose there are three battery_plus entities:

sensor.dev1_battery_plus
    sensor.dev2_battery_plus
    sensor.dev3_battery_plus

Then any of the above generators will create three condition alerts:

alert2.dev1_is_low
    alert2.dev2_is_low
    alert2.dev3_is_low

where `alert2.dev1_is_low` will fire if the "battery_low" attribute of `sensor.dev1_battery_plus` becomes true, and similarly for the other two alerts.

Here's how the first generator, above, is working:

1. `generator` specifies a template.
1. The template starts with the set of all sensor entities, filters for those whose entity_id matches the regex, and returns the list of matching entity_ids.
1. Alert2 creates an alert for each entity_id in the list. That entity_id is made available to all template config fields via the `genEntityId` variable. `domain` and `name` also accept templates for generator alerts.
1. A sensor will also be created, `sensor.alert2generator_low_bat`, whose state will be the number of alerts created by the generator. The sensor has an attribute, `generated_ids`, which is a the list of the entity_id of each alert created.  This is useful for verifying that the generator is producing the expected number of alerts.

The second generator example, above uses the `entity_regex` filter. Using that filter makes available to all template config fields the variable `genEntityId` with the entity_id as well as the variable `genGroups` with the regex groups that matched.

The third generator lists strings that are not entity_ids.  In this case, those strings are available as `genElem` to template config fields and `genEntityId` is not defined.

See the [Reference](#reference) section below for a complete list of possibilities.

Generators may be used to create either condition alerts or event alerts.

#### How it works

`generator` config field specifies a list of objects. An alert is created for each object. If that object is a string and the string is an entity_id, then it is put in the variable `genEntityId`. If the string is not an entity_id, then it is put in the variable `genElem`.  If the object is a dictionary, then the keys of the dictionary are defined as variables.  `entity_regex()` returns a list of dictionaries with `genEntityId` and `genGroups` as keys.

As a fallback, for any object in the list, the variable `genRaw` is defined as the object.

Generators track HA entity life cycles and so will dynamically create or destroy alerts as the set of entities changes. Technical note: by default in HA, using "states|" or "states.sensor|" in a template causes the template to be reevaluated every time the state of any entity in HA changes. For generator templates, we change this behavior so it only updates on entity life cycle events (to reduce unnecessary re-renderings).

Generators do not start generating until HA fully starts. `early_start` is not available for them or the alerts they create.

Last implementation detail:  templates actually render to strings. So "{{ [ 1, 2 ] }}" renders to the string "[1, 2]".  Alert2 internally does a literal_eval to convert the string back into a list.

Really last implementation detail: any templates specified for `domain` or `name` are evaluated only when the generator creates a new alert - i.e. so you can't change the domain/name of an alert on the fly (though you can change `friendly_name`).

#### Generators and triggers

Generator variables (eg `genElem`) are available to trigger fields that accept templates.

In addition, you may also specify a template in the `entity_id` field of a `state` trigger when used with generators (normally HA doesn't allow templates in the `entity_id` field).  That template will be rendered once when the generator creates an alert - the template does not track changes. So you can say:
````
  - domain: test
    name: my_alert
    generator: ...
    trigger:
      - trigger: state
        entity_id: "{{ genEntityId }}"
````

### Reference

#### `generator`

`generator` can take multiple forms. Each is a list of some sort, and an alert is created for each element of the list.
````yaml
    # A native YAML list.
    # genEntityId is defined to be each element in the list if the element is an entity_id
    # genElem is defined otherwise.
    # genRaw is defined to be each element regardless.
    generator: [ foo1, foo2 ] # YAML flow sequence
    generator:
       - foo1
       - foo2

# A template evaluating to a list of strings.
    generator: "{{ [ 'sensor.foo1', 'sensor.foo2' ] }}"

# A template evaluating to a string containing a list inside.
    generator: "{{ '[ \'a\', \'b\' ]' }}"
    # OR, if sensor.mylist is [ 'a', 'b' ], then equivalently
    generator: "{{ states('sensor.mylist') }}"

# A template evaluating to list of dictionaries
    # The keys of the dictionary are available as variables in all Alert2
    # template fields
    # genRaw is defined as the raw dictionary object.
    generator: "{{ {'a':'foo'}, {'a':'bar'} }}"
````

In addition to the variables `genElem`, `genEntityId`, and `genRaw` described above, generators also make the following variables available to templates:
* `genIdx` - the index, starting from 0, of the current generator element.
* `genPrevDomainName` - the {domain,name} of the previous generator element, or None if this is the first element.

With these, you can create a staged alert such as follows:

````yaml
alert2:
 alerts:
 - domain: test
 name: "low_disk_{{ genElem }}"
 condition: "{{ states('sensor.disk_free_gb')|float < genElem }}"
 supersedes: "{{ genPrevDomainName }}"
 generator: [ 20, 10, 1 ]
 priority: "{{ ['low','medium','high'][genIdx] }}"
 generator_name: g1
````

The above creates three alerts, alerting on progressively lower free disk space.  Each alert has a higher priority than the previous alert and each alert supersedes the alert before it.

An alternative way of expressing the above generator is to collect variables together in the generator itself. So it could instead be written as:
````yaml
alert2:
 alerts:
 - domain: test
 name: "low_disk_{{ freeGb }}"
 condition: "{{ states('sensor.disk_free_gb')|float < freeGb }}"
 supersedes: "{{ genPrevDomainName }}"
 generator:
 - { freeGb: 20, pri: low }
 - { freeGb: 10, pri: medium }
 - { freeGb: 1, pri: high }
 priority: "{{ pri }}"
 generator_name: g1
````

#### `entity_regex`

`entity_regex` is a filter function that consumes a list of entities, filters them and generates a list of dictionaries.  It has the following signature:

````python
entity_regex( find_regex, ignorecase=False )
````

`find_regex` is a regex tested against the entity_id of each entity. `find_regex` is tested using regex `match()`, which identifies matches only at the start of the entity_id string.  To ensure matches match the entire entity_id rather than just a prefix, be sure to end your `find_regex` with "$".

For each entity that matches, the output list includes a dictionary that maps "genEntityId" to the matched entity_id and `genGroups` to the list of regex groups (using match.groups())

Here are some examples intended to match temperature sensors such as `sensor.temp_fl1`, `sensor.temp_fl2` and so forth.

````python
# Default behavior with group present in regex
# genEntityId = sensor entity_id
# genGroups   = ["fl1"] then ["fl2"] ...
generator: "{{ states.sensor|entity_regex('sensor.temp_(.*)')|list }}"

# No regex group
# genEntityId = sensor entity_id
# genGroups   = []
generator: "{{ states.sensor|entity_regex('sensor.temp_.*')|list }}"
````

Instead of `states.sensor`, you could use `states` or `states.binary_sensor` and so forth in the above examples.

If you wanted to alert on low temperature, but don't want to use `entity_regex`, you could alternatively say something like:
````yaml
alert2:
 alerts:
 - generator_name: low_temp
 # genElem will be the entity_id
 generator: "{{ states.sensor|selectattr('entity_id', 'match', 'sensor.temp_.*')
 |map(attribute='entity_id')|list }}"
 domain: thermostat
 # See note on backslashes in regexes, later in this doc.
 name: "{{ genEntityId
 |regex_replace('sensor.temp_(.*)','\\\\1') }}_is_low"
 condition: "{{ states(genEntityId)|float < 40 }}"
 #
 # or equivalently
 #
 - generator_name: low_temp
 # genElem will be "fl1", "fl2", ...
 generator: "{{ states.sensor|selectattr('entity_id', 'match', 'sensor.temp_.*')
 |map(attribute='entity_id')
 |regex_replace('sensor.temp_(.*)', '\\\\1')
 |list }}"
 domain: thermostat
 name: "{{ genElem }}"
 condition: "{{ states('sensor.temp_'+genElem)|float < 40 }}"
````

## Front-end UI

We recommend also installing the [Alert2 UI](https://github.com/redstone99/hass-alert2-ui), which includes one card for viewing recently active alerts and another card for creating or editing alerts. Alert2 UI also enhances the information shown in the "more-info" dialog when viewing Alert2 entities.

Defaults set via the UI take priority over defaults set in YAML for both YAML alerts and UI-created alerts.  Alert2 does not allow any two alerts created via the UI or YAML to have the same domain and name.

Alert2 supports reloading configuration via the UI.  Go to "Developer Tools" -> "YAML" and click on "Alert2".  That will reload the YAML config as well as all UI-created alerts.

If you ever need to know, Alert2 stores the UI state, including entities defined, in your configuration directory in a JSON file called `.storage/alert2.storage`.

![Alert2 overview card](https://raw.githubusercontent.com/redstone99/hass-alert2/master/resources/overview.png)
![Alert2 management card](https://raw.githubusercontent.com/redstone99/hass-alert2/master/resources/manager.png)

Without [Alert2 UI](https://github.com/redstone99/hass-alert2-ui) you can still view and do some management of Alert2 alerts, but the process is a bit more involved.

### Editing Alert2 entity settings

Alert2 sets a `unique_id` on each alert and generator entity. This means you can adjust HA entity settings for the alert via the HA more-info pop-up dialog. A few notes:

We recommend setting `friendly_name` in your Alert2 config rather than editing the `name` field in the entity settings, just to avoid confusion. The entity setting for `name` will override any `friendly_name` set.

You may see old alert entities persist briefly with a state of "unavailable", particularly in the 10 seconds after HA startup if one of your generators changes the set of alerts it generates.  What going on is that the set of Alert2 entities in existence can fluctuate, as you adjust your Alert2 config or as generators update. If Alert2 stops creating an alert (eg on restart), then since the `unique_id` is set, the dead alert will persist with a state of "unavailable".  Alert2 strives to avoid this by updating the entity registry during Alert2 lifecycle changes.  And 10 seconds after HA starts up or Alert2 reloads, Alert2 it will go through and purge the entity registry of those dead alerts.

### A note on regexes and escaping

Escaping in a regex requires two backslashes when entered in the HA UI, or four backslashes when entered in YAML.  For example, to call regex_replace() with a group reference in a template you'd do the following:

Via the UI (eg the Alert2 Manager card or via dev tools template evaluator):

In your YAML config:

## Actions and events

Alert2 defines a few new actions.

Action `alert2.report` notifies the system that an event-based alert has fired. It takes two parameters, the "domain" and "name" of the alert that fired.  You can also pass an optional `message` argument specifying a template for a message to include with the firing notification. That domain/name should be declared in either the `tracked` or `alerts` section of your config (described above).  `alert2.report` overrides any `condition` and `trigger` specified in the event alert declaration.

You may also pass a `data` dictionary. This is merged with any default dictionary configured.

An example of using alert2.report in the action section of an automation:

trigger:
          ...
        condition:
          ...
        action:
          - service: alert2.report
            data:
              domain: "boiler"
              name: "fault_{{trigger.event.data.name}}"
              message: "code is {{ trigger.event.data.dData.Code }}"

A few other actions are available, some of which are used internally by [Alert2 UI](https://github.com/redstone99/hass-alert2-ui):

`alert2.ack_all` acks all alerts.
 `alert2.notification_control` adjust the notification settings.
 `alert2.ack` acks a single alert.
 `alert2.unack` unacks a single alert.
 `alert2.toggle_ack` toggles an alert between acked and unacked.
 `alert2.manual_on` turns on a condition alert that was configured with `manual_on: true`.
 `alert2.manual_off` turns off a condition alert that was configured with `manual_off: true`.
 `alert2.get_display_msg` renders the `display_msg` field for an alert and returns it.

More details on these calls are in the [`services.yaml`](https://github.com/redstone99/hass-alert2/blob/master/custom_components/alert2/services.yaml) file in this repo, or in the UI by going to "Developer tools" -> "Actions".

### Events

Alert2 will fire events on the hass bus as follows:

| event_type | data fields | description |
|---|---|---|
| `alert2_create` | <pre>entity_id domain name</pre> | Fires when an alert is created. Also fires on reloading or updating an alert via the UI. |
| `alert2_delete` | <pre>entity_id domain name</pre> | Fires when an alert is deleted. Also fires on reloading or updating an alert via the UI. |
| `alert2_alert_fire` | <pre>entity_id domain name</pre> | Fires when an event alert fires. |
| `alert2_alert_on` | <pre>entity_id domain name</pre> | Fires when a condition alert turns on (starts firing). |
| `alert2_alert_off` | <pre>entity_id domain name</pre> | Fires when an event alert turns off (stops firing). |
| `alert2_alert_ack` | <pre>entity_id domain name</pre> | Fires when an alert is acked. |
| `alert2_alert_unack` | <pre>entity_id domain name</pre> | Fires when an alert is unacked. |

Example of triggering an automation based on a condition alert turning on or off:

````
automation:
  - trigger:
       platform: event
       event_type: alert2_alert_on
    action:
       ...

- trigger:
       platform: event
       event_type: alert2_alert_off
    action:
       ...
````

## Python alerting

If you're developing python components, Alert2 is handy for alerting on unexpected conditions. The way to do that is:

1. In the `manifest.json` for your component, put a dependency on alert2. This is to ensure alert2 has initialized before your component.

{
            "domain": "mydomain",
            "name": "My Component",
            ...
            "dependencies": [ "alert2" ]
        }

1. In your component, import `alert2` and in `async_setup` declare whatever event alerts you might want to trigger. E.g.:

import custom_components.alert2 as alert2

async def async_setup(hass, config):
            await alert2.declareEventMulti([
                { 'domain': 'mydomain', 'name': 'some err 1' },
                { 'domain': 'mydomain', 'name': 'some err 2' },
                ...
            ])

1. To trigger an alert, call `report()`, which takes an optional message argument. E.g.:

if unexpected_thing_happens:
            alert2.report(DOMAIN, 'some err 1', 'optional message string')

The alert2 module also offers a `create_task()` and `create_background_task()` method to create tasks. It's similar to `hass.async_create_task` except it also `report()`s uncaught exceptions - so your task doesn't die silently.  Should only be called from the event loop. Example usage:

```
async def testTask():
    pass
taskHandle = alert2.create_task(hass, 'mydomain', testTask())
#
# Later on, cancel task if you want
taskHandle.cancel()
```
If an unhandled exception occurs, alert2 will fire an alert: `alert2.mydomain_unhandled_exception`.  `declareEventMulti()` automatically declares `mydomain_unhandled_exception` if you haven't already.

## Contributing

We welcome ideas for improving Alert2 or help implementing any of the great ideas people have suggested so far. A number of great ideas have arisen on the main [development thread](https://community.home-assistant.io/t/alert2-a-new-alerting-component) as well as on [Github issues](https://github.com/redstone99/hass-alert2/issues).

Feel free to jump in on any of the threads!

### Testing

To run the tests:

cd [ hass-alert2 directory ]
    python3 -m venv venv
    venv/bin/pip install --upgrade -r requirements.txt -r requirements_test.txt
    venv/bin/pytest

You can run each test individually and/or load the alert2 source code from a different directory.
If your custom_components directory is in /myha/custom_components, you'd say:

JTESTDIR=/myha venv/bin/pytest --show-capture=no tests/test_t1.py
    JTESTDIR=/myha venv/bin/pytest --show-capture=no tests/test_ui.py

To run the tests in hass-alert2-ui, you'll need to run the dummy server. It listens on port 50005. If you're alert2-ui repo is in /tmp/hass-alert2-ui, you'd run the dummy server like:

JTEST_JS_DIR=/tmp/hass-alert2-ui  venv/bin/pytest tests/dummy_server.py

hass-alert2

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README