# YAML Rule Templates

This page describes the ruleTemplates element for YAML Configuration.

# Rule Templates

The ruleTemplates top-level key contains a map of rule templates, defined by their template UIDs. The main building blocks of rules are triggers, conditions and actions, collectively called modules. Rule templates let you reuse the same definition in multiple rules, reducing duplication and improving maintainability, by using placeholders in the module configurations. When instantiating/generating a rule from a rule template, you define the values of the placeholders, which will then be substituted before the rule template becomes a rule. That way you can apply the same logic to several situations.

The rule template syntax is therefore almost identical to that of rules. The differences are:

Rule templates, unlike rules, can't link to a template.
Rule templates have no config section, as they don't have any configuration themselves.
Rule templates can contain placeholders ({{placeholder_name}}) in their module definitions.
Rule templates have an additional section, configDescriptions, which defines one parameter definition per placeholder. It defines the name, label, description, type and optionally restrictions and a default value of each placeholder.

The template UID, label and configuration description parameters are a part of the rule template only, all other fields are inherited by the resulting rules.

# YAML Definition Syntax

ruleTemplates:
  <template_uid>:
    label: <template_label> # Becomes the "name" of the rule template
    description: <template_description> # Optional
    tags: # Optional
      - <tag_name>
    visibility: <VISIBLE|HIDDEN|EXPERT> # Optional - defaults to VISIBLE
    configDescriptions: # One parameter must exist per placeholder
      <parameter_name>:
        label: <parameter_label> # Optional
        description: <parameter_description> # Optional
        context: <context_name> # Optional
        default: <default_value> # Optional
        required: <true|false> # Optional - defaults to false
        type: <type_id> # One of TEXT, INTEGER, DECIMAL and BOOLEAN
        min: <minimum_value> # Optional - INTEGER only
        max: <maximum_value> # Optional - INTEGER only
        step: <step_size> # Optional - INTEGER only
        pattern: <regular_expression> # Optional - validation for TEXT only
        readOnly: <true|false> # Optional - defaults to false
        advanced: <true|false> # Optional - defaults to false
        unit: <unit> # Optional - parameter value unit
        unitLabel: <unit_label> # Optional
        options: # Optional - defines a predefined set of values to choose from
          - label: <option_label> # Optional
            value: <option_value>
        multiple: <true|false> # Optional - defaults to false, applicable if there are options only
        multipleLimit: <maximum_number_of_selections> # Optional - applicable if there are options only
        limitToOptions: <true|false> # Optional - defaults to true, applicable if there are options only
        filterCriteria: # Optional - can be used with select contexts to filter e.g. which Items to select from
          - name: <filter_name>
            value: <filter_expression>
    triggers:
      - id: <trigger_id> # Optional - module IDs are autogenerated if not specified
        label: <trigger_label> # Optional 
        description: <trigger_description> # Optional
        type: <trigger_type> # Must be a valid trigger type
        config:
          <configuration_property>: <configured_value> # 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: <condition_type> # Must be a valid condition type
        config:
          <configuration_property>: <configured_value> # Required properties depend on the condition type
    actions:
      - id: <action_id> # Optional - module IDs are autogenerated if not specified
        label: <action_label> # Optional
        description: <action_description> # Optional
        type: <action_type> # Must be a valid action type
        config:
          <configuration_property>: <configured_value> # Required properties depend on the action type

Key	Required	Description
`<template_uid>`	☑	The UID of the rule template being defined.
`label`	☑	The rule template name/label.
`description`	☐	The description of the resulting rules.
`tags`	☐	A list of tags to associate with the resulting rules.
`visibility`	☐	Determines if the resulting rules will be visible in the UI. Rarely used, defaults to `VISIBLE`.
`configDescriptions`	☑	Specify configuration description parameters, one for each placeholder used in the template.
`triggers`	☐	Specify triggers for the resulting rules. Triggers define when a rule should be executed.
`conditions`	☐	Specify conditions for the resulting rules. Conditions control whether a rule should execute based on specific criteria.
`actions`	☐	Specify actions for the resulting rules. Actions define what happens when a rule is triggered and its conditions are met.

# ConfigDescriptions Section

A rule template uses placeholders in the module configurations. These placeholders must be substituted with actual values before a rule can be instantiated from a rule template. The configDescriptions section defines these placeholders as configuration description parameters. There must be one configuration description parameter per placeholder, and their names must match. Otherwise, generating rules from the rule template will fail.

Key	Required	Description
`label`	☐	The parameter label.
`description`	☐	The parameter description.
`type`	☑	The parameter type, one of `TEXT`, `INTEGER`, `DECIMAL` and `BOOLEAN`.
`context`	☐	The parameter context, triggers special behavior in the UI like a lookup or syntax validation. See Supported Contexts for details.
`filterCriteria`	☐	Can be used in combination with certain `context`s to filter e.g. `Item`s that are shown in the lookup. See Supported Contexts for details.
`default`	☐	The default parameter value.
`required`	☑	Whether the parameter is required. Defaults to `false`, but should be `true` for rule template parameters.
`min`	☐	The minimum parameter value, applies to `INTEGER` parameters only.
`max`	☐	The maximum parameter value, applies to `INTEGER` parameters only.
`step`	☐	The parameter value step size, applies to `INTEGER` parameters only.
`pattern`	☐	A regular expression used for validation, applies to `TEXT` parameters only.
`readOnly`	☐	Makes the parameter read-only. Defaults to `false`.
`advanced`	☐	Makes the parameter hidden unless advanced parameters are shown. Defaults to `false`.
`unit`	☐	The parameter value unit.
`unitLabel`	☐	The parameter value unit label.
`options`	☐	A list of predefined parameter values. Each option have a `value` and an optional `label`.
`multiple`	☐	Allows selecting more than one option if `options` are defined. Defaults to `false`.
`multipleLimit`	☐	Defines the maximum number of selectable options, if `options` are defined and `multiple` is `true`.
`limitToOptions`	☐	Allows custom values in addition to the predefined `options` if `false`. Defaults to `true`.

# Modules Sections

The modules sections are identical to those for rules, see the documentation for triggers, conditions and actions. The only difference is that the config sections can contain placeholders of the form {{placeholder_name}}.

# Example

version: 1

ruleTemplates:
  light-on:
    label: "Turn on light at sunset"
    description: "This rule turns on the selected light when the sun sets."
    configDescriptions:
      lightItem:
        context: item
        description: The Item that controls the light
        label: Light Item
        required: true
        type: TEXT
    triggers:
      - type: ChannelEvent
        label: Sunset
        config:
          event: START
          channelUID: astro:sun:local:set#event
    actions:
      - type: SendCommand
        config:
          item: "{{lightItem}}"
          command: ON
  welcome:
    label: Welcome
    description: Welcomes daytime visitors if the house is heated. 
    tags:
      - Welcome
      - Daytime
    configDescriptions:
      startTime:
        label: Start Time
        description: The time the welcomes start
        required: true
        type: TEXT
        pattern: "[0-2]?\\d:[0-5]\\d"
      endTime:
        label: End Time
        description: The time the welcomes end
        required: true
        type: TEXT
        pattern: "[0-2]?\\d:[0-5]\\d"
      heatingItem:
        context: item
        description: The Item that shows the amount of heating
        label: Heating Item
        required: true
        type: TEXT
      heatingThreshold:
        label: Heating Threshold
        description: Decides when there's sufficient heating for a welcome
        required: true
        type: INTEGER
        default: 50
      printText:
        label: Print Text
        description: What to display to visitors to welcome them
        required: true
        type: TEXT
        default: Welcome
      sayText:
        label: Say Text
        description: What to say to visitors to welcome them
        required: true
        type: TEXT
        default: Welcome visitor
    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.
        type: Cron
        config:
          cronExpression: 0 15/30 * * * ? *
    conditions:
      - id: weekday
        type: Weekday
      - type: TimeOfDay
        label: Daytime
        config:
          startTime: "{{startTime}}"
          endTime: "{{endTime}}"
      - type: ItemState
        label: Heating Power Sufficient
        config:
          itemName: "{{heatingItem}}"
          operator: ">="
          state: "{{heatingThreshold}}"
    actions:
      - label: Print
        description: Gives a warm welcome.
        config:
          type: Ruby
          script: |
            puts "{{printText}}"
        type: Script
      - config:
          volume: 80
          sink: enhancedjavasound
          text: "{{sayText}}"
        type: Say
  light-control:
    label: Light Control
    description: Controls lights based on time of day.
    configDescriptions:
      sensor_item:
        type: TEXT
        context: item
        required: true
        label: Sensor Item
        description: The Item that triggers the check
      light_item:
        type: TEXT
        context: item
        required: true
        label: Light Item
        description: The Item that controls the light
      start_time:
        type: TEXT
        required: true
        pattern: "([01]\\d|2[0-3]):?([0-5]\\d)"
        default: "19:00"
        label: Start Time
        description: The time to turn on the light (HH:mm).
      end_time:
        type: TEXT
        required: true
        pattern: "([01]\\d|2[0-3]):?([0-5]\\d)"
        default: "01:00"
        label: End Time
        description: The time to turn off the light (HH:mm).
    triggers:
      - id: item_trigger
        config:
          itemName: "{{sensor_item}}"
        type: ItemChanged
    actions:
      - id: light_action
        type: Script
        config:
          type: JavaScript
          script: |
            if(time.toZDT().isBetweenTimes("{{start_time}}", "{{end_time}}")){
              items["{{light_item}}"].sendCommandIfDifferent("ON");
            } else {
              items["{{light_item}}"].sendCommandIfDifferent("OFF");
            }

# Example Results

Rule templates can be instantiated to rules using rule stubs, Rule objects that only contain the rule UID, template UID, label and placeholders configuration. Here are examples of rule stubs for the example rule templates, and the resulting rules.

# Stub for `light-on`

version: 1
rules:
  light-on-stub:
    template: light-on
    label: Demo Light On At Sunset
    config:
      lightItem: DemoSwitch

# Resulting Rule from `light-on`

version: 1
rules:
  light-on-stub:
    template: light-on
    label: Demo Light On At Sunset
    description: This rule turns on the selected light when the sun sets.
    triggers:
      - label: Sunset
        config:
          event: START
          channelUID: astro:sun:local:set#event
        type: ChannelEvent
    actions:
      - config:
          item: DemoSwitch
          command: ON
        type: SendCommand

# Stub for `welcome`

version: 1
rules:
  welcome-stub:
    template: welcome
    label: Welcome Generated Rule
    config:
      startTime: 09:00
      endTime: 17:30
      sayText: "Welcome visitor, please feel the heat"
      heatingThreshold: 60
      printText: A warm welcome to you
      heatingItem: ControlSignal

# Resulting Rule from `welcome`

version: 1
rules:
  welcome-stub:
    template: welcome
    label: Welcome Generated Rule
    tags:
      - Welcome
      - Daytime
    description: Welcomes daytime visitors if the house is heated.
    triggers:
      - id: startlevel
        label: Start Level Trigger
        description: This trigger triggers at start level 80.
        config:
          startlevel: 80
        type: StartLevel
      - id: "1"
        label: Regular Trigger
        description: "Triggers at every 30 minutes starting at minute :15, every hour."
        config:
          cronExpression: 0 15/30 * * * ? *
        type: Cron
    conditions:
      - id: weekday
        config:
          offset: 0
        type: Weekday
      - id: "2"
        label: Daytime
        config:
          startTime: 09:00
          endTime: 17:30
        type: TimeOfDay
      - id: "3"
        label: Heating Power Sufficient
        config:
          itemName: ControlSignal
          operator: '>='
          state: "60"
        type: ItemState
    actions:
      - id: "4"
        label: Print
        description: Gives a warm welcome.
        config:
          type: Ruby
          script: |
            puts "A warm welcome to you"
        type: Script
      - id: "5"
        config:
          volume: 80
          sink: enhancedjavasound
          text: "Welcome visitor, please feel the heat"
        type: Say

# Stub for `light-control`

version: 1
rules:
  light-control-stub:
    template: light-control
    label: DemoSwitch On In Evenings
    description: Controls lights based on time of day.
    config:
      light_item: DemoSwitch
      end_time: 23:00
      start_time: 18:00
      sensor_item: DemoSensor

# Resulting Rule from `light-control`

version: 1
rules:
  light-control-stub:
    template: light-control
    label: DemoSwitch On In Evenings
    description: Controls lights based on time of day.
    triggers:
      - id: item_trigger
        config:
          itemName: DemoSensor
        type: ItemChanged
    actions:
      - id: light_action
        config:
          type: JavaScript
          script: |
            if(time.toZDT().isBetweenTimes("18:00", "23:00")){
              items["DemoSwitch"].sendCommandIfDifferent("ON");
            } else {
              items["DemoSwitch"].sendCommandIfDifferent("OFF");
            }
        type: Script

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

← Rules Pages →

# YAML Rule Templates

# Rule Templates

# YAML Definition Syntax

# ConfigDescriptions Section

# Modules Sections

# Example

# Example Results

# Stub for light-on

# Resulting Rule from light-on

# Stub for welcome

# Resulting Rule from welcome