Migration vs Fresh Installation


this is more a theoretical question to get a better feeling what others think about this:

Doing an update / migration e.g. from OH3.x to OH4.x is the recommended way. You will keep all your configuration and adjustments.

However would it make sense from time to time not doing an upgrade but to do a fresh install from the scratch (e.g. to get rid of old / unused stuff that maybe became obsolete over time)?

What about migration vs fresh setup of all the configuration?
When using text based configuration you can more simple do a fresh installation and copy your things, items, rules,… files as needed (+ adjust the files before and remove no longer needed records).
When using UI based configuration the backup / restore function should only used within same OH version, therefore it is not supported to backup OH3.x configuration and apply to OH4.x.

Also (besides editing jsondb files manually) there is no simply way to decide what part of configuration should move from one system to another. Its either all or nothing.

Food for thoughts and would love to learn about other peoples pov:
Does anyone see benefits in doing a fresh installation vs migration?
Are there any other tools to partially migrate OH configuration (e.g. using REST interface to selectively read/write configuration)?

Thanks in advance :slight_smile:

This is less so now that OH 4 comes with an upgrade tool. But the upgrade tool does not include support for all breaking changes so it might not work every time or in every case.

It all depends on what you want. If you just want to continue running your OH with minimal changes migration is definitely the way to go. If you want an opportunity to change things (e.g. adopt the semantic model, change your Item naming scheme, change to a new rules language, etc.) a fresh install is a good idea.

Note, there are tons of changes and updates internally but the user facing changes are mostly additions, not massively new ways of doing things like the changes between 2.x and 3.0 was. An in place upgrade is pretty smooth and requires relatively minimal effort.

If you are looking to only partially migrate recreation of the Things and Items is probably going to be the smoothest approach. You can copy the rules. for the most part using the UI or the REST API one by one but the effort to discover Things and Create Equipment from Thing is less than copying.

1 Like

This is my plan, mostly because I started in OH2 and carried that over to OH3 without making significant changes. Everything works pretty well for me in OH3, so I want to keep it running while I replicate in OH4 using UI items and rules. That gives me an easy fallback if something doesn’t work, and prevents me from feeling rushed to get it done in a weekend.

I’ll start by documenting all of my things and items in a spreadsheet with columns for their current UIDs and names, and a column for their new UIDs/names. Since my items and rules will be in the UI, I’m not going to worry about changing the default IDs.

For what it’s worth, I planned to do all of this when I moved from OH2 to OH3, but the quick migration worked pretty well for me. Since it was “good enough”, I didn’t prioritize the ground-up rebuild. There are only two issues with this:

  1. I have to remember syntax when I edit my rules, which has never been my strength.
  2. When people ask UI questions in the community, I often don’t know what they’re talking about.

So it’s time to move to the UI, and I might as well start fresh.

1 Like

I’m nots sure exactly what you mean here but just in case, I strongly recommend replacing the default random UIDs that OH creates with something meaningful. For example, mqtt:broker:mosquitto as opposed to mqtt:broker:lkjasd345.

1 Like

Ah, okay. I seemed to recall you or someone else recommending not to worry about UIDs, but maybe that was with items? Or maybe I’m just out to lunch. That’s a very real possibility.

Item names are not randomly generated and it’s somewhat important to have them with reasonable names. But it is true that in the UI, the Item label is much more prominent than the Item name. But if you do anything other than Blockly the built into the UI basic Actions and conditions you’ll still need to reference Items by name in your rules.

When you use “create equipment from thing” or “create points from thing” to generate your Items, the Item names will be based off of the Thing label and the Channel label. For example, I have an MQTT Thing labeled “Basement AirThings Wave Plus” that has a Channel named “Barometric Pressure”. The Item that was created is named BasementAirthingsWavePlus_BarometricPressure.

See? Exactly the sort of thing I’d know if I had rebuilt my system two years ago. :wink:

The automatic Item naming <Thing name>_<Channel name> is “the cheap way” to get almost unique Item names which will have a meaning for the user (at least, if the user already set the thing and channel labels correct).


imho, Item names should not refer to a specific hardware at all, e.g. Basement_BarometricPressure should suffice, it is of no interest which hardware is used, and maybe, at some point, the hardware will be replaced with another hardware (not the same model…) and then you would have to either create a new item (and lose old measurements) or to use the old item, which name is now wrong at least in parts.

For that reason I tend to change all Item names when creating them automatically, and as this process is time consuming through the UI, I use *.items files and do the changes with VS Code in “no time”.

1 Like

I agree that would suffice, but not so much that I think it’s worth worrying over much about it or doing anything about it except in certain circumstances. When using managed Items, the name of the Item really doesn’t matter nearly as much as the label.

All this is true, but if what you see most prominently in almost every place in MainUIis the Item’s label (Model, Items, Item selection dialogs, Overview page, Links, etc.) is that really a big deal? You almost have to go out of your way to see the Item’s name.

And of course you have the option to change the names of the Item in the create equipment from thing form so you do have that option. And it doesn’t really take much more time than in .items files. It’s also something you only have to do once.

But also note that the names of the Items do not come directly from the Thing per se. The way it works is:

  1. click “Add Equipment to Model”

  2. select the Location where the Equipment will live in the model

  3. by default the name of the Equipment will come from the Thing’s Name, but you can change it (e.g. remove the “AirthingsWavePlus” from the Equipment Name). For example, here I have a Thing called “All_speakers_group” and I’ve removed the “group” from the equipment name.

  1. select the channels you want to use in the Equipment. The names for the Items come from the Equipment’s name, not the Things name, so if you correct the Equipment first, that will change the names for all the Items.

You don’t need to change each Item’s name individually.


Good point! Thanks for that hint.

I want to do a fresh installation using information of my OH 3.4 as a starting point. Is there a way to list all bindings, things, items and so on I currently have in my OH 3.4?

Look at the API Explorer under Settings → Developer Tools

Thanks a lot.

If I use the API (e.g. fetching all things), I get the result in a text widget, but when I try to download it, the result is:

Requested content not found.

Any ideas how to fix it?

Depending on your security settings, you may need to authenticate to the API with basic auth or a security token as part of the request.

Notice the example curl command it shows you in the API Explorer will include an Authorization header.