Creating Command Options for Items via REST API

Setup, Configuration and Use Items & Sitemaps
1

Hi,

I’m developing a Python tool that automatically creates Things, Channels, and Items from an XML file using the openHAB REST API.

For some String Items (e.g., fan speed), I want the official openHAB UI/mobile app to show predefined selectable commands such as Off, Speed 1, Speed 2, and Speed 3.

I tried creating commandDescription via:

PUT /rest/items/{item}/metadata/commandDescription

but it always returns HTTP 400, while other metadata can be created successfully.

Is it possible to create Command Options (CommandDescription) programmatically through the REST API? If not, what is the recommended way to provide predefined command options for an Item automatically?

Raspberry Pi 3 / openHAB 5.0.1 / openjdk version “21.0.11” /

2

It should in principle work to define options I would think, but I’ve never tried doing it. Do you have an example of a document that you try to submit to the REST endpoint that fails?

There could be a bug, but as far as I know, the UI creates option values if you define them for e.g. widgets, so I think there should be a way.

3

If you look at the result json from an /items/{itemname} call, you can see that there’s a commandDescription property of the item itself. You need to populate that as part of the item creation or update.

4

I think it should be possible through widgets, but I wanted to try using the REST API because I noticed that commandOptions appears in the API Explorer schema.

I also saw the endpoint:

PUT /items/{itemname}/metadata/{namespace}

(“Adds metadata to an item.”)

So I tried to create commandDescription as item metadata, but it always returns HTTP 400.

Using the following request:

curl -i -X PUT "http://localhost:8080/rest/items/WaterCooler1_fan/metadata/test" 
-H "Authorization: Bearer oh.xmltoken.XXX" 
-H "Content-Type: application/json" 
-d '{
"value":"hello",
"config":{
"a":"1"
}
}'

HTTP/1.1 201 Created

The metadata with the namespace test was created successfully.

However, using:



curl -i -X PUT "``http://localhost:8080/rest/items/WaterCooler1_fan/metadata/commandDescription``" 
-H "Authorization: Bearer oh.xmltoken.XXX" 
-H "Content-Type: application/json" 
-d '{
"value":"",
"config":{
"commandOptions":[
{
"command":"off",
"label":"Off"
}
]
}
}'

HTTP/1.1 400 Bad Request

The request fails, and no commandDescription metadata is created.

5

Widgets are also created via the REST API.

Have you considered that perhaps the requests are bad? Try to make them via the API Explorer. It will output the curl call as well.

6

There are some metadata namespaces that are not writable because they are created by the system from other data. All the semantic metadata is the most prominent example. The information in that is not set by the user directly but instead updated when the user changes a semantic tag or group membership. I believe commandDescription is similar. The item property is the source of truth and the metadata is only updated from that. So, you must use the item endpoint I indicated above; the metadata endpoint will not work.

7

Thanks for your replies.
My use case is specifically Sitemaps. I need the command options to be available there because the openHAB mobile app is configured to use the native Sitemap UI. Layout pages and widgets are rendered through the Main UI, which doesn’t fit my use case, and custom widgets cannot be used in Sitemaps. Therefore I’m looking for a REST API solution that works with Sitemaps.

I should also add some context about my use case.

I have an XML file that contains the configuration of my devices. I wrote a Python script that reads this XML file and automatically creates the corresponding Things, Items, Channels, and Links using the openHAB REST API.

My goal is to generate a Sitemap from this information so that it can be used in the openHAB mobile app, which uses the native Sitemap UI.

Ideally, I would like to create the Sitemap entirely through the REST API. If that is not possible, my fallback plan is to have my Python script generate the Sitemap definition automatically, and then import or create the Sitemap through the UI instead of writing it manually.

Is this workflow supported? If so, what is the recommended approach?

8

You can set commentDescription metadata through the REST API, Main UI supports this and I tested it a few seconds ago.
And Main UI does use the REST API.

Something must be wrong with your request.

9

Thank you for your testing. I’ll check it again.

10

I finally figured out the correct format for commandDescription metadata through trial and error. Is there any documentation that explains metadata formats like this? I’d like to know where these metadata structures are documented.

11

They aren’t really documented in any detail, but if you look in the Java code and find the DTO objects, they are what defines how the format looks. But, you must “understand” how the DTO looks once it has been serialized to JSON to have much use of this.

If you look in the API Explorer, there will be example structures for all the endpoints. These will mostly show you what you need to know, but can’t really be called “documentation” either.

12

Thank you very much.