Your First Rule
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 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
|an item receives a command||Equivalent to the
|an item state is updated||Equivalent to the
|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.|
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.|
|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.
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.|
|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.|
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.
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
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.
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.