Experimental Next-Gen Rules Engine Documentation 3 of : Your First Rule

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 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.


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


I’d like to share a little something I painfully discovered while testing this while I was experimenting with Flows Builder - a visual designer for the new rules engine

Here the script shouldn’t actually use a return statement - instead, the value of the last statement is the one that counts.

So don’t do:

var result = (condition);
return result;



or even:

var result = (condition);

At least it was the case a year ago!

Excellent info.


It’s really frustrating trying to figure all of this out by experimentation and as I’m sure you can tell, I haven’t spent much time on the triggers just yet.

If there is any other mistakes or advice you can offer I’d be grateful.

I hope the visual designer becomes more than an experiment some day. I said to myself “I’m seeing the future” when I first looked at it. :slight_smile:

1 Like

I was stoked as well and saw the potential with the rules engine, that’s why I gave it a shot and developed the designer, but as I was almost ready to try to move all my rules to it, I faced New rule engine startup - rule initialisation which basically makes it very unreliable - if not unuseable.

I’m just learning now some workarounds have been found so might give it another try…


I have highlighted the part where where first time the rule must be run through an event


Not sure if we still looking here to resolve the issues, but i found that the “but only IF” does not evaluate anything…

Please show what you put in for the “but only if”. It should work but there are some known gotchas.

But it is true, these instructions are largely deprecated and will be rewritten when the replacement for PaperUI is released.