âHas worked on itâ instead of âworkingâ. The documentation has stalled because of limitations in PaperUI and the rapid and huge advancements Scott and company are making to the helper libraries Iâve stopped work on them, for now. I hope to be able to reuse maybe 50% of what is there now when we do pick back up on the docs.
OK, here is a quick tl;dr to explain the moving parts here.
PaperUI is a UI only, like rossko57 says. All that PaperUI does is present graphical elements to the user (forms and buttons) and converts the interactions with those into REST API calls. PaperUI is currently the only graphical way to create NGRE Rules.
The NGRE itself is a Rules Engine that currently supports the running of Rules written in Jython, JavaScript, and Groovy. JSR223 Rules are executed by the NGRE. Rules created by PaperUI are stored as JSON in the JSONDB, but despite this radically different form, these Rules too are executed by the NGRE. To a large extent, the NGRE represents a unification of the Rules Engine. Whether you create your Rules in text files or through whatever replaces PaperUI, it will be executing on the same engine.
So, if you want to start using the NGRE now, you can get started with JSR223 and the Helper Libraries.
The example JSON Yannick posted above is JSON Rules. This is the type of Rule that would be created through a UI/REST API. Instead of being saved to .js files, they get stored as JSON. The biggest difference between JSR223 Rules and JSON Rules is that in JSR223 you have to define your Rules and triggers and such in the code. The Helper Libraries makes this very easy to do, especially with Jython and itâs annotations. In JSON Rules, most of the stuff that defines the Rule is defined in JSON. The âbodyâ of the Rule (in Rules DSL the stuff between the then
and end
goes in the actions.configuration.script
element. In Yannickâs example, its a set of three print statements using JavaScript.
Note that âtypeâ element. You can write your rule using any supported language for JSON Rules, not just JavaScript. Though PaperUI only supports JavaScript at this time. Itâs also important to note that the Action need not be code when using JSON Rules. For example, right now I have the following choices for Actions:
- enables or disable rules: this is going to be super powerful; imagine just disabling your night time Rules when the sun comes up, this works with JSR223 Rules too
- execute a given script: see Yannickâs example, this is the closest to what we are used to doing with Rules
- play a sound
- publish an MQTT message
- run rules
- say something
- send a command
- send a web push notification to HABot
As you can see, individual bindings can add their own Actions to the list.
JSON Rules also have the concept of âbut only ifâŠâ which I donât think has an analog in JSR223 Rules (@5iver, is that true? I couldnât find any similar concept in the Rules section of the Helper Library docs). This lets you establish a set of conditions which must be true for the Rule to trigger. Unlike with Rules DSL where all you have are events that trigger the Rule and then you need to use if statements in the body of the Rule to see if there is anything to do, JSON Rules have a separate section for this. As with Actions, you can write a full script for this or use one of the built in conditions (e.g. âit is a certain day of the weekâ).
Finally, I believe both JSR223 and JSON Rules have the concept of Rule Templates. These are pre-written Rules that you can import into your setup, perform some configurations (e.g. mapping your Item names to the parameters needed by the Rule). This will be huge! No more will we need to copy and paste examples from the forum for users to adopt some code. We can let the experts write the Rules for us and just use them as is.
On the Rules front, the future looks bright indeed.
As for docs, as you can see from the Helper Library docs, the language and ways to interact with openHAB is pretty well documented. There is very little documentation available for JSON Rules. Since JSON rules were never intended to be written by hand, this isnât surprising. But the part that makes them âexperimentalâ is the limitations of the UI part. The Rules themselves are mature and working very well.