OH3 - Best approach for migration from textual configuration files to GUI

At the moment I have OH 3.0 and textual configuration files (using KNX, Paradox Binding etc.).

What is the best approach for migration from textual configuration files to GUI?

I am also wondering about this question. In the documentation they mention an import-function:

Also use Main UI to manage Items. You can use the import function to import .items files or snippets taken from other sources like the openHAB community forum.

I did not find this import-function so far, I found out that you can paste text in the dialog “Add Items from Textual Definition” but this one throws errors if items belong to groups…

1 Like

same question for me, because many of my text-based-configs did not make it into OH3 and i wonder why, they all worked in OH 2.5

Ok I found a way:

First, rename the .items file to .old or something. This is important because textual definition always “wins”, and afterwards you may have problems unlinking or relinking items.

Then copy it’s content.

Go to Items -> Add -> Add from Textual Definition

Paste your .items content there.

But there are some limitations, for example comments in this style

/*Some comment*/ 

are not accepted, you can remove them while in this editor and get results below in real-time.

Good news is: When the item was linked before, it is linked also afterwards.

So I’ve been messing with this as well. You can copy your .items file into the config folder like always, but it only creates the item not the link to the thing. (Unless you add all the things and update .items file.

The problem is that it doesn’t make a “Model” which is the new way. I’m currently struggling with whether or not to convert to the new method. - I’ve linked some documentation.

Where the push is to update to the new model. - If you made your groups methodically, you should be fine to import and use the old way. (Currently what I’m testing now)

Perhaps they are migrating from an older version of OH, they did not follow the advice above to start with the model to begin with, or they are following a tutorial or example that doesn’t include the model.

As of now, I’m not sold yet.

How i works do it now given what I’ve learned is below. Keep in mind though that everyone’s config is unique and will have different requirements and hurdles to overcome.

  1. Start by creating the Locations part of the model in the UI. In a few minutes you’ll have it set up and it will pay dividends in the long run.

  2. Install a binding you use. Discover all the Things!

  3. Back to the model and create the Items by clicking on the right location and selecting “create equipment from Thing”. If you happen to already have an equipment you want to add to, choose add points from Thing.

  4. As you go check out the locations, equipment, and properties tabs of the Overview Page and if you need to adjust his they look go to the item and modify the custom widget Item metadata.

  5. Rules will largely need to be recreated in the UI rule by rule. But take this opportunity to simplify where you can by taking advantage of the Condition (but only if) and stuff like the ability to call another rule and enable/disable rules.

Step 2 has a variant for cars where you can’t discover the Things. If you’ve a lot of similar Things (e.g. MQTT), either create one, copy the YAML from the code tab, then create another one and paste/edit into the new Thing’s code tab. Alternatively, query for the Thing in the REST API explorer, copy/paste/edit the JSON to the create Thing endpoint.

I started importing my items but quickly have that up. It’s so easy and it’s less work to recreate then from the model instead.

However, I’m fully aware that certain bindings like KNX and Modbus still are easier to manage through text configs so this may not make sense for you.

From a rules development perspective, I make heavy use if the developer sidebar to interact with items, bring up a scratchpad rule to execute adhoc code, and watch Item events as they happen. With code completion and syntax highlighting and those features, plus a terminal open to tail openHAB.log, in every bit as predictive writing rules as I was in OH 2.5.

That’s The import function mentioned. If it generates errors please file an issue. I was able to import items that are members of a group and I’ve but seen reports of this being a problem. By chance do theses groups already exist?

Without tons more details who can answer?

1 Like


Thanks for your explanations. So far I have transferred all items to database and things are basically running. I also started to create semantic model, but what I am wondering about is how to organise it. For example, what to use as the “root” for the model? The location (adress)? The house? It would be helpful if you (and others) could share the model you build so far to get some inspiration :wink:

Thanks! I am mainly using binding KNX, what are the benefits of this new model?

For the semantic modem you can find an example bere: Semantic Model | openHAB

1 Like

You don’t need a root at all if you’ve no reason to add one. Your rooms can just exist independently. Or you can use Home as the root and put the rooms inside that. Or a building as the root. You’ve all sorts of options. Do what makes sense.

I use two generic Locations as the roots because my openHAB has Items from two different places, my house and my dad’s house 100 miles away. Then under my house I have an Indoor and Outdoor because I have some stuff that is outside and other stuff inside. Then I have a Home Group under Indoor which is probably unnecessary. And under that I have the three floors of my house and in those the rooms.

That’s a really strictly defined structure, but I have reasons to do it that way.

It doesn’t matter what binding you are using. The Model is built in Items. Benefits include:

  • The Overview Page’s Location, Equipment, and Propertied tabs are automatically created.

  • “Add equipment from Thing” is a really quick and easy way to add a bunch of Items to openHAB.

  • All of the Item selectors in MainUI is going to present your Items to you based on the model first.

  • It provides a way to organize and manage your Items.

  • It allows for natural language interaction with openHAB using HABot.

  • Other new features will certainly be created that take advantage of the model.

For me, the ease in creating Items from Things makes it worth use alone.

1 Like