Triggers and automations

Triggers and automations

Defining triggers

As an user with administrator privilege you will find Triggers in the Admin menu. This is where you define the triggers which users can use.

Triggers

Initially this will just be an empty space. But once you add triggers, you'll see a list of these here. You can either modify or delete existing triggers.

Add / modify trigger

This section either allows you to create a new trigger, or it will be populated with the data of an existing trigger if you choose to edit a trigger.

Caption

The text of the button the users will see in their trigger list.

Order

A numeric value by which the trigger list will be sorted. The order is ascending.

Trigger data

The payload that will be included when the webhook is called. The format is raw JSON.
Example:

{
"service": "light.turn_on",
"entity_id": "light.kitchen"
}

Whitespace will be stripped out when saving the trigger. So you can use it while constructing the payload, but if you edit it later on it will be gone.
The border of the textarea in which you construct the payload will change to the color red if the content is not valid JSON.

Webhook URI

This is the full URI to which the webhook request will be sent. It will depend on your setup. This section of the Home Assistant documentation covers webhook triggers.

Password

You may want to restrict access to triggers to a subset of the available users. As of today trigger availability is global. As a workaround you can specify a simple password / pin which a user will be prompted for when pushing the trigger button. It's basically another, trigger-specific, authentication layer.
This is just used internally and will not be stored encrypted. Do not use secret passwords that are used elsewhere!

Include user

When this checkbox is checked, the trigger data will be extended with the user information of the user that executed the trigger. This can be used to fine tune the automation by using the username as a condition.

Require Geolocation

A trigger can require the user to provides his location prior to firing the trigger, and will fail if the user rejects to do so. If the user accepts, the payload sent to Home Assistant will include the additional keys latitude, longitude and accuracy. This can be useful the check if the trigger has not been fired from the other side of the globe. If you activate this, a small globe-icon will be displayed next to the caption in the trigger view.

Disable trigger

Use this checkbox to disable a trigger without deleting it. All data will be retained, but the trigger can't be fired and will not be displayed to the users.

Available to users

User can only see triggers that have been assigned to them. On regular computers the used select multiple element might not be easy to use if you don't know this type of element. You have to hold the CTRL key (or CMD on Mac) to add / remove items from your selection.

Automation in Home Assistant

This is a minimal automation in Home Assistant (YAML style) that will write a message to the logs at the warning level. It includes the trigger data, allowing you to observe what data arrives at Home Assistant after executing the trigger.

automation old:
  trigger:
    platform: webhook
    webhook_id: secretwebhookid
  action:
    service: system_log.write
    data_template:
      message: "{{ trigger.json }}"
      level: warning

If you add a trigger with the trigger data {"test": "foo"} and check the Include user checkbox, the output will look something like this:

2020-01-17 22:22:37 WARNING (MainThread) [homeassistant.components.system_log.external] {'test': 'foo', 'user': 'john.doe'}

And here a more complex automation with the user as a condition and multiple actions.

- alias: Unlock the door
  description: Unlocking the door via HASS-WH-Triggers
  trigger:
  - platform: webhook
    webhook_id: secretwebhookid
  condition:
  - condition: template
    value_template: '{{ trigger.json.user in ["bob", "alice"] }}'
  action:
  - service: lock.unlock
    data:
      entity_id: lock.mylock
  - service: switch.turn_on
    data:
      entity_id: switch.myswitch
  - service: system_log.write
    data_template:
      message: "{{ trigger.json.user }} has unlocked the door"
      level: warning

And this is just the action part of an automation (YAML mode in the automation editor) where the location of the user gets sent as a location-message using a Telegram notifier:

data_template:
  data:
    location:
      latitude: '{{trigger.json.latitude}}'
      longitude: '{{trigger.json.longitude}}'
  message: '{{trigger.json.user}}'
service: notify.my_telegram

Have a look at the DISTANCE section of the Home Assistant documentation on how to make use of the location information. This template for example will evaluate to True in case the distance to Home is less than 1 kilometer:
{{ distance(trigger.json.latitude, trigger.json.longitude) < 1 }}.