Migrating from text files to Paper UI for Things using REST API

Hardware: RPi 3
OS: Raspbian GNU/Linux 8 (jessie)
JRE: OpenJDK Runtime Environment (Zulu (build 1.8.0_181-b122)
OH: 2.5.0 (Build)

Hi all,

I’ve spent the last week or so upgrading to OH 2.5 and then migrating all of my .things files into Paper UI through auto discovery. A second step has been migrating away from legacy 1.x bindings where a 2.x exists…

I stopped when I got to the MQTT things/items because there are a fair few of them and “there must be a better way” than doing it manually through Paper UI (and avoiding potential inconsistencies)?

Following on from a couple of comments made in a threads - the one I can refer to is this one - [SOLVED] Switching from PaperUI based config to Text file config only is reference to a method of “create 1 Thing in Paper UI”, use the REST API to get the details, modify and then create through the API.

I can follow the “GET” bit to retrieve the details, but does anyone have a step by step guide to post the API calls for the insert/create tasks, and - do I need any tools/plugins etc. I’m at a loss as to where to start…


The first place to start is to install the REST API Docs. It’s under the Misc tab in PaperUI.

They are docs so using it should be pretty self explanatory. If not please ask and we can try to answer.

You will scroll down to the Things section, click it and it will open up with all the Things API calls.

The two circled end points are the ones you care about. Look at the text to the right, it tells you what the endpoint does.

First get the Thing. Click on that row and a form will open out. Put in the Thing ID of the one you created in PaperUI already. Click “Try it out!” and it will fetch the Thing’s JSON. That will be in the “Response Body”.

Copy that JSON and paste it into the “body” field under the POST end point. You may want to use a text editor instead as the box is kind of small.

Go through the JSON and remove:

  "statusInfo": {
    "status": "ONLINE",
    "statusDetail": "NONE"

and and “linkedItems” sections, e.g:

      "linkedItems": [

Notice the commas.

If you don’t link your Items to your exemplar before pulling the JSON it will save you some work here. And I don’t think it matters if you keep the “statusInfo” section really. I think it get’s ignored.

Now go through the JSON line by line and change what needs to be changed for the new Thing. You will want to change at a minimum the label, UIDs (don’t forget the ones in the Channel definitions), and topics.

Once you’ve made your edits, copy and paste the edits into the “body” field under the POST end point and click “Try it out!” You should see a 200 response code. If there is an error, look in openhab.log to see what was the cause.

After you do one or two it becomes pretty routine and fast.

1 Like

Thanks Rich,

Simpler than I was expecting - I was simply hitting the rest url @ :8080/rest/things which now I’ve seen the explanation above is why the confusion/stuck!


Please tick the solution, thanks