Documentation Examples for 'now' are incorrect

The code examples clearly show this usage:


Yet, if you copy/paste that example, you get this error:

Script execution of rule with UID 'da88b1ba77' failed: ReferenceError: "now" is not defined in <eval> at line number 15

It says " A number of date and time calculations have been made available in openHAB through ZonedDateTime" but that sentence has no meaning to someone new to scripting in OH. The example needs to clearly point out that ZonedDateTime is the library/object that you must reference in order to access ‘now’ like this:

Which language?

Those examples are Rules DSL (for now unless otherwise indicated all examples in the docs are Rules DSL). For Rules DSL that example is correct. now is injected into the scope automatically.

That is not the case for other languages. For example, JS Scripting (ECMAScript 11) you get to now through or time.toZDT() (see JavaScript Scripting - Automation | openHAB). Furthermore, you’d call changedSince differently in JS Scripting (ECMAScript 11): Lights.history.changedSince(time.toZDT().now.minusMinutes(2).minusSeconds(30));

Javascript is the default language when writing scripts via UI, so it’s a bit confusing when the documentation defaults to X but the user interface defaults to Y. One would expect the two to match up. (It’s actually Blockly that defaults, but that’s just a UI to javascript.)

No it’s not. You have the choice between Blockly, Rules DSL, or ECMAScript 5.1. Other options can be added by installing an add-on. But you have to choose each and every time you create a script. There is no default.

And it’s really only recently that anything except Rules DSL was really an option for most users so many parts of the docs are a bit behind in terms of focus and the types of examples shown.

When I click on ‘Scripts’ → ‘+’, Blockly is automatically selected. Thus, the assumption it is the default. I’ve tried this in Chrome and Safari. In both cases, Blockly is automatically selected. In fact, the CSS class of the Blockly radio button is ‘item-radio-icon-start’. So, everything points to this as being the default choice.

It’s not selected. It’s just the first item that’s listed, and then you have the “or choose the scripting language” options. When you hover over an option, it changes to a very subtle light-grey shade. And since there’s no “Continue” or “Next” button at the bottom of the window, you have to click one of the choices to move forward.


Saying that, I can understand that you interpret being first and separated from the others means that it’s the default. The language also suggests this, though I could read that either way. If there had been two items in the first group, it wouldn’t look like there’s a default.

We probably could have done without splitting the three things into two separate groups.

Whatever the case, as Rich points out the documentation is lagging due to the sheer number of examples that were written in Rules DSL over the years. If you’d like to see this changed, then I’m sure the help would be appreciated. This is the tough thing about open-source software…nothing happens if no one volunteers to do it.

OH 3.2.0 Chrome and Safari:

I’m not interpreting anything. It is literally selected. See screenshot above.

I’d love to help, but since I can’t even make the existing stuff work, how can I possibly write what correctly works? I’m trying to learn, but the examples in the most recent documentation don’t work. I’m searching here on the forums and posting questions, trying to get better understanding to help out.

Sorry, my mistake. I went through “Rules” to get to the screenshot I posted. My fault for not reading your post correctly. I forgot that there are two ways to get there, as I don’t use the UI scripts.

Oh, totally. I don’t mean it to sound judgmental in any way. Just to say that if you’re interested in helping, it’s surprisingly easy to submit documentation edits.

I’m actually more concerned about binding docs showing examples for textual configuration of things and items. In some ways it’s less of an issue (since text configs still work), but it’s not as helpful for newcomers who only know OH3.

Let’s assume that Blockly is the default, which appears to be the case depending on how you get to the language selection page (sometimes it is, sometimes it isn’t). Blockly is its own language. It currently “compiles” into ECMAScript 5.1 but that is likely to change sometime (perhaps even sometime soon). That fact should not be taken to mean that ECMAScript 5.1 is the “default”.

By policy and design, there is not default language. All languages are given equal billing. I’ve seen it discussed that in the future, all languages might become an add-on with none of them being built in.

All those Rules DSL examples will at some point become labeled as such. Examples in other languages will likely be added. But it will never be the case that all examples are represented in all supported languages. We don’t have enough volunteers for that.

The key thing is to use the docs for the language you want to use as your primary reference.

For the rest, refer to the individual add-ons docs.

If you are just getting started, I recommend against using ECMAScript 5.1. Not only is it not well documented in the official docs but it’s really old and will be removed from OH as a default (meaning it comes with OH without needing to install an add-on) sometime soon (it’s currently built into Java 11 but removed from all future versions of Java). It won’t go away completely, there is already an add-on on the marketplace that will make it available, but it’s definitely to be considered deprecated. If you like JavaScript use the JS Scripting add-on. There is a very complete set of reference docs for it and it uses a recent version of ECMAScript.

Nothing is decided yet, but it has been discussed that when ECMAScript 5.1 is gone from the underlying Java, Blockly will be rewritten to “compile” into JS Scripting’s ECMAScript 11.