[OH3] Add metadata to Items via configuration files

Foreword

In the UI you can easily add metadata to Items.

This post is my notes on adding the same metadata in existing *.items files in order for the UI to do its magic.

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"
	]
}

The pattern field can also contain a transformation. Syntax is (example transform):

pattern="MAP(switch2online.map):%s"

Default Widgets

You can set the default widgets for standalone, list and cell presentation from the Item itself. Within configuration files, for example:

Number nTest "Test Number Item" {
	stateDescription=""[
		pattern="%d%%",
		min="0",
		max="100",
		step="1",
		options="1=Red, 2=Green, 3=Blue"
	],
	widget="oh-slider-card",
	listWidget="oh-slider-item",
	cellWidget="oh-slider-cell"
}

Available widgets and their names

Adjusting metadata of the widgets

Number nTest "Test Number Item" {
	stateDescription=""[
		pattern="%d%%",
		min="0",
		max="100",
		step="1",
		options="1=Red, 2=Green, 3=Blue"
	],
	widget="oh-slider-card",
	listWidget="oh-slider-item"[
		title="My title",
		subtitle="My subtitle",
		icon="oh:water"
	],
	cellWidget="oh-slider-cell"
}

General

You can use the UI to work out what the main metadata namespace is. For example, selecting Auto-Update from the list presents a page with this title:

image

Therefore autoupdate is the namespace to use:

Number nTest "Test Number Item" {
	stateDescription=""[
		pattern="%d%%",
		min="0",
		max="100",
		step="1",
		options="1=Red, 2=Green, 3=Blue"
	],
	widget="oh-slider-card",
	listWidget="oh-slider-item"[
		title="My title",
		subtitle="My subtitle",
		icon="oh:water"
	],
	cellWidget="oh-slider-cell",
	autoupdate="false"	
}

You can then use the code tab to work out what the extra metadata options are. For example, to expand the Default List Item Widget click on it and start entering nonsense data in to the fields:

Then move to the code tab:

value: oh-slider-item
config:
  icon: oh:water
  title: My title
  subtitle: My subtitle
  min: 5
  max: 20
  step: 2
  vertical: 0
  label: true
  scale: true
  scaleSteps: 2
  scaleSubSteps: 5
  unit: DEG

Which would translate to:

Number nTest "Test Number Item" {
	stateDescription=""[
		pattern="%d%%",
		min="0",
		max="100",
		step="1",
		options="1=Red, 2=Green, 3=Blue"
	],
	widget="oh-slider-card",
	listWidget="oh-slider-item"[
		title="My title",
		subtitle="My subtitle",
		icon="oh:water",
		min=5,
		max=20,
		step=2,
		vertical=0,
		label=true,
		scale=true,
		scaleSteps=2,
		scaleSubSteps=5,
		unit="DEG"
	],
	cellWidget="oh-slider-cell",
	autoupdate="false"	
}
21 Likes

thanks that really helped me a lot configuring my group-items default-widgets!

Thanks, your post came exactly to the right time. I’m migrating to OH3 at the moment. If I only put pattern in metadata, everything works without an error.
But, when I add min, max and step I get this warning:

2021-01-07 12:45:14.537 [WARN ] [dataStateDescriptionFragmentProvider] - Unable to parse the stateDescription from metadata for item OG_Li_Schlafen_Spots_BWM_Tnach, ignoring it

The item-configuration looks like this:

Number			OG_Li_Schlafen_Spots_BWM_Tnach			"Schlafen Spots Tnach [%.1f min]"	<time>			(gOG_Schlafen_Spots)			["Setpoint"]			{channel="simatic:generic_device:S7-1500:OgSchlaf:OG_Li_Schlafen_Spots_BWM_Tnach", stateDescription=""[pattern="%.1f min", min="0", max="30", step="1"]}

Though this warning appears, in UI the metadaty is shown correctly. Do I have a mistake in my config, or could I just ignore the warning?

Same here. WARN is gone if min max and step is deleted.

@the_elk @Wikibear can you show the exact configuration which gives these warnings?


I mean your configuration from your *.items file…

Don’t have one. It’s created OH3 item only.

OK, but this entire topic is about metadata in configuration files! Either way, interesting that you get the WARN on a UI configured Item too.

2021-01-11 11:10:51.964 [WARN ] [dataStateDescriptionFragmentProvider] - Unable to parse the stateDescription from metadata for item WZHeizung, ignoring it
2021-01-11 11:10:51.991 [WARN ] [dataStateDescriptionFragmentProvider] - Unable to parse the stateDescription from metadata for item WZHeizung, ignoring it
2021-01-11 11:10:51.998 [INFO ] [.openhab.core.model.script.WZHeizung] - Neuer Wert 21.0
2021-01-11 11:11:22.980 [WARN ] [dataStateDescriptionFragmentProvider] - Unable to parse the stateDescription from metadata for item WZHeizung, ignoring it
2021-01-11 11:11:22.985 [WARN ] [dataStateDescriptionFragmentProvider] - Unable to parse the stateDescription from metadata for item WZHeizung, ignoring it
2021-01-11 11:11:22.990 [WARN ] [dataStateDescriptionFragmentProvider] - Unable to parse the stateDescription from metadata for item WZHeizung, ignoring it

I trapped into a pit fall… Via Sitemaps Editor you must use half steps with comma, but in item state it seems you must use point. That is silly…

…but if you try this(using “half-steps”:

Number:Temperature radiator_valve_02_Set "Solltemperatur York [%.1f %unit%]" <heating1> (gRFritz_02,gRtSoll) ["Setpoint","Temperature","Property_Temperature"]  { channel="avmfritz:Comet_DECT:192_168_178_1:119600949320:set_temp", widget="oh-stepper-card" [step=0.5, min=6, max=24], listWidget="oh-stepper-item" [step=0.5, min=6, max=24] }

and using the developer tool “Add Items from Textual Definition”, you will get an error:

but if one sets the “half-steps” in quotes, it will be accepted, …weird…

Is that only for ‘half’ steps (<1), or all steps? My thermostat can only handle integers, so never tried…!

…seems to be for every decimal/float.

But another question. How can I use the “options”-parameter, or what does it stands for ???

I use it in my example with the number Item. It means that by default (!), in the auto-generated UI (Location, Equipment…) the Item will show as a selection list. Choosing from that selection list (Red, Green or Blue) will send (command) the corresponding number to that Item (1, 2 or 3 respectively).

I see it as the new way of using mappings= from Sitemap files…

1 Like

The warning also appears at full steps, my configuration with warning is:

Number			OG_Li_Schlafen_Spots_BWM_Tnach			"Schlafen Spots Tnach [%.1f min]"	<time>			(gOG_Schlafen_Spots)			["Setpoint"]			{channel="simatic:generic_device:S7-1500:OgSchlaf:OG_Li_Schlafen_Spots_BWM_Tnach", stateDescription=""[pattern="%.1f min", min="0", max="30", step="1"]}

If I don’t define “min, max and step” I get no warning. The configuration then looks like this:

Number			OG_Li_Schlafen_Spots_BWM_Tnach			"Schlafen Spots Tnach [%.1f min]"	<time>			(gOG_Schlafen_Spots)			["Setpoint"]			{channel="simatic:generic_device:S7-1500:OgSchlaf:OG_Li_Schlafen_Spots_BWM_Tnach", stateDescription=""[pattern="%.1f min"]}

Hi Elk,
I think you are merging two different options. First one is the Formatter/Pattern and the second is the new card-option.

Number			OG_Li_Schlafen_Spots_BWM_Tnach			"Schlafen Spots Tnach [%.1f min]"	<time>			(gOG_Schlafen_Spots)			["Setpoint"]			{channel="simatic:generic_device:S7-1500:OgSchlaf:OG_Li_Schlafen_Spots_BWM_Tnach", stateDescription=""[pattern="%.1f min"], listWidget="oh-stepper-item" [step="0.5", min=6, max=24], widget="oh-stepper-card" [step="0.5", min=6, max=24]}

Btw: you can also use the pattern only in item-description (I think there was a change)

Hi fibu-freak,
I did it just like the example above. Or did i miss something?
Thanks for your suggestion, I will test it an tell you the result. But it will take some time, because I have other issues with my installation at the moment, which I have to fix first.

Is there possibility to add “nested” metadata in text configs?
For example item

  "metadata": {
    "listWidget": {
      "value": "oh-label-item",
      "config": {
        "action": "popup",
        "actionModal": "widget:test_widget",
      }
    }
  },
  "type": "Switch",
  "name": "TestItem",
  "label": "Test item",
  "category": "switch",
  "tags": [
    "Equipment"
  ],
}

can be described as

Switch TestItem "Test item" <switch> ["Equipment"] {listWidget="oh-label-item" [action="popup", actionModal="widget:test_widget"]}

But I need to add props to custom widget

  "metadata": {
    "listWidget": {
      "value": "oh-label-item",
      "config": {
        "action": "popup",
        "actionModal": "widget:test_widget",
        "actionModalConfig": {
          "widgetProp": "value"
        }
      }
    }
  }
}

How to add this part “actionModalConfig”: { “widgetProp”: “value”}" in .items file?

Yeah, this question has popped up a few times now in this forum, but no-one seems to know the answer. @ysc apologies for the ping but are you aware of this question, and have any guidance?