[OH3] Add metadata to Items via configuration files

[shaselb]

Hi folks,
how i can find out the syntax to populate the “read only” property of an item within the *.items conf-file? Options are working fine…
Thx, Sascha

[JanK]

Hi @shaselb, Hi Search User,

Summary

stateDescription=""[pattern="%d%%",min="0",max="100", readOnly=true]

I was looking for the same question because it is case sensive and I did not know that.

So the following stateDescription has to be configured for your item:
stateDescription=""[pattern="%d%%",min="0",max="100", readOnly=true]

Kind Regards

[der_tobi (ET)]

hi all!
is it somehow possible to use a range value in options? for example:

<980=stormy
980-1000=rainy

and so forth?

thanks

[hafniumzinc (T)]

Probably not. Are you aware of the Scale Transformation Service?

[der_tobi (ET)]

thx, that did the trick

[shutterfreak (Olivier Biot)]

@hafniumzinc

State Description

Via the UI, the following options are available:

To populate these fields via configuration files (example values):

Number nTest "Test Number Item" {
	stateDescription=""[
		pattern="%d%%",
		min="0",
		max="100",
		step="1",
		options="1=Red, 2=Green, 3=Blue"
	]
}

Thanks!

UPDATED: However… it does not work on openHAB 3.0.2. The language parser chokes on this format of stateDescription metadata. Maybe it’s the empty double quote portion that is the culprit, as also mentioned in:

How to add item pattern format via "Add items via textual definition"? (migrate from .items files)

Dear all, during migrating from OH2.5 to OH3 I had some issues to maintain the patterns via “Add items via textual definition”. After longer searching and playing and shouting and playing again, I found a solution, I’d like to share. Maybe it is helpful for someone else. In short I’d like to import all items from *.items-files OH2.5 to OH3.0 via “Add items from textual definition”. But patterns have been ignored. What I tried and how I solved it Keeping the *.item files under OH3 works fine.…

More precisely:

The trick is, to add the pattern as metadata in the textual definition. E.g. , stateDescription=" "[ pattern="%1$tR" ] (Make sure you have a space or some other text in stateDescription=" " / Empty does not work)

(The example successfully assigns and properly configures the custom temperature_list widget for list items, but skips the offending stateDescription metadata definition block.)

It however works when adding a single space between the pair of double quotes.

Bug report:

Cannot assign stateDescription metadata in Item creation from textual definition

[Lionello_Marrelli]

Impossibility to set the “actionAnalyzerItems” in items file.

Let me highlight another limitation of items files concerning setting metadata for widgets.

I noticed that the oh-label-list widget does not offer the possibility to “analyze” the time behavior of the item, differently than the oh-label-card. This behavior can be modified by editing with the UI the metadata “Default List Widget”, in particular by filling the fields action with the value “analyzer” and the field actionAnalyzerItems with the name of the item (Question: why doesn’t it default to the item to which this widget is applied?).
The YAML is as follows

value: ""
config:
  action: analyzer
  actionAnalyzerItems:
    - Pres_Anna

With this manual modification of the configuration the widget expose the analyze button and everything works as I wish.
As I am wishing to apply this modification to a number of items, I am trying to set a metadata in the **items file **, following the informations in the OP, as follows

Switch Pres_Silvana    "Pres Silvana [%s]"   <presence>  (gEquip_PresPD) ["Status","Presence"] {channel="xxx",
         listWidget="oh-label-list"[action="analyzer",actionAnalyzerItems="Pres_Silvana" ]
         }

but this item does not appear in the list of items under the equipment. If I remove the metadata it obviously reappears. The item is, in both cases visible from the settings pages (both in the model and the items pages) and it also shows that metadata are modified. Probably it is discarded, because the metadata are not correct. In fact, by looking closely to the code section in the UI, in order to inspect the YAML, it is as follows:

value: ""
config:
  action: analyzer
  actionAnalyzerItems: Pres_Silvana

The line actionAnalyzerItems does not look the same as the one set manually. The same YAML appears also if I import from the UI with the option “import from .items file”.

When importing from the UI the YAML can be modified by inserting the missing newline, dash and indentation in order to make it look like the previous one. With this modification the item re-appears in the list under the equipment in the UI.

[Lionello_Marrelli]

Workaround for the previous post limitation.

By using a custom list widget, slight modification of @rlkoshak example custom list widget for presence, setting the actionAnalyzerItems field is not required any more.

uid: listWidget-presence
tags:
  - list
  - presence
props:
  parameters:
    - description: The label for the widget
      label: Person
      name: title
      required: false
      type: TEXT
    - context: item
      description: The presence switch Item
      label: Item
      name: item
      required: false
      type: TEXT
  parameterGroups: []
timestamp: Aug 17, 2021, 10:37:02 PM
component: oh-list-item
config:
  icon: f7:person_circle
  iconColor: '=(items[props.item].state == "ON") ? "green" : "red"'
  color: '=(items[props.item].state == "ON") ? "yellow" : "gray"'
  title: =props.title
  item: =props.item
  badgeColor: '=(items[props.item].state === "ON") ? "green" : "red"'
  badge: '=(items[props.item].state === "ON") ? "IN CASA" : "FUORI"'
  action: analyzer
  actionAnalyzerItems: =[props.item]

The last line is tricky. I was naively trying

  actionAnalyzerItems: 
  -  =props.item

but it didn’t work. I found in another rlkosk example that the right syntax was the one that i showed in the working yaml.

Once this widget is saved under the developer tools , a simple items definition such as

Switch Pres_Silvana    "Pres Silvana [%s]"   <presence>  (gEquip_PresPD) ["Status","Presence"] {channel="xxx",
         listWidget="widget:listWidget-presence"[title="Silvana" ]
         }

allows me to define the widget in the items file

[mstormi (Markus Storm)]

@Lionello_Marrelli

Impossibility to set the “actionAnalyzerItems” in items file.

Dunno why it does not work for you but for me it does (without defining a widget).
Probably item: is required.

- component: oh-label-card
     config:
     item: PVNetzeinspeisung
     title: bla
     action: analyzer
     actionAnalyzerItems:
       - PVNetzeinspeisung

[Lionello_Marrelli]

Thank you for reading my post and giving me the opportunity to clarify it.
The point of my post is the fact that the YAML line concerning the actionAnalyzerItems field is not correctly generated when the metadata is specified in items writen in items file. The value (i.e. the item name) is on the same line and not preceded by a new line, dash and indentation.

When using a custom widget, the parameters that need to be specified in the widget metadata are correctly generated when imported by items file, because values are in the same line as the the key.

The other problem I found with the custom widget always concerned the actionAnalyzerItems but this time it was in the YAML itself.
Using the inline syntax

actionAnalyzerItems: =[props.item]

The time history of the item is shown, while when using

actionAnalyzerItems:
  - =[props.item]

the popup window showing the time history is opened but empty. This also applies if I remove the square bracket. On the other hand, if I replace =[props.item] with an actual item name (as in your case) the the analyzer window do show the time history of the item. Clearly this makes the custom widget useless because it cannot be customized.

I hope that this is clearer now. I am not a programmer nor a native english speaker, so probably my previous posts were not sufficiently clear. I modified them in order to try to state the problem more clearly

[mstormi (Markus Storm)]

I think you have a misunderstanding here:
The point is that actionAnalyzerItems is a UI property but it is NOT item metadata so you cannot specify it via .items.

It’s confusing that specifiying fields that way seems to work generically (i.e. even for properties that do not exist), but note that the fact that it works for non-metadata, too, is strictly speaking a bug.
It’s however always assuming the standard property: value format. But actionAnalyzerItems is a list and therefore requires a different format.

[Lionello_Marrelli]

@mstormi

The point is that actionAnalyzerItems is a UI property but it is NOT item metadata so you cannot specify it via .items.

Actually, based on the fact that this property is set in the UI when I edit the item metadata and it is stored in org.openhab.core.items.Metadata.json I concluded that it was an item metadata.

Anyway, thank you for your comment: may I conclude that the workaround that I have found may not work in newer versions of openHAB when bugs will be removed? Maybe @rlkoshak can give some comment on this point.

Thank you

[mstormi (Markus Storm)]

@Lionello_Marrelli

I edit the item metadata and it is stored in org.openhab.core.items.Metadata.json I concluded

I might be mistaken there, too. I think only @ysc can tell.

[rlkoshak (Rich Koshak)]

@mstormi

The point is that actionAnalyzerItems is a UI property but it is NOT item metadata so you cannot specify it via .items.

The “Default X Widget” definitions are in fact stored in Item metadata.

@Lionello_Marrelli

Maybe @rlkoshak can give some comment on this point.

I can but you will probably not like it. In an effort to better use my time helping less experienced/less technical users I’ve pulled back from providing help with text based configs. I’ll still help with basic stuff and stuff that can’t be done through the UI but particularly Things and MainUI Widgets/Pages I’m just not going to mess with. It’s a huge time sink.

Having said that…

@Lionello_Marrelli

As I am wishing to apply this modification to a number of items, I am trying to set a metadata in the **items file **, following the informations in the OP, as follows

Alternative approaches that will let you more easily apply the same modifications to multiple Items with minimal effort while still using the UI include:

• Create a Custom widget with all the settings. Then you just need to apply the custom widget to your Items. That’s pretty much the whole point of the tutorial you linked to with the custom list widgets. I define a widget for, say temperature Items. Then I apply that custom widget to each temperature Item. If I decide later I want to change the way my temperature Items to look I can change the one Custom Widget and it changes all the Items that use it.

• Use the REST API. Create and test the metadata once using the UI in the usual manner. Then use the REST API to query for the metadata and copy/paste/edit/resubmit to apply it to additional Items.

• Stop openHAB and manually copy/paste/edit the metadata.json file. This approach is not recommended except as a last resort.

Beyond that all I can really offer is that defining the metadata on the Items in .items files should be possible. There really is nothing special about the default list widget metadata from expire or Alexa metadata. It follows the same rules and formats and it processed by the same block of code I believe. So if it’s not working there is likely a typo somewhere in the Item’s definition.

[Lionello_Marrelli]

Thank you for your post: I deeply appreciate your efforts for letting non-experienced user to take advantage of openHAB.
Actually, I mentioned you because I was only wishing to understand the question of what is stored in metadata and about the small widget issue that I found.

@rlkoshak

In an effort to better use my time helping less experienced/less technical users I’ve pulled back from providing help with text based configs.

It was not my intention to ask for help on textual configuration, but simply to let other know about its limitations.
I fully understand your point and, while porting my OH2.5 to OH3.1 with text files, I’m practicing with adding new things and items with the MainUI, keeping track of the YAML code in text files.

The other observation that I described was about a widget YAML, but I will open a separate thread because it is only marginally related to writing metada via configuration text files.

[xgon (Alexandre Gonçalves)]

Adding metadata to Items configuration files, enables the usage of displayState property, right?

Is there any documentation regarding the stateDescription field, for each of the item types?

[rlkoshak (Rich Koshak)]

@xgon

Is there any documentation regarding the stateDescription field, for each of the item types?

No because your question kind of reveals a misunderstanding of what the field is and how it works. There is not singular stateDescription filed. It’s a metadata structure with several fields.

Each Item can have a State Description metadata defined. That metadata includes various information about the how to show the Item, the two most important of which are the Pattern and the Options.

Pattern is the same as the stuff that goes between [ ] in a traditional sitemap label (see Items | openHAB). the Options is a way to replace the MAP transformation in that state presentation.

You can see what the metadata looks like by opening the form on MainUI, putting something into each field and click on the “code” tab. That shows what the metadata looks like in YAML format. You should be able to translate that to .items files if that’s what you are after. See Items | openHAB.

But note, this is all independent of Item type.

[serge_simon (SRG)]

I’m not able to find a clear answer on this : is it possible to apply the “iconUseState” inside the .items configuration files ?

From config / yaml it would be :

config:
  iconUseState: true

But as i have a tons of items to update this way, i would like to configure this in a plain text way (.items, or something else, if available).
Additionnaly :

• i’m not sure that in this case the “custom widget” approach (spoken about a few messages before) is suitable here ?
• and of course i’m not willing at all to edit the JSON internal DB representation

[serge_simon (SRG)]

Replying to myself …

So i had to rely on this script to automatically update all my “battery” items (with that type as a “category” + being “Number”, in order to exclude LowBattery (which are “Switch”)

jq is used to filter the JSON results.

Here the command is updating the iconUseState for all items (whatever the number of items to update is).

BEARER_TOKEN="<API bearer token to be retrieved from examples in API explorer, for example>"
OPENHAB_HOSTNAME="192.168.8.4:8080"

curl -X GET --header "Accept: application/json" "http://${OPENHAB_HOSTNAME}/rest/items?recursive=false"|jq '.[] | select(.category == "battery") + select(.type == "Number") | .name' | sed 's/"//g' | sort -u | while read ITEM ; do
  echo "Now processing [$ITEM]"
  curl -X 'PUT' "http://${OPENHAB_HOSTNAME}/rest/items/${ITEM}/metadata/listWidget" -H 'accept: */*' -H 'Content-Type: application/json' -H "Authorization: Bearer ${BEARER_TOKEN}" -d '{"value": " ", "config": { "iconUseState": true } }'
done

Not the most convenient way to do that kind of manipulation, but, well, it’s better than having to rely on the UI.

And of course it works (all batteries had the same icon before).