mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-23 01:06:52 +00:00
Improve automation templating docs (#16454)
This commit is contained in:
Erik Montnemery
GitHub
parent
a3a16a5fa9
commit
f277317a2e
@ -3,75 +3,11 @@ title: "Automation Templating"
|
||||
description: "Advanced automation documentation using templating."
|
||||
---
|
||||
|
||||
In Home Assistant 0.19 we introduced a new powerful feature: variables in scripts and automations. This makes it possible to adjust your condition and action based on the information of the trigger.
|
||||
|
||||
The trigger data made is available during [template](/docs/configuration/templating/) rendering as the `trigger` variable.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
# Example configuration.yaml entries
|
||||
automation:
|
||||
trigger:
|
||||
platform: state
|
||||
entity_id: device_tracker.paulus
|
||||
action:
|
||||
service: notify.notify
|
||||
data:
|
||||
message: >
|
||||
Paulus just changed from {{ trigger.from_state.state }}
|
||||
to {{ trigger.to_state.state }}
|
||||
|
||||
automation 2:
|
||||
trigger:
|
||||
platform: mqtt
|
||||
topic: /notify/+
|
||||
action:
|
||||
service: >
|
||||
notify.{{ trigger.topic.split('/')[-1] }}
|
||||
data:
|
||||
message: "{{ trigger.payload }}"
|
||||
|
||||
automation 3:
|
||||
trigger:
|
||||
# Multiple entities for which you want to perform the same action.
|
||||
- platform: state
|
||||
entity_id:
|
||||
- light.bedroom_closet
|
||||
- light.kiddos_closet
|
||||
- light.linen_closet
|
||||
to: "on"
|
||||
# Trigger when someone leaves one of those lights on for 10 minutes.
|
||||
for: "00:10:00"
|
||||
action:
|
||||
- service: light.turn_off
|
||||
data:
|
||||
# Turn off whichever entity triggered the automation.
|
||||
entity_id: "{{ trigger.entity_id }}"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## Important Template Rules
|
||||
|
||||
There are a few very important rules to remember when writing automation templates:
|
||||
|
||||
1. You **must** surround single-line templates with double quotes (`"`) or single quotes (`'`).
|
||||
1. It is advised that you prepare for undefined variables by using `if ... is not none` or the [`default` filter](http://jinja.pocoo.org/docs/dev/templates/#default), or both.
|
||||
1. It is advised that when comparing numbers, you convert the number(s) to a [`float`](http://jinja.pocoo.org/docs/dev/templates/#float) or an [`int`](http://jinja.pocoo.org/docs/dev/templates/#int) by using the respective [filter](http://jinja.pocoo.org/docs/dev/templates/#list-of-builtin-filters).
|
||||
1. While the [`float`](http://jinja.pocoo.org/docs/dev/templates/#float) and [`int`](http://jinja.pocoo.org/docs/dev/templates/#int) filters do allow a default fallback value if the conversion is unsuccessful, they do not provide the ability to catch undefined variables.
|
||||
|
||||
Remembering these simple rules will help save you from many headaches and endless hours of frustration when using automation templates.
|
||||
|
||||
## Trigger State Object
|
||||
|
||||
Knowing how to access the [state object](/docs/configuration/state_object/) of a trigger entity can be useful in automations. Here are a few ways to access the [`state`](#state), [`numeric state`](#numeric-state) and [`template`](#template) triggers:
|
||||
|
||||
* `trigger.from_state` will return the **previous** [state object](/docs/configuration/state_object/) of the entity.
|
||||
* `trigger.to_state` will return the **new** [state object](/docs/configuration/state_object/) that triggered trigger.
|
||||
* `states[trigger.to_state.entity_id]` will return the **current** [state object](/docs/configuration/state_object/) of the entity.
|
||||
Automations support [templating](/docs/configuration/templating/) in the same way as scripts do. In addition to the [Home Assistant template extensions](/docs/configuration/templating/#home-assistant-template-extensions) available to scripts, the `trigger` template variable is available.
|
||||
|
||||
<div class='note'>
|
||||
|
||||
Be aware that if you reference a `trigger` state object in templates of automation `action`, attempting to test that automation by calling the `automation.trigger` service or by clicking EXECUTE in the More Info box for the automation will not work. This is because the trigger state object doesn't exist in those contexts. One way to test automations like these is to manually check that the templates work as expected by pasting them in Developer Tools > Template together with your trigger's definition like:
|
||||
Be aware that if you reference a `trigger` state object in templates of an automation' `action` or `condition` sections, attempting to test that automation by calling the `automation.trigger` service or by clicking EXECUTE in the More Info box for the automation will not work. This is because the trigger state object doesn't exist in those contexts. One way to test automations like these is to manually check that the templates work as expected by pasting them in Developer Tools > Template together with your trigger's definition like:
|
||||
|
||||
{%raw%}
|
||||
```yaml
|
||||
@ -180,4 +116,49 @@ The following tables show the available trigger data per platform.
|
||||
| `trigger.zone` | State object of zone
|
||||
| `trigger.event` | Event that trigger observed: `enter` or `leave`.
|
||||
|
||||
## Examples
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
# Example configuration.yaml entries
|
||||
automation:
|
||||
trigger:
|
||||
platform: state
|
||||
entity_id: device_tracker.paulus
|
||||
action:
|
||||
service: notify.notify
|
||||
data:
|
||||
message: >
|
||||
Paulus just changed from {{ trigger.from_state.state }}
|
||||
to {{ trigger.to_state.state }}
|
||||
|
||||
automation 2:
|
||||
trigger:
|
||||
platform: mqtt
|
||||
topic: /notify/+
|
||||
action:
|
||||
service: >
|
||||
notify.{{ trigger.topic.split('/')[-1] }}
|
||||
data:
|
||||
message: "{{ trigger.payload }}"
|
||||
|
||||
automation 3:
|
||||
trigger:
|
||||
# Multiple entities for which you want to perform the same action.
|
||||
- platform: state
|
||||
entity_id:
|
||||
- light.bedroom_closet
|
||||
- light.kiddos_closet
|
||||
- light.linen_closet
|
||||
to: "on"
|
||||
# Trigger when someone leaves one of those lights on for 10 minutes.
|
||||
for: "00:10:00"
|
||||
action:
|
||||
- service: light.turn_off
|
||||
data:
|
||||
# Turn off whichever entity triggered the automation.
|
||||
entity_id: "{{ trigger.entity_id }}"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
[state object]: /docs/configuration/state_object/
|
||||
|
||||
@ -44,6 +44,17 @@ script:
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### Important Template Rules
|
||||
|
||||
There are a few very important rules to remember when adding templates to YAML:
|
||||
|
||||
1. You **must** surround single-line templates with double quotes (`"`) or single quotes (`'`).
|
||||
1. It is advised that you prepare for undefined variables by using `if ... is not none` or the [`default` filter](http://jinja.pocoo.org/docs/dev/templates/#default), or both.
|
||||
1. It is advised that when comparing numbers, you convert the number(s) to a [`float`](http://jinja.pocoo.org/docs/dev/templates/#float) or an [`int`](http://jinja.pocoo.org/docs/dev/templates/#int) by using the respective [filter](http://jinja.pocoo.org/docs/dev/templates/#list-of-builtin-filters).
|
||||
1. While the [`float`](http://jinja.pocoo.org/docs/dev/templates/#float) and [`int`](http://jinja.pocoo.org/docs/dev/templates/#int) filters do allow a default fallback value if the conversion is unsuccessful, they do not provide the ability to catch undefined variables.
|
||||
|
||||
Remembering these simple rules will help save you from many headaches and endless hours of frustration when using automation templates.
|
||||
|
||||
## Home Assistant template extensions
|
||||
|
||||
Extensions allow templates to access all of the Home Assistant specific states and adds other convenience functions and filters.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user