OH3 files or GUI

I agree! I, too, constantly redo everything, having learned something new, I constantly try to apply it, but it requires a large-scale alteration. In addition, I have 3 servers, at home, in the garage and in the country. Having done something in one place, it is very easy to transfer it to other servers using the file option. In a graphical interface, this is more difficult to do.

What would be great is to be able to import and export the ui objects to files, including rules and things

That’s an ever-recurring request but it won’t happen.
In the past there simply was noone willing to build it, but now UI functionality has essentially outgrown the capabilities of the file format. So now it cannot even be done any more.

Why not? at the end of the day all the UI things / rules, etc are stored in a JsonDB, so as I see it its should be only a matter of export / import entries from the system db in json as it is stored internally. Or do I miss something?

Yes, about everything.
It would require to define a new file format that is backwards compatible so all input processing would need to be rewritten, too.
It hasn’t been done earlier (at times when it would have been easier because the existing format would still have been sufficient by then) because the benefit it brings is considered marginal and nowhere in line with the efforts.
And it requires a lot of fruitless work that one of the very few people to be able to do it would need to be willing to spend on this and not on some more beneficial feature.
Why should some volunteer spend his personal spare time on that ? “Fun” is not the answer here.

now UI functionality has essentially outgrown the capabilities of the file format

That is an interesting information.
Reading through this and many other threads regarding whether to choose config files or the gui in OH3 I
must say I cannot get all facts straight.

What I collected:

  1. Looking at the official comparison you will find out, that for transformations and persistence files are a must:
  1. On the other hand with files you are not able to use yaml as scripting language.
  2. Obviously the file format is not able to keep up with the options presented in the gui so at some point you will be left out when new features are implemented and you are depending on files.

In OH2 I used a combination of gui and files.
Things I autodiscovered and added for convenience through the gui, everything else I did in files.

Files I was using because:
a) I twice had a OH database failure loosing all information
b) only files gave me the option to use transformations, advanced scripts etc.

I was going to do the same approach in OH3 and adding the semantic model information via text file configuration.
However, if the file format will keep me in the future from new functionalities I would reconsider that.

=> Will choosing files lock me out from new functions in the future ?
=> Is it really possible to include all the advanced scripting, transformations etc. via the gui ?

Thx for any advice !

Indeed, for those transformation configs that require files, namely Map and JavaScript, you still need to write files for those. But all the rest are defined inline and do not require files.

Yes, while a custom persistence strategy does currently still require writing a .persist file, in OH 3 persistence engines now come with an enabled default persistence strategy which covers most user’s needs most of the time. Not everyone needs to create a custom persistence strategy.

To take it further, the Exec binding whitelist, custom Ephemeris daysets and holidays, etc. also require text based configs for now.

It’s important to realize here that the YAML representation only exists in MainUI and nowhere else uses it. The YAML for rules is significantly more human readable than the JSON that openHAB actually uses and which MainUI converts between.

At the moment, the only things you can do through MainUI that cannot be done in text configs is the definition of custom MainUI widgets and the installation and the installation and use of stuff (add-ons, widgets, rule templates) from the marketplace.

This should never happen unless openHAB was force closed, machine lost power, or openHAB otherwise crashed while writing out to the JSONDB. And before OH writes out the JSONDB it automatically takes a backup in $OH_USERDATA/jsondb/backup first. Even if your JSONDB becomes corrupted, you’ll always have the working and automatically created backup.

Also note that the JSONDB is itself text files.

What do you mean by “advanced scripts”. There is exactly one thing I know of that cannot be done in a UI created rule: share a variable between rules. And even that limitation is not absolute. An approach to do so using the ScriptExtensions has been identified and today there is already the ability for one rule to call another rule and pass it data as part of the call.

Everything else is supported in UI rules the same as text based rule files.

I’ve been through that. It’s frankly not worth it. It’ll be far less work to use the “Create Equipment from Thing” and “Create Points from Thing” menu to recreate your Items and place them into the semantic model than it will be to try to retrofit the model to your existing .items files. Of course it can be done, but it’s so much more work I recommend only messing with the model when using managed Items (i.e. not .items files).

Not necessarily. It’s possible to work with some things in files and others managed (there are some bugs doing so with Items at the moment though). And there is no requirement to use new functions at all. But I suspect that new functions are going to be built UI first and only later, if someone really wants it enough to volunteer to do it, will they move to text based configs. But these would only be completely new features like MainUI Widgets and the marketplace. Anything built on existing OH features like the semantic model will be supported in both places.

You can use any valid transformation anywhere a transformation is supported in the UI. You cannot create the .map files and .js files used by the Map and JavaScript transformations.

“Advanced scripting” is really kind of meaningless so :man_shrugging: .

Thank you for your extensive feedback, I really appreciate it.

So far it convinced me to give the gui only approach a try though I believe to have more oversight looking in a text file rather than clicking several layers of menus for each equipment in order to see what I specified. (e.g. I can see all my room thermostates in one file and I can see that I used with all of them the same transformation map, the same icons etc… Via gui I need to click each equipment individually and examine it.)

“Advanced scripting” is really kind of meaningless so :man_shrugging: .

By “advanced scripting” I mainly referred to java scripts.

One other question:
I have 2 MQTT topics where I specified the thing manually in a config file because I needed JSONPath transformation. Will I be able to do that with the gui ? If not is it possible to specify those 2 things via config file and use the channels as points within an equipment via gui afterwards ?

This is one reason that I’ve continued with the config files.

Another is that I find the UI slow to use - both in terms of the number of clicks, but also in terms of performance. I don’t have the fastest hardware, so the UI gets quite sluggish.

I have defined the model in files - no issues encountered, and relatively fast once I’d worked out how to actually do it. Though in reality I don’t really use it much to be honest.

Yes, definitely.


Not necessarily. As I said, the JSONDB is text too. You can grep and search through there in a pinch.

The REST API also provides a decent set of search capabilities.

The search function built into the other UI areas can search on a number of criteria too.

And except for Items, there is a “Code” tab you can click on to see a YAML representation of what ever you are working on. You can copy/paste/edit in the code tab to quickly duplicate Channels, Things, Item metadata, etc through that tab.

I personally think it comes down to a choice. You will either need to spend a little more time and effort in the UI doing that, or you’ll need to spend a lot more time and effort adapting your Items to use the semantic model to .items files. Only you can determine if the tradeoff is worth while.

Any rules language supported by openHAB can be used in UI rules. The only limitations I’ve already mentioned. There is no “outside the rule” context so you can’t really share variables between rules. All of my rules are defined in the UI. 99% of my rules use JavaScript for anything more complicated than sending an ON command to an Item. A growing number of my rules have been posted to the marketplace for others to simply install and use.

That’s another feature that can’t be done in text based configs (yet?). You can’t define and use a rule template in text files.

Yes of course. Applying a transformation anywhere a transformation can be applied anywhere in the UI. Transformations like JSONPATH and REGEX and the like are defined inline, no separate files are required.

The only things that need to be in text files that go with the Map transform (i.e. .map files) or the JS transform (i.e. .js files). But you can still apply even those those transformations in the UI for Things and Item labels and Profiles and rules.

My personal feeling is that the answer is “both”.

The way I see it, the UI is the best approach for beginners who have no prior knowledge of OH. They can graduate up to using files as they need, and that will be their paradigm for “how OH works”. Easy stuff in UI, harder stuff in text files.

The struggle is for those of us who have had to adapt from our existing text files and our reliance on VS Code or other editors. As @hafniumzinc says, I do find it slower to click through the UI, because I know how to quickly make items with one line of text. But if I didn’t already know that, it would be much harder to learn the text-based approach. Beginners shouldn’t be troubled by that while they figure out everything else. As we’ve all learned, it’s really easy for a single typo to ruin your day. :wink:

I think the semantic model is great for beginners, because they can define it as they set up their items. It will help them to understand their systems as they build out. I haven’t bothered with it, though. Most of my equipment is automated, and the handful of things I want to directly turn on and off are accessed via Google Assistant, a simple sitemap, and one HabPanel. I’ll explore the model if I ever decide to blow up my interfaces, but it all works pretty well for me. It’s only worth fixing if I decide there’s a problem with it.

1 Like

That is my opinion exactly when it comes to OH1.x or OH2.x

I call myself a fairly experienced OH user who is running currently 2 setups, one for a 4 room apartment and another for a whole house with homematic, zigbee, etc…

With the release of OH3 and the full end of any support for OH2 I wanted to keep an open mind to changes/possibilities OH3 offers. One of these changes is the complete overhaul of the gui in everyway. (Yes, lets be honest, the OH2 gui did not cover much of what was possible in config files)

However, if I interpret @rlkoshak correctly, with OH3 the gui is no longer meant to meet only the requirements of beginners but of the professional user as well by offering feature parity in terms of possibilities for the configuration.

Out of curiosity I am willing to start all over with my configuration for the smaller project in the apartment.
Hence the question for me came up: Do I go with config files as I used to or do I believe the gui option to be as good as files and more flexible etc. on the longterm ?

In parallel to our discussion here I started to configure the first 2 rooms and I have mixed feelings:


  • Very nice overview to have everything sorted in the module tree
  • Straight forward clicking the things together


  • It is a lot of clicking around to select for every channel all the bits&blobs: Category, Semantic Class, Semantic Property etc.
  • It happend to me twice that I configured an identical equipment in one room different than in another because I oversaw that I did not select the correct semantic property => A lot of clicking to correct.
  • I found myself creating *.items and *.rules files again because I needed proxy items as the rollershutter level for homatic rollershutter is inverted :wink:

When I say “beginner”, I’m not talking about technical expertise. I’m talking about experience with OH. We all have to start somewhere, and I think new OH users should start with the UI. As they progress and build their systems from scratch, they’re unfortunately going to find that some things can only be done with text files (and hopefully that will change in future releases).

Maybe it’s more accurate to say that if someone’s starting a brand-new installation, I think it’s best to do so in the UI. But if you have an existing OH system that works just fine, there’s no reason to change it unless you have issues, want a particular feature, or just feel like learning something new. All that really matters is how much time and effort you want to put in, and what you want to get out of it.

If you’re going to redo your apartment, then your goal is theoretically to learn something new. So commit to the UI, because if you waffle back and forth then you aren’t giving it a chance to win you over. Read the docs as if you’ve never used OH, and only use files when it’s definitely not possible to use the UI. Otherwise, they’re a crutch that prevents you from learning. Relying on prior knowledge will cause you to make assumptions that also affect your ultimate conclusion.

FYI, this “UI versus code” debate comes up quite regularly in web development. There are lots of content-management systems that make it super easy to churn out webpages in a few minutes. They’re also very limiting when you want to do something that doesn’t work in the template, which forces the use of an HTML editor.

All I can really say is that a number of the developers themselves do everything through the UI too. I’m personally satisfied with the UI for most things and it’s getting better over time.

As for the clicking around, see OH 3 Tips and Tricks, in particular the “Buying in Bulk” sections. Once you create the exemplar you have options to do “copy/paste/edit” type stuff to create more. The options are a little bit more limited for Items but the REST API and messing with the JSONDB directly are both options.

I also sometimes use “Create Items from Text” to create a bunch of similar Items using .items files syntax. I don’t know if you can edit an Item that way though.

The UI supports both creating Items and rules. Obviously you can do it in .items files if you want and if you prefer but nothing says you have to. There are lots of ways to create Items in the UI beyond the “Create Equipment from Thing” option in the Model View.

Also, you probably don’t want all your Items in the model anyway. See A Deep Dive into the Semantic Model

I agree, after really forcing myself to find solutions via the UI I come to enjoy it. Moreover it offers definitely a bigger complexity which would be difficult to maintain via text files.

I created the items and the proxy rules via UI now. It works fine, however I consider to move the rules which connect the proxy items with the real ones to text files again since I see no benefit in having those “stupid rules” filling up the rules tab unnecessarily.

One thing that bugs me though is a naming issue:

I started off with a structure in my model like “My Apartment/Kitchen/Thermostate/Temperature”
While this gives you a nicely autogenerated view for the “Location” tab it just makes the information useless under the “Devices” and “Properties” tab where only “Thermostates” and “Temperatures” will show up with no connection to the location model at all.

Obvious solution and the way how you, @rlkoshak model:
“My Apartment/Kitchen/Kitchen Thermostate/Kitchen Thermostate Temperature”
While this variant gives you nice “Devices” and “Properties” views it makes the “Location” view horrible for me. Sorry to be blunt, but I hate redundant information which is all over now:

Why is the provided information about the location of every object not better used to generate the automated views ?

Don’t forget you can tag rules and the search is pretty good. I make heavy use of tags and when I’m working on one thing I’ll just enter the tag for that one thing into search and only see the relevant rules.

You can also use the developer sidebar and pin the rules you are working on instead of only going through the rules page. For example, if I were working on my Honeywell API stuff my developer sidebar would look something like

Notice how not only can I jump to the pinned rules to edit them, I can also pause them or run them manually right from the sidebar.

I find these two features make it so that the number of Rules just doesn’t matter. I can pin what I’m working on the one time and never have to look at the rest while I’m working.

Because it isn’t yet. I can’t say that it ever will be. The problem goes beyond just the Equipment and Properties tabs of the Overview page. When searching for Items to select a Rule trigger, for example, you see the Label, not the Item name. If you have a dozen Items labeled “Temperature” how do you tell the difference?

So your choices are:

  • live with it
  • hide the locations tab and keep the more descriptive names
  • hide the equipment and properties tabs and use less descriptive names, though you’ll run into less fun when browsing and searching for Items elsewhere in OH beyond the Overview page.

This is not a UI vs text config issue though. It’s just how the model and the Overview page works. I think an issue has been filed but as far as I can tell, it’s not an easy fix. The Item’s label is used in too many places.


That’s some great piece of advice and should probably do the trick. Thx !

True, I went a little bit off-topic because it came up using OH3 for the first time. I guess I will stick with the more descriptive names for now and will adjust the labels manually e.g. in sitemaps. I anyway was not planing to use the locations view.

Thx again to all of you for the great help and advices here !

The thing I’m missing most is a “Copy” button that enables me to clone an existing item (including metadata) and then edit before saving it. That would exactly replicate how I often create items in text files.

When I really think about it, .items files are just a bulk-editing interface for openHAB.

1 Like

Unfortunately, because of the way metadata is implemented that is really not feasible right now unless and until the REST API for Items and metadata changes. That’s why custom metadata namespaces doesn’t even show up in the UI. There is no way to say “give me all the metadata for this Item.” You can only say “give me the ‘expire’ metadata for this Item.”

The rest of the Item could easily be handled though but based on some decisions made early on in OH 2.0’s development we are kind of stuck for now.

Yeah, I figured there was a technical reason, as it would have been a seemingly obvious feature to include. Not ideal, but not the worst thing in the world.