Custom metadata in items

Hi, i saw Design Pattern: Using Item Metadata as an Alternative to Several DPs - #13 by TI89 but it’s to complicated for me right now.

I am trying to put a custom metada data to an item using web gui:
1/ Currently on the list in item details there is :
Metadata : Apple Homekit, Google assitant
2/ i want to add custom metadata : Thermostat type with a value “abc”
3/ After clicking add custom namespace ‘test’ → metadata created.
4/ But the metadata in the GUI is empty and i cant check if it’s saved.

when i add it i can read this property using jss
var item = items.getItem(NewItem).getMetadataValue(test)
So is this a GUI bug?

If you have added the custom metadata then it still exists. The only issue is that there is currently no way for the UI to get a list of all the custom metadata that has been added to an item, so it cannot add those custom namespaces to the GUI list of namespaces. This is a known limitation and relates to the limited functions for metadata available in the API.

To re-edit the same metadata, just use the Enter Custom Namespace button and type in the same metadata namespace. It will take you to the editor with that metadata.

I don’t know when this was fixed but there is now a way to get all the metadata associated with an Item through the REST API. If you supply * for the “metadata string” in the GET Item REST API end point it will return all the metadata. All that’s missing right now is the UI changes necessary to take advantage of it.

I missed that change. That’s fantastic!

This is one of my busiest next couple of weeks, but if no one else gets to it first, I might take a look at updating the metadata UI when things calm down again.

1 Like

Looks like @stefan.hoehn beat you to it. show custom namespaces for items by stefan-hoehn · Pull Request #1623 · openhab/openhab-webui · GitHub

Right on.

Nice work Stefan!

Unfortunately I didn’t get that far because we didn’t know what the impact would be changing it as it would break the API because it behaves the other way around as it is currently doing BUT the way you can achieve is the new API endpoint which I provided today on 4.0:

which returns all the metadata namespaces of that item:


You can then use this to retrieve the item with the metadata. There is also another PR open (where you can also see this in action) that will then show all the metadata in the UI (which is actually why I added the new endpoint) which you can find here:

I am also just know writing blocks to read and write metadata which will come soon.

Now, @JustinG and @rlkoshak while I have you both , being the widget gurus, on the call :wink: here is my question:

I am desperately looking for a way to actually READ and EDIT metadata through widgets. I have seen complex widgets who seem to do that but I didn’t understand it. Can you provide a very simple widget example how one can show and maybe even edit item metadata?

Can’t be done directly*. I use one of two approaches when I want to accomplish this.

  1. The metadata or edits are fairly simple: Use an item to pass the relevant information to a rule and update the metadata from a rule.

  2. The metadata is complex: I use include a oh-link that takes me directly to the edit metadata page in question (see, for example, the widget for the Bayesian system).

*- Theoretically you could build the widget so that at the press of a button variable values are submitted to the metadata API, but that sounds like a awful lot of work…

Not me. I only know enough to be dangerous. I can work with the default widgets but I could begin to create something refined and useful.

I see Justin is replying so I’ll just wait and see what he has to say. I’ve never dealt with metadata in a widget but I’m pretty sure you need a rule to change it.

Could you provide a simple example for that how to edit an item and send that to a rule? Maybe I can abuse this…

Basically item metadata let’s you store lots of configuration without using items in particular if that configuration IS related to that item. This is why I am looking for an easy-to-use UI (=Widget) that allows me (and therefore a user of my UI) to change metadata without wasting items or using the admin item UI for that.

The basic version only requires a few parts:

  1. A proxy item specific to this use - String type
  2. A rule which triggers when the proxy item value changes
  3. A component in a widget that sends a command to the proxy item

The magic is really only in the command that gets sent to the proxy item by the widget. You want the proxy items state to convey the information about which item’s metadata is being updated and what that update is. You can do something as simple as put a comma between those two pieces of info (e.g., “itemName,newMetadataValue”).

Now when the proxy item gets that command, its state should change and that triggers the rule. The rule can get the proxy item state and split that state on the comma so that array[0] is item to update and array[1] is data and the rule can then easily update the metadata by your prefered method.

For completeness, I then usually have the rule reset the proxy item to some default value.

You can see a system that is only one step more complicated than this in my scene widget and the associated rule. In that case there’s a third piece of information passed on in the proxy item state and that is just the update procedure to be performed (e.g., Add, Delete, etc.).

A comma is a part of the metadata configuration normally so if you stick to the format of metadata string as it appears in .items files, some other character might be better.

With the latest changes in openhab-js you can set metadata through the Item openhab-js/items.js at 99755070df9b4fa3d96157f74bbeb3809ae22514 · openhab/openhab-js · GitHub (I don’t think the docs have been updated/rebuilt yet.)


This returns an Object with a value and configuration, with the value being a String and the configuration being a map of name/value pairs.

There’s also a replace and remove method.

It’s more complicated in Nashorn and older verisons of openhab-js.

This is exactly the widget where I spotted your metadata work and where i had no clue what your were doing :sweat_smile:

But I’ll do my best the next days .

I know, Rich, Florian and I worked together on that lib (at let’s say I verified it) because it becomes the basis for the new blocks.

creates this'teststate').getMetadata('rollershutter').value);

So, the blocks will be there soon but a simple Widget that would allow to edit these, is missing.

The comma is arbitrary. It’s get eliminated when the item state is split by the rule. It can of course, be anything else.

A second option is to format the item state as a json string and then just parse it into an object in the rule. I do this too sometimes when more complicated information is needed, but, of course, it gets a little trickier formatting the string in the widget in the first place (although, that is easier now that string templates can be used in the widget expressions).

Well, all things considered, editing Item metadata should be an administration function, not necessary a user facing function (at least not directly). As such, we already have a UI for administrators to modify Item metadata on the Items page (and the util of that page will be greatly improved with your PRs).

There are some specific use cases where I could see presenting a slider setpoint or the like on the sitemap which might influence Item metadata in some cases (e.g. @JustinG’s scene control suite, updating Expire timeouts based on some event, etc.). But I’m not sure it’s something that should be exposed to end users through a widget most of the time and if it’s done the fact that it’s metadata being set should be invisible to the user.

If we want an easy way to edit metadata from a widget, we can extend the widget actions here: openhab-webui/widget-actions.js at main · openhab/openhab-webui · GitHub.

Ok, here is one of my usecases (and please don’t ask why I want to set these values manually - I heard that before ;-))

I have around 20 rollershutters which I want to open and close at specific times (and it is not only me but other installations as well). I like to store these open- and close times at the rollershutters’s item to open and close the shutter. And I want my user to be able to edit these values via the UI (using the item UI for configuring this, to me doesn’t make snse).

And yes, you can do all of this with proxy items (40+) and I have done this but the maintenance of all of these items is a nightmare (believe me I have done a lot with tags that relate to the items to find them automatically in the rule but setting up all of this really is hazzle).

I agree that not all of metadata should be edited by the normal user but I do see quite a number of usecases where it would be really helpful.

Great Florian,

that was something I was hoping to find!

let’s join forces and make that our next project :fist_right: :fist_left:

1 Like

This seems a reasonable use of metadata. But instead of a widget to edit the metadata directly you’d create a widget to choose your Item and choose a start and stop time. That gets published to one or more Items which trigger a rule and it’s the rule that updates the metadata. Or, @florian-h05’s idea to add a change metadata action to a widget.

But what you really don’t want is to have to present to your user some text field where they have to enter what will be to them some arcane String or mysterious characters and deal with the errors that will result from typos and such.

The last gotcha here though will be that most (all?) of the OH widgets are designed to update or interact with one Item. You can use expressions and such to present information from multiple Items but the control only commands/updates one Item. So to do anything more complicated is going to require a compound widget and coordination between them. Not impossible but not super easy either.

Have you considered using rules/scripts to create and manage the Items?

1 Like