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
EDIT: This is getting too long for one posting. I’ve split it up (thanks @ysc’s write-up for HABot for giving me the idea).
This is a series of postings to start writing and gathering what we know works and what doesn’t yet work in the Rules that can be created through PaperUI. In particular I’m interesting in what we have access to and not in self written scripts.
I’m making all of these a wiki so please add your contributions to the OP instead of in comments if you have something that works or spot something wrong or that has changed. For now it is kind of stream of consciousness and not organized.
I’m currently testing with OH 2.4 SNAPSHOT Build #1405
Background
The Experimental Next-Gen Rules Engine (NGRE) is a brand new automation engine available as a separate install on OH 2.3. Note the “Experimental” in the name. While NGRE has matured significantly in recent months, it is still a work in progress. Use at your own risk. The document below makes up the bulk of the available documentation.
This document will primarily focus on creating and managing NGRE Rules through the Rules tab in PaperUI. This is not currently the only way and expect new NGRE editors in the future.
What’s New
There are some significant differences between the Rules DSL and the NGRE. For one the NGRE supports new concepts and capabilities including:
-
supports the creation and management of Rules through the REST API meaning we can have UI based Rule Builders (currently only PaperUI exists but there was a Node Red/Yahoo Pipes like UI started)
-
Rules can be enabled or disabled, and they can be enabled and disabled through other Rules // TODO how?
-
Rules can be created that all use the same script as the action
-
a Rule can be manually run from PaperUI (don’t do this right now, there is a bug that will kill your Rule)
-
Rules are written in main stream programming languages (JavaScript supported now, others to follow)
-
if you are using JSR223 then you are already using the NGRE (more on the implications of this below)
-
support for Rule Templates // TODO How do I create a template? How do I use a template?
-
super simple Rules like sending a command, playing a sound, or saying something do not even require manually entering a script
-
there is a new concept called “Conditions” which allows one to define the conditions under which the Rule should trigger; no more need to add if statements at the beginning of your Rule; conditions are fully scriptable allowing for very complex and thorough pre-checking
-
support for libraries, functions, and classes
-
it will run your old .rules files (not yet implemented but promised)
And there are more. But the main takeaway is the NGRE is a wholly new thing with new concepts and capabilities.
Two of the most exciting additions for power users is the support for libraries, functions, and classes as well as the fact that you’ve likely already been using it, perhaps unbeknownst to you.
For new/non-technical users the most exciting part is the built in support for creating Rules in PaperUI, the promise of a Node Red like Rules editor, and the ability to load libraries and have Rules call each other. This last point means no longer will you have to copy and paste and edit code from the forum but will instead be able to download a library and call it with your Items.
There is much to be excited about the NGRE!
What’s Missing or Broken
There are some features that are missing for those used to Rules DSL for PapeRUI created Rules (note, most of these are available in JSR223).
-
Time cron triggers or combination of triggers and conditions to replicate the full cron expression. The “fixed time of day” trigger is a little confusing. The format description says HH:MM but I could only get it to work by also supplying AN/PM. The Day of week condition is currently broken as the dialog doesn’t let us click on the days to select them, or it is not showing that we have selected a day.
-
send command for all the command types. Currently CLOSED/DOWN/OFF/ON/OPEN/UP are the only ones listed in the dropdown. Appears we can type in anything but that is not clear from the way the UI works causing confusion.
-
Syntax checking and highlighting in the JavaScript entry box. There is also a bug in how the script entry box resizes when first creating a Rule; it doesn’t resize when pressing enter on a line with text. Pressing enter on a blank line does resize it so one must add a bunch of blank lines to open the dialog up enough to work.
-
Global variables alternative? The main issue is that many of the use cases of Timers requires retaining a handle on the Timer that can be accessed across multiple Rules or multiple executions of the same Rule. Another use case that can’t be supported easily without global variables are the use of the storeStates and restoreStates. Everything else can be stores in Items.
-
Member of Rule triggers are missing.
-
Group update event triggers are currently broken. The only way to trigger a Rule using a Group is by changed triggers. The combination of these last two means it is impossible to trigger a Rule on an Item’s update or command unless the Item is explicitly listed as a trigger.
-
There is no way to add tags to Rules except by editing the JSONDB files manually.
How NGRE Is Related to JSR223
JSR223 is a way to write OH Rules using one of three more mainstream programming languages: Jython, JavaScript (Nashorn), or Groovy. For experienced programmers, this restores many of the important programming tools that were purposefully removed from the Rules DSL to create a simpler programming environment for non-programmers. The lack of those tools can be frustrating and overly constraining for these users.
With the creation of the NGRE, now JSR223 rules and PaperUI created Rules are run on the same engine. This means that one can run a mix of JSR223 and PaperUI Rules, one can write JSR223 Rules but set up the triggers using PaperUI, once can create a library of classes and functions that are useful for both JSR223 rules and PaperUI created Rules.
In short, the NGRE will give the experts a chance to create complicated and reusable Rules logic and make that available to all users through a simply download instead of a copy/paste/edit from some forum posting.
If you are looking for how to do something and the answer is not in this guide, look at the JSR223 docs and at the JSR223 openHAB libraries. Both will be rich with examples.
This guide will focus on creating Rules in PaperUI. If you need to write complicated Rules that need good syntax highlighting, a fast save/test cycle, or if you are just more comfortable using text based files for your coding I recommend following the instructions for coding with JSR223. You will still be using the NGRE and for super simple stuff you can use PaperUI.
For those who are not coders and are just getting started, using PaperUI may be a more comfortable choice. Realize that there is nothing that can be done in JSR223 rules that cannot be done through the PaperUI interface, but the current script entry interface is very frustrating to use.
But if I use PaperUI, where are my Rules saved? All Rules created in PaperUI get saved to the JSONDB. After you create your first Rule you will find a new automation_rules.json
file in $USERDATA/jsondb. The format of this file is loosely documented here. I can tell you, it’s pretty ugly, you will not want to edit this file by hand.
{
"7a6ebf3b-6f0c-4a82-b582-5e7ded2dae42": {
"class": "org.eclipse.smarthome.automation.dto.RuleDTO",
"value": {
"triggers": [
{
"id": "1",
"label": "an item receives a command",
"description": "This triggers the rule if an item receives a command.",
"configuration": {
"itemName": "Test",
"command": "ON"
},
"type": "core.ItemCommandTrigger"
}
],
"conditions": [],
"actions": [
{
"inputs": {},
"id": "2",
"label": "execute a given script",
"description": "Allows the execution of a user-defined script.",
"configuration": {
"type": "application/javascript",
"script": "\u0027use strict\u0027;\n\nload(\u0027./../conf/automation/jsr223/jslib/JSRule.js\u0027);\n\nlogInfo(\"Using the library!\");\n\n//var myLog \u003d Java.type(\"org.slf4j.LoggerFactory\").getLogger(\"org.eclipse.smarthome.model.script.Rules\");\n//myLog.info(\"createTimer---------------------------\");\n//var ScriptExecution \u003d Java.type(\"org.eclipse.smarthome.model.script.actions.ScriptExecution\");\n//var LocalDateTime \u003d Java.type(\"java.time.LocalDateTime\");\n//var DateTime \u003d Java.type(\"org.joda.time.DateTime\");\n//var fnc \u003d function(){\n// myLog.info(\"Timer completed\");\n//}\n//myLog.info(\"Creating timer...\");\n//ScriptExecution.createTimer(LocalDateTime.now().plusSeconds(5), fnc);"
},
"type": "script.ScriptAction"
}
],
"configuration": {},
"configDescriptions": [],
"uid": "7a6ebf3b-6f0c-4a82-b582-5e7ded2dae42",
"name": "Test4",
"tags": [],
"visibility": "VISIBLE"
}
}
}
Next step: Experimental Next-Gen Rules Engine Documentation 2 of : Installation.