This tutorial post is very out of date and ultimately did not make it into the official docs. Do not use this except for historic purposes. See the Getting Started Tutorial sections on rules for how to get started with rules. Rules - Introduction | openHAB
Your First Rule
Prerequisites
Create a Switch Item named Test. We will use this to trigger our Rule. Give the Item a label because the Items are listed alphabetically by label. If you skip the label, the Item ends up at the bottom of the list.
Create the Rule
In PaperUI, select Rules from the left.
Press the big + to create a new Rule.
You will find several fields to fill out.
| Field | What to fill in |
|---|---|
| Name | Give the Rule a unique and meaningful name. |
| Description | Explain what the Rule does and any other information that is useful to you. |
| When… | Defines the events when the Rule will trigger. This is optional if you are creating a Rule that is to be called from other Rules. You can create more than one trigger. |
| but only if… | Defines the conditions under which the Rule will run when triggered. This is optional and there can be more than one trigger |
| then… | Defines what actions the Rule takes when it runs. This is optional (though the Rule won’t do anything) and there can be more than one Action. |
Fill out the name and description with meaningful information.
When…
When defines the events cause the Rule to trigger when they occur. Zero or more When’s can be defined for a given Rule. There currently exists six types of Rule triggers supported.
| Trigger Type | What it does |
|---|---|
| a trigger channel fires | Triggers a Rule when a Channel trigger fires such as is used in the Dash Button binding or Astro binding for astronomical events. Both the Channel and the event can be defined. |
| an item state changes | Equivalent to the changed trigger in Rules DSL. Triggers the Rule when the selected Item changes state. One can optionally define the previous state and new state similar to Rules DSL “changed from OFF to ON”. |
| an item receives a command | Equivalent to the received command trigger in Rules DSL. Triggers the Rule when the selected Item receives a command. One can optionally define the command received similar to Rules DSL “received command ON”. |
| an item state is updated | Equivalent to the received update trigger in Rules DSL. Triggers the Rule when the selected Item receives an update. One can optionally define the update received similar to Rules DSL “received update ON”. |
| it is a fixed time of day | Sets the Rule to trigger at a specific time of day every day. This is NOT a full Time cron type trigger from Rules DSL. |
| the rule is activated | Triggers when a rule is activated the first time. This causes the Rule to trigger when it is first loaded by OH similar to the Rules DSL. NOTE: This appears to not work with a jsr223.StartupTrigger existing in JSR223 Rules. This needs more exploration. |
Select an item receives a command as the Trigger and select Test from the list. You can jump to the Item’s whose labels start with “T” press the “t” button. Be sure to provide a meaningful name and description for the trigger so you can tell them apart for Rules that have more than one trigger.
but only if…
These define the conditions that must be true for the Rule to execute even if one of the events defined in When occurs. There currently exists three types of conditions supported.
| Condition Type | What it does |
|---|---|
| an item has a given state | Select the Item, comparison operator, and the value to compare against. For example, MyTemperature Item >= (is greater or equal to) 20. |
| a given script evaluates to true | A script to execute whose last line evaluates true or false. If the that line is true, the rule will be allowed to run (assuming all the other defined conditions are also true). Currently only JavaScript is supported. Everything available to the Action Script is available here as well. The Script just needs to return true or false. |
| it is a certain day of the week | Allows one to select the day of the week that it must be for the Rule to run. This combined with “it is a fixed time of day” allows one to write Rules that trigger at a certain time on certain days. |
We will not be creating a condition for this Rule.
then…
These define the actions to take place when the Rule runs. There are six Actions that are currently implemented.
| Action Type | What it does |
|---|---|
| send a command | Allows one to send a command to an Item when the Rule runs. This can be very useful for creating links between proxy Items and device Items. NOTE: if your Item requires an Integer this may not work as it seems to set the value to a floating point value. |
| run rules | Allows the triggering of other Rule(s) to run when this Rule triggers. One can optionally ignore the Conditions defined on those Rules, though that should be rare. JSR223 Rules should appear in the list so one can create the Rules in JSR223 and the triggers in PaperUI. |
| enables or disable rules | TODO: file issue to correct typo. Enable or disable Rule(s). This is useful to create “away mode” type Rule sets as they can be enabled/disabled based on events. |
| execute a given script | Define a script to execute when the Rule runs. Currently only JavaScript is supported. The bulk of the rest of this guide covers this. |
| play a sound | Send a sound to the selected audio sink. TODO: How to add sounds to the list? |
| say something | Send TTS to the selected audio sink. The text is statically defined but you can generate dynamic text in a script. |
Select execute a given script from the list. Fill in something meaningful for the Name and Description. JavaScript is the only option for “the scripting language used”. We will be entering the code itself in the Script section.
Entering the following two lines:
var myLog = Java.type("org.slf4j.LoggerFactory").getLogger("org.eclipse.smarthome.model.script.Rules");
myLog.info("Hello world!")
The first line imports the openHAB logger. The second line is the actual logging statement.
Note that the text field may not resize automatically. I find that adding a bunch of newlines will help expand the text field and make it easier to see what you are typing.
Click OK and then the check mark to save the Rule.
Trigger the Rule
There is a bug when using the play button to manually trigger a Rule after it is first created or after modification. The first trigger after a save MUST be from an event. If it is not, the Rule will throw an error and will not work until it is re-saved and triggered through an event.
Issue an ON command to the Test Item in your preferred way. Options include:
- through the REST API
- put the Item on your sitemap or HABPanel and click the toggle
- through the Karaf console
Watch openhab.log. Once the Rule is triggered you should see “Hello World!”
2018-10-25 12:52:49.566 [INFO ] [eclipse.smarthome.model.script.Rules] - Hello world
Delete or Disable the Rule
Now that we have tested the Rule you can delete the Rule by clicking on the trashcan icon. You can disable the Rule by clicking the clock icon.
Deleting the Rule removes it from the list. If you accidentally delete a Rule you can restore it from the backup JSONDB file in $OH_USERDATA/jsondb/backups.
Note that disabling a Rule will disable it in all the way’s it is called. So if you have another Rule that isn’t disabled that calls the disabled Rule, the disabled Rule will not execute.
Rule Satus
Notice the yellow “IDLE” next to the Rule name. This shows the current state of the Rule. Monitoring this status will show you what Rules are actively running, disabled, initializing, have a problem, etc.
Previous step: Experimental Next-Gen Rules Engine Documentation 2 of : Installation
Next step: Experimental Next-Gen Rules Engine Documentation 4 of : Writing Scripts
