# YAML Rules

This page describes the rules element for YAML Configuration.

# Rules

The rules top-level key contains a map of rules, defined by their rule UIDs. The main building blocks of rules are triggers, conditions and actions, collectively called modules.

# YAML Definition Syntax

rules:
  <rule_uid>:
    template: <rule_template_uid> # Optional - only used when the rule is based on a rule template
    label: <rule_label> # Required
    description: <rule_description> # Optional
    tags: # Optional
      - <tag_name>
    visibility: <VISIBLE|HIDDEN|EXPERT> # Optional - defaults to VISIBLE
    config: # Optional - used when the rule is based on a rule template
      <config_key>: <config_value>
    triggers:
      - id: <trigger_id> # Optional - module IDs are autogenerated if not specified
        label: <trigger_label> # Optional 
        description: <trigger_description> # Optional
        type: StartLevel # Must be a valid trigger type
        config:
          startlevel: 80 # Required properties depend on the trigger type
    conditions:
      - id: <condition_id> # Optional - module IDs are autogenerated if not specified
        label: <condition_label> # Optional
        description: <condition_description> # Optional
        type: TimeOfDay # Must be a valid condition type
        config:
          startTime: 08:00 # Required properties depend on the condition type
          endTime: 16:00
    actions:
      - id: <action_id> # Optional - module IDs are autogenerated if not specified
        label: <action_label> # Optional
        description: <action_description> # Optional
        type: Script # Must be a valid action type
        config:
          type: Ruby # Required properties depend on the action type
          script: |
            puts "Hello world"

Key	Required	Description
`<rule_uid>`	☑	The UID of the rule being defined. The UID can be anything as long as it doesn't start or end with whitespace, and doesn't contain `/` or `\`.
`template`	☐	Contains the UID of the rule template if the rule is linked to one. This field is only relevant for template-based rules.
`label`	☑	The rule name/label.
`description`	☐	The rule description.
`tags`	☐	A list of tags to associate with the rule.
`visibility`	☐	Determines if the rule will be displayed in the UI. Rarely used, defaults to `VISIBLE`.
`config`	☐	A key-value map of the rule's configuration. Used with rule templates to specify the values of placeholders.
`triggers`	☐	Specify rule triggers. Triggers define when the rule should be executed.
`conditions`	☐	Specify rule conditions. Conditions control whether a rule should execute based on specific criteria.
`actions`	☐	Specify rule actions. Actions define what happens when a rule is triggered and its conditions are met.

# Triggers Section

Key	Required	Description
`id`	☐	The trigger ID. It must be unique within the rule, across triggers, conditions and actions (modules). Will be generated if not specified.
`label`	☐	The trigger label.
`description`	☐	The trigger description.
`type`	☑	The trigger type, which must be a valid/existing trigger type. This is what decides how the trigger works, what mechanism is in use, and which configuration properties must be present.
`config`	▧	A key-value map of the trigger's configuration. See the trigger type documentation for which keys exist, are mandatory, and what their values should be.

# Trigger Types

openHAB can be extended in various ways, so other trigger types than those listed here can be valid in a particular installation. Here is a list of standard trigger types that exist in any installation. The standard trigger types have been given simplified aliases for convenience, but can also be used with their "full ID".

Alias	ID	Description
`ChannelEvent`	`core.ChannelEventTrigger`	A channel event trigger, which triggers on specific events from trigger channels.
`Cron`	`timer.GenericCronTrigger`	A time trigger, which triggers at specific times, defined by a Cron expression (opens new window).
`DateTime`	`timer.DateTimeTrigger`	A time trigger, which triggers on a `DateTimeType` state of an Item.
`GenericEvent`	`core.GenericEventTrigger`	An "advanced" trigger, which triggers on events on the event bus, using various filters to filter out events of interest.
`MemberReceivedCommand`	`core.GroupCommandTrigger`	A group trigger, which triggers on received commands among group members.
`MemberChanged`	`core.GroupStateChangeTrigger`	A group trigger, which triggers on state changes among group members.
`MemberUpdated`	`core.GroupStateUpdateTrigger`	A group trigger, which triggers on state updates among group members.
`ItemReceivedCommand`	`core.ItemCommandTrigger`	An item trigger, which triggers on received commands for an item.
`ItemChanged`	`core.ItemStateChangeTrigger`	An item trigger, which triggers on state changes for an item.
`ItemUpdated`	`core.ItemStateUpdateTrigger`	An item trigger, which triggers on state updates for an item.
`StartLevel`	`core.SystemStartlevelTrigger`	A system trigger, which triggers at specific start levels during openHAB startup.
`ThingChanged`	`core.ThingStatusChangeTrigger`	A thing trigger, which triggers on status changes for a thing.
`ThingUpdated`	`core.ThingStatusUpdateTrigger`	A thing trigger, which triggers on status updates for a thing.
`TimeOfDay`	`timer.TimeOfDayTrigger`	A time trigger, which triggers based on time of day.

# Conditions Section

Key	Required	Description
`id`	☐	The condition ID. It must be unique within the rule, across triggers, conditions and actions (modules). Will be generated if not specified.
`label`	☐	The condition label.
`description`	☐	The condition description.
`type`	☑	The condition type, which must be a valid/existing condition type. This is what decides how the condition works, what mechanism is in use, and which configuration properties must be present.
`config`	▧	A key-value map of the condition's configuration. See the condition type documentation for which keys exist, are mandatory, and what their values should be.
`inputs`	☐	Advanced: A key-value map for controlling mapping of inputs from other modules. Inputs are automatically mapped if not mapped explicitly.

# Condition Types

openHAB can be extended in various ways, so other condition types than those listed here can be valid in a particular installation. Here is a list of standard condition types that exist in any installation. The standard condition types have been given simplified aliases for convenience, but can also be used with their "full ID".

Alias	ID	Description
`DayOfWeek`	`timer.DayOfWeekCondition`	A condition that will only allow the rule to run on specific days of the week.
`Dayset`	`ephemeris.DaysetCondition`	A condition that will only allow the rule to run on days in a specified set.
`Holiday`	`ephemeris.HolidayCondition`	A condition that will only allow the rule to run on holidays.
`Interval`	`timer.IntervalCondition`	A condition that will only allow the rule to run inside a specified time interval.
`ItemState`	`core.ItemStateCondition`	A condition that will only allow the rule to run if a specific Item has a specific state.
`NotHoliday`	`ephemeris.NotHolidayCondition`	A condition that will only allow the rule to run on non-holidays.
`Script`	`script.ScriptCondition`	A scripted condition written in any supported scripting language, which can evaluate the condition using custom logic.
`ThingStatus`	`core.ThingStatusCondition`	A condition that will only allow the rule to run if a specific Thing has a specific status.
`TimeOfDay`	`core.TimeOfDayCondition`	A condition that will only allow the rule to run within a specified time window.
`Weekday`	`ephemeris.WeekdayCondition`	A condition that will only allow the rule to run on weekdays.
`Weekend`	`ephemeris.WeekendCondition`	A condition that will only allow the rule to run on weekends.

# Actions Section

Key	Required	Description
`id`	☐	The action ID. It must be unique within the rule, across triggers, conditions and actions (modules). Will be generated if not specified.
`label`	☐	The action label.
`description`	☐	The action description.
`type`	☑	The action type, which must be a valid/existing action type. This is what decides how the action works, what mechanism is in use, and which configuration properties must be present.
`config`	▧	A key-value map of the action's configuration. See the action type documentation for which keys exist, are mandatory, and what their values should be.
`inputs`	☐	Advanced: A key-value map for controlling mapping of inputs from other modules. Inputs are automatically mapped if not mapped explicitly.

# Action Types

openHAB can be extended in various ways, so other action types than those listed here can be valid in a particular installation. Here is a list of standard action types that exist in any installation. The standard action types have been given simplified aliases for convenience, but can also be used with their "full ID".

Alias	ID	Description
`EnableRule`	`core.RuleEnablementAction`	An action that enables or disables rules.
`SendCommand`	`core.ItemCommandAction`	An action that sends a command to an Item.
`PostUpdate`	`core.ItemStateUpdateAction`	An action that updates an Item state.
`Play`	`media.PlayAction`	An action that plays a media file.
`RunRule`	`core.RunRuleAction`	An action that runs another rule and returns the resulting data.
`Say`	`media.SayAction`	An action that uses voice to say something.
`Script`	`script.ScriptAction`	An action written in any supported scripting language and does whatever the script dictates. This is probably the most widely used action type.

# Script Types

For scripted conditions and actions, there's an additional type parameter that must be specified under config, to identify the scripting language to use. The identifiers are based on MIME-types (opens new window), but don't really adhere to any standard. It's up to each scripting add-on to pick a code, and the resulting codes reflect that. To make these easier to use and remember, the type field in a scripting module's config section supports aliases for the most commonly used type. Either the alias or the full type code will work. Other scripting languages can be specified, but the full type code must be used.

Alias	Type Code	Description
`DSL`	`application/vnd.openhab.dsl.rule`	Rules DSL, openHAB's own scripting language.
`Groovy`	`application/x-groovy`	Groovy (opens new window) scripting.
`JavaScript`	`application/javascript`	JavaScript scripting using GraalJS (opens new window).
`Python`	`application/python`	Python 3 scripting using GraalPy (opens new window).
`Jython`	`application/x-python2`	Python 2 scripting using Jython (opens new window).
`Ruby`	`application/x-ruby`	Ruby scripting using JRuby (opens new window).
`NashornJS`	`application/javascript;version=ECMAScript-5.1`	JavaScript scripting using Nashorn (opens new window).

# Example

version: 1

rules:
  lights-on:
    label: "Turn on light at sunset"
    description: "This rule turns on the living room light when the sun sets."
    triggers:
      - type: ChannelEvent
        label: Sunset
        config:
          event: START
          channelUID: astro:sun:local:set#event
    actions:
      - type: SendCommand
        config:
          item: LivingRoomLight
          command: ON
  welcome-rule:
    label: Welcome Rule
    description: Welcomes daytime visitors if the house is heated. 
    tags:
      - Welcome
      - Daytime
    triggers:
      - id: startlevel
        label: Start Level Trigger
        description: This trigger triggers at start level 80.
        type: StartLevel
        config:
          startlevel: 80
      - label: Regular Trigger
        description: Triggers at every 30 minutes starting at minute :15, every hour between 08 and 20, of every day.
        type: Cron
        config:
          cronExpression: 0 15/30 8-20 ? * * *
    conditions:
      - id: weekday
        type: Weekday
      - type: TimeOfDay
        label: Daytime
        config:
          startTime: 08:00
          endTime: 20:00
      - type: ItemState
        label: Heating Power Sufficient
        config:
          itemName: CurrentPower
          operator: ">"
          state: "50"
    actions:
      - label: Print
        description: Gives a warm welcome.
        config:
          type: Ruby
          script: |
            puts "Hello and welcome to a heated house"
        type: Script
      - config:
          volume: 80
          sink: enhancedjavasound
          text: Welcome
        type: Say

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← Tags Rule Templates →