Storage of items authored in PaperUI

I’m fairly new to openHAB, and I have a confusion.

I can author items in two ways, I can manually write an item file, or I can edit things in (e.g.) PaperUI.
The storage of those two things is different though. I actually haven’t worked out where the ones edited in the UI are stored yet. What editing things in the PaperUI doesn’t do is write an item file. Wouldn’t this be the obvious way? Since there can be lots of item files there could easily be a “ui.iems” file or something, so it wouldn’t overwrite manually created items.

That way you can move seamlessly from being a “basic” user starting out and using the UI to a “power user” where once you know what you are doing, certain things are going to be quicker to do by editing the files. Or you can tweak things (like adding format strings, which doesn’t seem to be supported from the PaperUI interface).

Since I’m new to openHAB, this might be a mad thought though.


Check out the following info :slight_smile: :


To me it’s confusing to have two storage methods. For example you don’t seem to be able to set a “format string” for an item as part of the label from within the PaperUI, but you can in an item file, so so have all items stored in the same format would be ideal. You can then tweak things in the text files in only one format for example.

So I can see that I can at least change the text now (I could do search and replace for example). I still think that a storage format that uses “.item” file format would be much better though.

Sounds like that discussion has been had a resolved though.

(As a newbie, knowing what to search for is hard. Even now, knowing they are there, I can’t find those posts if I search for naive things, things that don’t assume knowledge like “JsonDB”)



You are right… I never checked this out on PaperUI :slight_smile: (I do all of my item configs in flat files)

I have a good opinion about jsonDB. TBH, I don’t really use it (only for my Z-Wave things)…

I am sure that if a community member would come up with a better solution, the maintainers would evaluate it.
There have been many, many discussions on this topic but I never saw anyone stepping up to the challenge :wink:

1 Like

Actually, you can define a format string by adding it to the label in PaprrUI, e.g. Chromecast Status [%s].

1 Like

Oh, ok…
On the other hand… if you have already defined the item label with a string in an *.item file, it doesn’t show up in PaperUI :frowning:

So there really isn’t two storage methods. All items end up in the JSON DB and OH operates off of the JSON DB. Json db is the storage method. There are two ways to define items though. When you do so via the UIs (paper or HABmin) they are stored straight into the db. When you use .items files, those files get parsed and put into the db. When there is a conflict, the text files take precedence.

Gradually PaperUI is becoming more and more capable and the end goal is clearly to be able to do everything within it and no longer require the text files fur some things. But as long as there are critical bindings (I’m looking at you mqtt) that have yet to be ported to 2.x there​ will always be two ways. That is one of the things we give up to be backwards compatible.

There are significant deficiencies in .items files which drove a lot of the changes to OH 2 that support automatic Discovery of devices. For that reason .items files will never be the one way.


I think that’s the main confusion there. Look at an item defined in an item file that has a format string and that format string doesn’t show in the paperUI, so why would I think that setting a format string as part of the label in the paperui would have the desired effect. I admin though it’s on my list of things to try out and I haven’t gotten to that test yet.

There really ought to be a separate “Format string” entry field with common choices and help etc. To bind this up into the “label” seems very confusing to me.

That doesn’t appear to correlate with what I see. I have some items defined in “.items” files, I can see them in PaperUI, yet I can find no record of them in any files in the “jsondb” folder. I was wanting to see how the “format strings” appear in the JSONDB files, but none of my manually defined items appear there.

Maybe I’m misunderstanding though.

I agrree on that. There should be a fomat field in order to separate the label content from its form.

Although theoretically you can edit the JSONDB files by hand you appear to have to stop openHAB first.
Just in case anyone tries the same.

I still think that storing things back as .item files seems the most intuitive thing to do as a user.

Sorry to bother you again: that is clearly stated in the docs:

As stated above, the files are only read during system startup - therefore if you change a file you will need to restart the system for the changes to take effect.

I might be misremembering as well. I’m on travel with no a laccess to my system, and even then I don’t define Items via the UIs. I can’t find the thread where that was discussed anymore either (it’s hard in the phone).

What would be most intrude to the user is the ability to do everything through the UIs. And that is the direction OH is heading. It just isn’t quite there yet.

The discussion about saving everything in .items files has been had and decided.

What is stated in the docs is that you have to restart openhab. What isn’t stated is that you should stop openhab before editing the files, that’s my experience anyway. I edited the files as per the documentation, restarted openhab and it had rewritten the files, presumably on shutdown. So it seems to be “stop, edit, start”, rather than “edit, restart”.
That’s all.

The docs should be updated. Can you open an issue on the openhab-docs repo?

I have a mix of different setups and checked the JsonDB right now:

  • Things and items configured in text files don’t show up in JsonDB
  • Things via PaperUI, items via text files don’t show up in JsonDB
  • Things and items configured via PaperUI do show up in JsonDB (surprise :slight_smile:)

I guess @tomq42 is busy setting up his openHAB system, so I created a PR:

1 Like

Tom i faced the same problem when i started using openhab2. Created everything in Paper UI, when i see some missing properties i switched to config files, then trying to use the full potential of openhab2 switched back to paper UI, and then when i update OH2 lost all settings, switched back to config files and so and so. After some serious struggle, i set up my system like this, and happier since:

Paper UI: Install necessary Bindings and create ZWave things if there are any.
Things File: Create everything in .things file except Zwave, since in OH2 you cannot assign parameters to zwave node channels, like invert_percentage.
Items File: Create all of your items here in .items file, very easy to manipulate and update since in OH2 all items are sorted according to their labels, not item names and very hard to find an item after a certain number.
Sitemaps, Rules, persistence, scripts, transform files: All config files.

As you have realized anything you create on config files appears on Paper UI without any jsondb file, and they are read only under Paper UI. And anything you create on Paper UI is only available as jsondb file, and editable on Paper UI.

The more you use configuration files, easier to backup your system. If you change anything in config files you do not have to restart OH. Yet again, this is my thought, you are welcome to try anything. And this is for the current situation, i hope someday i will be able to handle everything in Paper UI :slight_smile:

1 Like

Whilst I agree in principle, the user interface has to be pretty sophisticated to keep the power users happy. At the moment it seems like it’s the worst of both worlds in a way, in that you can get started with PaperUI, but after a while you reach the conclusion that you’d be better of with .item files instead. However that’s a hard transition because everything you’ve got is now in JSONDB. Indeed I’ll probably write myself a utility to read the JSONDB files and write .item files from it.

As an example, I was trying to set up groups for things earlier. I wanted to put all the “battery” items into a group. My word it was hard work in the PaperUI, and I’m not convinced I’ve got them all. You select an item, and edit it to add the group. You go back to the item list and you’ve got no idea where in the list you where, so what the next one to look at was. If you happen to also change the label while you are at it, you’re completely lost, as the item list changes order! With an item file it would be an easy scan to check that I’ve got them all, and it’s easy to go through them one by one.

I can imagine improvements that would make this much easier. For example, being able to add items to groups, as well as groups to items, and maybe having all items listed with check boxes next to the ones in the group (for example).

Anyway, I think I’ve come to the same conclusion as @febz11 above, and will move that way too.

I think I’ve come to the conclusion that this is the right way, at the moment.
It’s sad in some ways. Initial item creation is much simpler within PaperUI, but most other things it seems are just not. Until such time as I have the time to understand how the code works to the level that I can contribute to it, I think I’ll migrate to using item files too (most of my “things” are zwave).