Skip to content

Yaml rules and rule templates documentation #2737

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
florian-h05 merged 6 commits into from
Jul 5, 2026
+1,106 −7
Merged

Yaml rules and rule templates documentation #2737

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
037c5e7
Add rules and rule templates to the YAML overview page
Jun 28, 2026
6d32dc4
Extend concepts documentation with standard triggers, conditions and …
Jul 1, 2026
0326d4f
Create YAML rules documentation
Jun 28, 2026
4b39d35
Create YAML rule templates documentation
Jul 2, 2026
2c39731
Address review feedback
Jul 4, 2026
96fa3da
Address review comments
Jul 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion .vuepress/docs-sidebar.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,14 @@ module.exports = [
'concepts/discovery',
'concepts/audio',
'concepts/units-of-measurement',
'concepts/rules',
{ title: 'Rules',
path: '/docs/concepts/rules',
children: [
['concepts/standard-triggers', 'Standard Triggers'],
['concepts/standard-conditions', 'Standard Conditions'],
['concepts/standard-actions', 'Standard Actions']
]
}
]
},
{
Expand Down Expand Up @@ -116,6 +123,8 @@ module.exports = [
['configuration/yaml/things', 'Things'],
['configuration/yaml/items', 'Items'],
['configuration/yaml/tags', 'Tags'],
['configuration/yaml/rules', 'Rules'],
['configuration/yaml/ruletemplates', 'Rule Templates'],
['configuration/yaml/pages', 'Pages'],
['configuration/yaml/widgets', 'Widgets'],
]
Expand Down
17 changes: 11 additions & 6 deletions concepts/rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,8 @@ In both cases, the rule has no triggers and no conditions.
## Triggers

Now that we know the concept of rule triggers, let's look at them in more depth.
Triggers define those events that, when they occur, causes the rule to run.
Triggers define those events that, when they occur, cause the rule to run.
OpenHAB has a set of [standard triggers with specific definitions](./standard-triggers.md).
Comment thread
Nadahar marked this conversation as resolved.
Outdated

These are the categories of rules that can be used to trigger a rule:

Expand Down Expand Up @@ -195,9 +196,7 @@ Please keep in mind that rule engines provided by separately installed automatio

With triggers, we have the _When \_\_t\_\_ happens* part completed, so next up is the *if \_\_c\_\__ part.
This part can limit when a rule can run by adding one or more condition(s).

Conditions as a separately definable part of a rule are supported by some rule engines.
In situations where the rule engine does not support conditions, you can implement your conditions using an `if`-statement in the rule action.
OpenHAB has a set of [standard conditions with specific definitions](./standard-conditions.md).
Comment thread
Nadahar marked this conversation as resolved.
Outdated

Available types of conditions include:

Expand All @@ -210,7 +209,13 @@ Available types of conditions include:
The script condition is the most universal one, as you can choose one of the many available script/rule languages to build any condition you can think of.
The only restriction is a script condition's last executed line of code must result in a boolean (i.e. `true` or `false`).

## Scripts
## Actions

Once a rule has triggered, and all conditions have been met, the rule will execute one or more actions.
These are what makes the rule actually _do something_.
OpenHAB has a set of [standard actions with specific definitions](./standard-actions.md).
Comment thread
Nadahar marked this conversation as resolved.
Outdated

### Scripts

Unfortunately the term "Script" is overloaded in openHAB, and has multiple meanings based on the context:

Expand All @@ -226,7 +231,7 @@ Unfortunately the term "Script" is overloaded in openHAB, and has multiple meani

These rule docs mainly refer to the first two meanings when talking about scripts.

## Script Actions
### Script Actions

Script Actions are an action that allow you to run logic written in one of the available automation/rule languages, e.g. JavaScript, Rules DSL, Blockly.

Expand Down
84 changes: 84 additions & 0 deletions concepts/standard-actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
---
layout: documentation
title: Standard Actions
---

# Standard Actions

This page describes the standard actions for [rules](./rules.md).

OpenHAB comes with a set of standard actions.
Comment thread
Nadahar marked this conversation as resolved.
Outdated
These are built-in mechanisms that perform actions on behalf of rules.

## Actions Structure

The standard actions are fundamentally Java classes that implement the required logic.
We identify these actions using a code called the action type.
These codes are used as titles for the sections below.
To tell the action implementation what to do, actions can have configuration parameters with predefined names.
These configuration parameters and a brief description of what values they expect are listed in the following sections.

### `core.RuleEnablementAction`

This action enables or disables one or more specified `Rule`s.

| Parameter | Description |
|------------|-----------------------------------------------------------------------------------------|
| `ruleUIDs` | The `List` of rule UIDs of the `Rule`s to enable or disable. |
| `enable` | The boolean value that decides if the rule(s) should be enabled or disabled. |

### `core.RunRuleAction`

This action runs one or more specified `Rule`s.

| Parameter | Description |
|------------------------|--------------------------------------------------------------------------------------------|
| `ruleUIDs` | The `List` of rule UIDs of the `Rule`s to run. |
| `[considerConditions]` | A boolean value that determines if `Condition`s should be considered. Defaults to `false`. |

### `core.ItemCommandAction`

This action sends a `Command` to an `Item`.

| Parameter | Description |
|------------|-----------------------------------------------------------------------------------------|
| `itemName` | The name of the `Item`. |
| `command` | The `Command` to send. |

### `core.ItemStateUpdateAction`

This action updates the `State` of an `Item`.

| Parameter | Description |
|------------|-----------------------------------------------------------------------------------------|
| `itemName` | The name of the `Item`. |
| `state` | The `State` to set. |

### `media.PlayAction`

This action plays an audio file.

| Parameter | Description |
|-------------|-----------------------------------------------------------------------------------------|
| `sound` | The filename of the file from the `sounds` folder. |
| `[sink]` | The ID of the audio sink to use. Leave out to use the default. |
| `[volume]` | The volume to be used. Leave out to use the default. |

### `media.SayAction`

This action uses the voice system to say the specified text.

| Parameter | Description |
|-------------|-----------------------------------------------------------------------------------------|
| `text` | The text to say. |
| `[sink]` | The ID of the voice to use. Leave out to use the default. |
Comment thread
Nadahar marked this conversation as resolved.
Outdated
| `[volume]` | The volume to be used. Leave out to use the default. |

### `script.ScriptAction`

This action executes the provided script.

| Parameter | Description |
|-----------|-------------------------------------------------------------------------|
| `type` | The code/MIME-type for the scripting language. |
| `script` | The script content to execute. |
114 changes: 114 additions & 0 deletions concepts/standard-conditions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
---
layout: documentation
title: Standard Conditions
---

# Standard Conditions

This page describes the standard conditions for [rules](./rules.md).

OpenHAB comes with a set of standard conditions.
Comment thread
Nadahar marked this conversation as resolved.
Outdated
These are built-in mechanisms that decide if a rule should be executed when triggered.

## Conditions Structure

The standard conditions are fundamentally Java classes that implement the required logic.
We identify these conditions using a code called the condition type.
These codes are used as titles for the sections below.
To tell the condition implementation what to evaluate, conditions can have configuration parameters with predefined names.
These configuration parameters and a brief description of what values they expect are listed in the following sections.

### `ephemeris.DaysetCondition`

This condition checks if the current day is in the configured `dayset`.

| Parameter | Description |
|------------|-----------------------------------------------------------------------------------------|
| `dayset` | The name of a `dayset` from the ephemeris settings. |
| `[offset]` | The number of days to add to or subtract from the current day (values can be negative). |

### `ephemeris.WeekdayCondition`

This condition verifies that the current day is a weekday.

| Parameter | Description |
|------------|-----------------------------------------------------------------------------------------|
| `[offset]` | The number of days to add to or subtract from the current day (values can be negative). |

### `ephemeris.WeekendCondition`

This condition verifies that the current day is in a weekend.

| Parameter | Description |
|------------|-----------------------------------------------------------------------------------------|
| `[offset]` | The number of days to add to or subtract from the current day (values can be negative). |

### `ephemeris.HolidayCondition`

This condition verifies that the current day is a holiday.

| Parameter | Description |
|------------|-----------------------------------------------------------------------------------------|
| `[offset]` | The number of days to add to or subtract from the current day (values can be negative). |

### `ephemeris.NotHolidayCondition`

This condition verifies that the current day isn't a holiday.

| Parameter | Description |
|------------|-----------------------------------------------------------------------------------------|
| `[offset]` | The number of days to add to or subtract from the current day (values can be negative). |

### `timer.DayOfWeekCondition`

This condition checks the current day of the week against a specified list of days.

| Parameter | Description |
|-----------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `days` | A set of days to check against. The days are specified with the following strings: `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, and `SUN`. |

### `timer.IntervalCondition`

This condition verifies that a minimum interval has elapsed since the last time the condition was met.

| Parameter | Description |
|---------------|-------------------------------------------------------------------------|
| `minInterval` | The minimum number of milliseconds since the last satisfied evaluation. |

### `core.ItemStateCondition`

This condition verifies that the `State` of the specified `Item` fulfills the requirements.

| Parameter | Description |
|---------------|-------------------------------------------------------------------------|
| `itemName` | The name of the `Item`. |
| `operator` | The evaluation operator, one of `=`, `!=`, `<`, `<=`, `>`, and `>=`. |
| `state` | The `State` to compare with. |

### `script.ScriptCondition`

This condition verifies that the provided script returns `true`.

| Parameter | Description |
|-----------|-------------------------------------------------------------------------|
| `type` | The code/MIME-type for the scripting language. |
| `script` | The script content in the specified scripting language. |

### `core.ThingStatusCondition`

This condition verifies that the status of the specified `Thing` fulfills the requirements.

| Parameter | Description |
|------------|-------------------------------------------------------------------------|
| `thingUID` | The UID of the `Thing`. |
| `operator` | The evaluation operator, either `=` or `!=`. |
| `status` | The status to compare with. |
Comment thread
Nadahar marked this conversation as resolved.
Outdated

### `core.TimeOfDayCondition`

This condition verifies that the clock is within the specified time window.

| Parameter | Description |
|-------------|--------------------------------------------------------------------------|
| `startTime` | The start of the time window. |
| `endTime` | The end of the time window. |
Loading