2022.5: Automation & scripts features

source/_posts/2022-05-04-release-20225.markdown

@@ -131,34 +131,9 @@ via the overflow menu (the three dots in the top right).
 
 ## New automation & script features
 
-{% details "TODO" %}
-
-- Order of all chapters; should they be subsections?
-- If-Then:
-  - Replace screenshot
-  - Check story/contents
-  - Shorter example?
-- Calendar trigger:
-  - Replace screenshot
-  - Check story
-- For each:
-  - Improve story
-  - Better example?
-- Parallelizing actions:
-  - Simplify?
-  - Less warnings to make it less negative?
-- Stopping a script or automation:
-  - Replace screenshot
-  - Story... is meh
-- The more stuff section... Its just a lot, figure out a way
-  to organize the story.
-
-{% enddetails %}
-
-
 This release is packed with new automation & script features! Some have been
-added to the UI, and others are advanced features that are currently only
+added to the UI, and others are advanced features that are only available when
-available when using YAML.
+using YAML.
 
 One thing almost all these changes have in common: They have been requested
 and voted for by the community in our [Feature Requests] forum.
@@ -175,11 +150,15 @@ While this structure is very flexible and extensive, there was still a desire
 for an if-then(-else) structure that is small, simple, compact, and clean.
 This release brings you just that.
 
-The new if-then action is available via the automations and scripts editors.
+The new if-then action is available via YAML and via the UI using automations
+and scripts editors.
 
-<img class="no-shadow" src='https://user-images.githubusercontent.com/195327/162737991-d97d3cf0-2039-4ebe-9295-1c3d7fdeff90.png' alt='Screenshot showing If-then'>
+<img class="no-shadow" src='/images/blog/2022-05/if-then.png' alt='Screenshot showing If-then'>
 
-An example in YAML:
+{% details "If-then example in YAML" %}
+
+If YAML automations are more your thing, this is how you can use the new
+if-then action in your automations and scripts.
 
 ```yaml
 actions:
@@ -200,22 +179,69 @@ actions:
           message: "Skipped cleaning, someone is home!"
 ```
 
-[More information can be found in the scripts documentation](/docs/scripts/#if-then)
+Note that that `if` also supports a shorthand condition templates (if that
+is more your style), for example:
+
+{% raw %}
+
+```yaml
+actions:
+  - if: "{{ states('zone.home') == 0 }}"
+    then:
+      - alias: "Then start cleaning already!"
+        service: vacuum.start
+        target:
+          area_id: living_room
+```
+
+{% endraw %}
+
+{% enddetails %}
+
+[More information can be found in the scripts documentation](/docs/scripts/#if-then).
 
 ### Calendar trigger
 
-This release [@allenporter] gave the [Calendar] integration (and the
+[@allenporter] gave the [Calendar] integration (and the [Google Calendars]
-[Google Calendars] integration lots of love. In the process, a new Calendar
+integration) lots of love. In the process, a new Calendar trigger was added,
-trigger was added, which is available for use in your automations.
+which is available for use in your automations.
 
-<img class="no-shadow" src='/images/integrations/calendar/trigger.png' alt='Screenshot showing the calendar trigger'>
+<p class='img'>
+<img class="no-shadow" src='/images/blog/2022-05/calendar-trigger.png' alt='Screenshot showing the new calendar trigger in the UI'>
+The new calendar trigger is available in the automation editor.
+</p>
 
-This brand new trigger is a little more flexible compared to the (previously
+This brand new trigger is slightly more flexible than the (previously only
-only other option) state trigger. It is available for automation in YAML as well,
+other option) state trigger. It is available for automations in YAML as well,
-and the trigger provides [a lot of trigger variables](/docs/automation/templating/#calendar)
+and the trigger provides [lots of trigger variables](/docs/automation/templating/#calendar)
 you can use in your templates.
 
-[More information can be found in the Calendar integration documentation](/integrations/calendar/#automation)
+{% details "Calendar trigger example in YAML" %}
+
+The calendar trigger is, of course, also available in YAML. This automation
+example shows the use of the trigger and some of the variables it provides.
+
+{% raw %}
+
+```yaml
+automation:
+  trigger:
+    - platform: calendar
+      event: start
+      entity_id: calendar.personal
+  action:
+    - service: persistent_notification.create
+      data:
+        message: >-
+          Event {{ trigger.calendar_event.summary }} @
+          {{ trigger.calendar_event.start }}
+```
+
+{% endraw %}
+
+{% enddetails %}
+
+[More information can be found in the Calendar integration documentation](/integrations/calendar/#automation).
 
 [@allenporter]: https://github.com/allenporter
 [Calendar]: /integrations/calendar/
@@ -223,16 +249,16 @@ you can use in your templates.
 
 ### For each
 
-We had a number of options available to repeat a [group of actions]. For
+We had several options available to repeat a [group of actions]. For example,
-example, repeating based on a count, repeating while a condition passes, and
+repeating based on a count, while a condition passes, or until a condition
-repeating until a condition passes.
+passes.
 
-These have been very powerful, but repeating a sequence for each item in a list
+These are very powerful, but repeating a sequence for each item in a list
-was also requested and voted for. This release implements: For each.
+was also requested and voted for. This release adds: For each.
 
-This is an advanced feature and is only available for use in YAML right now.
+This is an advanced feature and is only available for use in automations written
-Here is an example of a for each that sends out two notifications in different
+manually in YAML. Here is an example that sends out two notifications in
-languages:
+different languages:
 
 {% raw %}
 
@@ -253,29 +279,81 @@ repeat:
 {% endraw %}
 
 Each item in the list will be run against a sequence of actions, and the item
-is available as a variable you can use in your templates. The list of
+is available as a variable you can use in your templates. The items you can
-items you can provide to `for_each` can be mappings, lists of just strings,
+provide to `for_each` can be mappings, lists of just strings, and even complex
-and even complex templates that provide a list as a result.
+templates that provide a list as a result.
 
-[More information can be found in the scripts documentation](/docs/scripts/#for-each)
+[More information can be found in the scripts documentation](/docs/scripts/#for-each).
 
 [group of actions]: /docs/scripts/#repeat-a-group-of-actions
 
-### Continue on error
+### Disable any trigger, condition, or action
 
-An automation and script run a sequence of actions. One of the comments and
+Sometimes, you may want to disable a specific trigger, action, or condition,
-questions we often see/read/get is: "If one of the actions fails, why does
+whether this is for testing, a temporary workaround, or any other reason.
-the whole automation stop?"
 
-Good question! To answer this, we have added a new feature: Continue on error.
+In YAML, you'd comment out parts of your automation, but if you wanted
-This will enable you to allow certain steps in an automation or script sequence
+to do that in the UI, the only option you have is to delete it from the
-to fail, without interrupting the whole sequence.
+automation or script.
 
-This is an example of a script that will always run the second action, even
+In this release, we added support for disabling a trigger, action, or condition;
-if the first action fails with an error.
+without the need for removing it or commenting it out! A disabled trigger
+won't fire, a disabled condition always passes, and a disabled action is
+skipped.
+
+<img class="no-shadow" src='/images/blog/2022-05/disabled-condition.png' alt='Screenshot showing an disabled condition in an UI automation'>
+
+{% details "Disabled example in YAML" %}
+
+If YAML automations are more your thing, this disabled feature is still
+helpful. While, of course, you can still comment parts out easily; using the
+this feature will make disabled parts still show up in automation and
+script debug traces.
+
+Every trigger, condition, and action now has an `enabled` parameter. Which
+you can set to `false` to disable that section. For example:
 
 ```yaml
-sequence:
+# Example automation with a disabled trigger
+automation:
+  trigger:
+    # This trigger will not trigger, as it is disabled.
+    # This automation does not run when the sun is set.
+    - enabled: false
+      platform: sun
+      event: sunset
+
+    # This trigger will fire, as it is not disabled.
+    - platform: time
+      at: "15:32:00"
+```
+
+{% enddetails %}
+
+More information can be found in the disabled [Triggers], [Conditions],
+and [Actions] documentation.
+
+[Actions]: /docs/scripts/#disabling-an-action
+[Conditions]: /docs/scripts/conditions#disabling-a-condition
+[Triggers]: /docs/automation/trigger/#disabling-a-trigger
+
+### Continue on error
+
+An automation runs a sequence of actions. One of the questions we
+often see/read/get is: "If one of the actions fails, why does the whole
+automation stop?"
+
+Good question! To answer this, we have added: Continue on error.
+
+It allows specific steps in an automation or script sequence to fail
+without interrupting the rest of the sequence.
+
+This advanced feature is currently only available for automations and scripts
+written in YAML. The following example shows an automation action that will
+always run the second action, even if the first action fails with an error:
+
+```yaml
+action:
   - alias: "If this one fails..."
     continue_on_error: true
     service: notify.super_unreliable_service_provider
@@ -289,9 +367,7 @@ sequence:
       message: "I'm fine..."
 ```
 
-This is an advanced feature, currently only availble for automations in YAML.
+[More information can be found in the scripts documentation](/docs/scripts/#continuing-on-error).
-
-[More information can be found in the scripts documentation](/docs/scripts/#continuing-on-error)
 
 ### Stopping a script or automation
 
@@ -304,24 +380,32 @@ run when you are home and run it at full when you are away.
 
 This feature is available both via the UI and YAML.
 
-<img class="no-shadow" src='https://user-images.githubusercontent.com/195327/163601771-1e8a1e6e-c4e3-4b18-a388-fc17b946dea8.png' alt='Screenshot showing the new stop action'>
+<img class="no-shadow" src='/images/blog/2022-05/stop-action.png' alt='Screenshot showing the new stop action'>
 
-Additionally, the stop-action can be set as an "error" which gives
+{% details "Stop example in YAML" %}
-you a way to stop an automation or script and mark it as an error (for
+
-example, if you detected something unexpected).
+When writing YAML automations or scripts, this is how the Stop action looks:
+
+```yaml
+action:
+  - stop: "Stop right here!"
+    # Optionally mark it as an unexpected error
+    error: true
+```
+
+{% enddetails %}
 
 [More information can be found in the scripts documentation](/docs/scripts/#stopping-a-script-sequence)
 
 ### Parallelizing actions
 
-This release introduces a highly advanced feature, that provides a way to
+This release introduces a highly advanced feature that provides a way to
-parallelize actions (or groups of actions).
+parallelize actions.
 
-By default, all sequences of actions in Home Assistant run sequentially.
+By default, all actions in Home Assistant run sequentially. This means the
-This means the next action is started after the current action has been
+next action is only started after the current action has been completed.
-completed.
 
-This is not always needed, for example, if the sequence of actions
+Running in serial is not always needed, for example, if the sequence of actions
 doesn’t rely on each other and order doesn’t matter. For those cases, the
 parallel action can be used to run the actions in the sequence in parallel,
 meaning all the actions are started simultaneously.
@@ -342,123 +426,68 @@ automation:
               message: "These messages are sent at the same time!"
 ```
 
-As said, this is quite an powerful and advanced feature, and it comes with
+This feature is partly available via the UI; however, as said: This is quite
-caveats. Be sure to check out the [script documentation on parallizing actions](/docs/scripts/#parallelizing-actions)
+a powerful and advanced feature, and it comes with caveats. Be sure to check
-before you decide on using it.
+out the [script documentation on parallelizing actions](/docs/scripts/#parallelizing-actions)
+before deciding to use it.
 
-### And there is even more!
+### Using a single state trigger for multiple entities
 
-These items still need to be processed for the release notes, or might just
+If you write automations in YAML, you are probably already aware of the
-be summed up.
+ability to trigger on multiple entities in a single trigger; it has been
+around for quite some time.
 
-- **Allow any entity to match state condition** ([@frenck] - [#69763])
+And now also available in the UI. A small addition that might help you cut
+down the length of your UI-managed automations.
 
-  If any of the entities matches a certain condition, instead of all of them:
+<img class="no-shadow" src='/images/blog/2022-05/trigger-multiple-entities.png' alt='Screenshot showing multiple entites in a single trigger from the UI.'>
 
-  ```yaml
+### Trigger on not matching to/from states
-  condition:
-  condition: state
-  entity_id:
-    - binary_sensor.motion_sensor_left
-    - binary_sensor.motion_sensor_right
-  match: any
-  state: "on"
-  ```
 
-  YAML only capability.
+This is an YAML only feature we have added to the state triggers: Triggering
+on not matching to/from states. Yes, you read that correctly. When it **not**
+matches it triggers.
 
-  [More information can be found on the state condition documentation](/docs/scripts/conditions#state-condition)
+Instead of `from`, you can now use `not_from` and instead of `to`, you can now
+use `not_to`. This example trigger will only from if the state was previously
+not "unavailable" or "unknown":
 
-- **Trigger on not matching to/from states** ([@frenck] - [#69760])
+```yaml
+trigger:
+  - platform: state
+    entity_id: light.living_room
+    not_from:
+      - "unavailable"
+      - "unknown"
+    to: "on"
+```
 
-  Adds support for `not_from` and `not_to` in the state trigger:
+[More information can be found on the state condition documentation](/docs/scripts/conditions#state-condition).
 
-  ```yaml
+### Shorthand notation for logical conditions
-  automation:
-  trigger:
-    - platform: state
-      entity_id: light.living_room
-      not_from:
-        - "unavailable"
-        - "unknown"
-      to: "on"
-  ```
 
-  ```yaml
+A neat little YAML feature [@thomasloven] added can make your YAML-based
-  automation:
+automations and scripts looks significantly cleaner.
-  trigger:
-    - alias: "Trigger on any alarm state, except when it is disarmed"
-      platform: state
-      entity_id: alarm_control_panel.home
-      not_to: "disarmed"
-  ```
 
-  YAML only capability.
+Logical conditions (also known as `and`, `or`, `not`) now have a shorthand
+notation. Some example pseudo code to show them all:
 
-  [More information can be found on the state condition documentation](/docs/scripts/conditions#state-condition)
+```yaml
-
+or:
-- **Allow disabling specific triggers/actions/conditions** ([@frenck] - [#70082])
+  - <condition>
-
+  - and:
-  Adds support to disable/enable any trigger, action or condition; without
-  removing it from the automation or script.
-
-  ```yaml
-  # Example automation with a disabled trigger
-  automation:
-    trigger:
-      # This trigger will not trigger, as it is disabled.
-      # This automation does not run when the sun is set.
-      - enabled: false
-        platform: sun
-        event: sunset
-
-      # This trigger will fire, as it is not disabled.
-      - platform: time
-        at: "15:32:00"
-  ```
-
-  Currently only supported by YAML, but supposed to be a UI driven feature
-  (as well, in YAML you can just comment out). UI feature hasn't landed yet.
-
-  - Triggers: <https://rc.home-assistant.io/docs/automation/trigger/#disabling-a-trigger>
-  - Conditions: <https://rc.home-assistant.io/docs/scripts/conditions#disabling-a-condition>
-  - Actions: <https://rc.home-assistant.io/docs/scripts/#disabling-an-action>
-
-- **Add shorthand notation for logical conditions** ([@thomasloven] - [#70120])
-
-  This add a shorter/cleaner syntax for logical conditions (`and`, `or`, `not`)
-
-  ```yaml
-  or:
     - <condition>
-    - and:
+    - <condition>
-      - <condition>
+  - not:
-      - <condition>
+    - <condition>
-    - not:
+```
-      - <condition>
-  ```
 
-  A full example
+In the above `<condition>`, of course, needs to be replaced with an actual
+condition, but the short new syntax of `or`, `and`, and `not` clearly visible.
 
-  ```yaml
+[More information can be found on the condition documentation](/docs/scripts/conditions#logical-conditions).
-  automation test:
+
-    - trigger:
+[@thomasloven]: https://github.com/thomasloven
-      - platform: state
-        entity_id: light.bed_light
-        to: "on"
-      condition:
-        - or:
-          - condition: state
-            entity_id: light.ceiling_lights
-            state: "on"
-          - condition: state
-            entity_id: light.kitchen_lights
-            state: "on"
-      action:
-        - service: light.turn_off
-          target:
-            entity_id: light.bed_light
-  ```
 
 ## Gauge card segment colors