Proposal to suggest file syntax for things and items to users

[lolodomo]

I would like to add a new feature that would be, I believe, very useful for users (at least those interested by having their things/items defined in config files. The idea is to have in Main UI showing the suggested config file syntax for any thing/item.

What I propose is to add in core framework the following REST endpoints:

• /inbox/{thingUID}/suggestedfilesyntax (GET) : Get suggested file syntax for a discovered thing
• /things/{thingUID}/suggestedfilesyntax (GET) : Get suggested file syntax for a thing and the items to be linked to its channels
• /items/{itemname}/suggestedfilesyntax (GET) : Get suggested file syntax for an item

I will also extend console commands to provide the same features.

In Main UI, several options are possible but here is what I imagine as the easiest:

• In the inbox, add a new action named "Suggest file syntax" on each discovered thing. This will open a pop-up and show the result of the REST API call.
• In the thing page, add a new action link named "Suggest file syntax" at the same level as the existing link named "Copy Thing". This will open a pop-up and show the result of the REST API call. Alternative: could be a new block in the page so that there is no need to click and no need of pop-up.
• In the item page, add a new action link named "Suggest file syntax" at the same level as the existing link named "Copy Item". This will open a pop-up and show the result of the REST API call. Alternative: could be a new block in the page so that there is no need to click and no need of pop-up.

WDYT ?
@florian-h05 in particular for the feedback regarding Main UI/

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/ideas-and-discussion-what-features-do-you-want-in-openhab-5-0/160573/395

[J-N-K]

But why? If you want to use discovery, why would you chose file based config?

If the proposed syntax can't be autogenerated from the model I would vote against that feature - there is a high risk of forgetting the correct adjustments when the model is updated.

[lolodomo]

But why? If you want to use discovery, why would you chose file based config?

Discovery is useful to get values of thing parameters you cannot guess (like for example the node id for a Matter node).
Then using managed things or unmanaged things is another point, just a user choice.

If the proposed syntax can't be autogenerated from the model I would vote against that feature - there is a high risk of forgetting the correct adjustments when the model is updated.

As you know this is very complex (to not say impossible) to implement, this "requirement" looks to me like an argument just to make no progress in this direction while at the same time the file syntax for things and items is very stable over the recent years and a specific generation would be relatively easy to implement.

Rejecting the change just because it is not technically absolutely the perfect solution is a pity while at the same time it could be so helpful for a massive number of users.

But Ok I will not insist more.

[lolodomo]

That's being said, I will check if I can build the model to generate the test result.

[rkoshak]

Personally, I'd rather see a convergence between the syntax shown in MainUI and the text configs. This feels like a work around for the fact that both have very different formatting and syntax.

If what you saw in the code tab in MainUI was the same as what you would use in a .things file (or whatever that becomes) this wouldn't be needed. Moving between managed and file based configs would be very straight forward.

[seime]

@lolodomo great suggestion! I welcome this!

Discovery is useful to get values of thing parameters you cannot guess

Another surprising case I've found is that some things use undocumented properties, even as the representation property! This leads to inboxes with things that aren't matched with the corresponding file based thing configuration. Making these properties visible to users of file based configuration is crucial, preferably through corrected documentation.

In the inbox, add a new action named "Suggest file syntax" on each discovered thing.

A similar feature (UI only) was PRed by me a week ago; openhab/openhab-webui#2920

Looks like this

[lolodomo]

Personally, I'd rather see a convergence between the syntax shown in MainUI and the text configs.

This is a different story. You know how this story ended the last time so I doubt there will be someone else motivated to make a new try before 5.0 is released.
By the way, what I propose will always be necessary and helpful for users even if one day we change the file format because I assume it is clear for everybody that JSON will never be the choice for config file (not user friendly at all).
My proposal is to add the REST API and the UI stuff and behind the scene of course base it on the current file format we have. If one day, the file format change, all this will already be there and this will require absolutely no change in UI.

[lolodomo]

In the inbox, add a new action named "Suggest file syntax" on each discovered thing.

A similar feature (UI only) was PRed by me a week ago; openhab/openhab-webui#2920

This is similar to what I have in mind for inbox but we need an API that the UI will call to retrieve the generated code from the server. This is what I propose.
Having a way to easily copy the content in the clipboard would be also very cool.

[lolodomo]

I updated my initial proposal to simplify the UI part. The UI part is I assume trivial to implement by @openhab/webui-maintainers when you see what they are able to do. Probably just few minutes of work for them.

Here is the update:

New REST endpoints:

• /inbox/{thingUID}/suggestedfilesyntax (GET) : Get suggested file syntax for a discovered thing
• /things/{thingUID}/suggestedfilesyntax (GET) : Get suggested file syntax for a thing and the items to be linked to its channels
• /items/{itemname}/suggestedfilesyntax (GET) : Get suggested file syntax for an item

In Main UI, several options are possible but here is what I imagine as the easiest:

• In the inbox, add a new action named "Suggest file syntax" on each discovered thing. This will open a pop-up and show the result of the REST API call.
• In the thing page, add a new action link named "Suggest file syntax" at the same level as the existing link named "Copy Thing". This will open a pop-up and show the result of the REST API call. Alternative: could be a new block in the page so that there is no need to click and no need of pop-up.
• In the item page, add a new action link named "Suggest file syntax" at the same level as the existing link named "Copy Item". This will open a pop-up and show the result of the REST API call. Alternative: could be a new block in the page so that there is no need to click and no need of pop-up.

[ghys]

Funny thing is very early versions in the UI had a feature I tried to make where you could retrofit a managed Thing into a .things file entry:
https://github.com/ghys/openhab-ui-f7/blob/master/src/pages/settings/things/thing-textual-definition.js

I abandoned the idea because it was buggy and unreliable, and couldn't work with client-side code only for inbox entries (you had to add it is a real Thing first) so wasn't worth the maintenance burden.

Great place to again plug my pipe dream to have a YAML-based declarative object management system à la Kubernetes which would let you organize your configuration by functional domain (i.e. multi-object YAML files and/or folders) rather than by object types.
You could also mix different kinds of objects in a functional "package" - Things, Items, Rules/Scripts (templates & instances), UI components incl. widgets & sitemaps etc.
They could be "templatized" and therefore redistributable e.g. through the Marketplace and the objects would all be managed (you would "apply" your configuration unit to your system).
And I'm with @rkoshak on the must-have that you should be able to adjust configuration in the UI then save it back to your YAML file by just copying-pasting the Code tab at the appropriate place.

I think it could be a perfect major feature to accompany a major release 🙂 (but again, probably a pipe dream)

[lolodomo]

Please guys, you have #3666 to discuss YAML in case you want to reopen the discussion and find someone to implement it.

We are not discussing here what should be the new file format but how we can help users by generating the file code and show it to them as suggestion. Of course, this would be the current file syntax but if one day the file syntax is changed to a new format this will become this new file format.

[florian-h05]

I updated my initial proposal to simplify the UI part. The UI part is I assume trivial to implement by @openhab/webui-maintainers when you see what they are able to do. Probably just few minutes of work for them.

Your proposal for the UI sounds good and should be straightforward to implement 👍

[lolodomo]

I can include a file format parameter in the API and implement the file generator in a service so that adding a new file format in the future (YAML for example) could simply consist in implementing a new class (service).

[lolodomo]

I made very good progress and already made a POC with things and items. It is finally possible to build the DSL model from a Thing or Item object and then just request the saving of the built model to retrieve the original syntax we are looking for.

I will create a WIP PR very soon after Christmas to show how it is simply done and also to show that any new format could be added later just by implementing an additional service. The API provides a "format" parameter to select the output format which is currently "DSL" by default.

I find all this just so amazing that I regret not having done it earlier. This would be a great feature for OH5 in the sense that it would help so many users.

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/ideas-and-discussion-what-features-do-you-want-in-openhab-5-0/160573/435

[lolodomo]

@florian-h05 @jimtng : the core PR is almost finished, I am doing last improvements.

For UI integration, I saw @jimtng proposal to copy the generated syntax into clipboard instead of displaying it in UI. Why not, that is not a bad idea. Is there a size limit for the clipboard?

In addition to an entry for individual item, thing and inbox entry, I would like an input for exporting all items and an input for a exporting all things. It could be added at the same place where we can import items file.

[lolodomo]

Closed by error.

I also saw the idea to generate items for all channels of a thing. This is something that I can add, the biggest difficulty is to find a name for items and names that do not yet exist. I could use same pattern as Main UI. What is Main UI pattern for mew item to link to a channel?

[kaikreuzer]

FWIW: You can count me as a big fan of this feature, @lolodomo!

[lolodomo]

@kaikreuzer: fantastic news, I should have my core PR ready for review at the end of the coming weekend.

[spacemanspiff2007]

One tiny detail:
In your screenshot the icon, group and tag delimiters are all spaced before the value.
If you look at the docs there are consistently no spaces around the delimiters but always after a comma.

Would it be possible to align the response accordingly?
e.g.
<switch> instead of < switch >
(DemoSwitchGroup) instead of ( DemoSwitchGroup )
[Control, Light] instead of [ Control , Light ]

The same for things where there is no space around the parameter equality sign in the docs
e.g.
[ interval="300", geolocation="49...." ] instead of [ interval = "300" , geolocation = "49...." ]

[lolodomo]

All this is already done in the current PR except space kept inside [ ] at beginning and end. I could very easily do it but the easy way will also apply to config parameters lists and I have a preference with the space at beginning and end of the list in this case.

I will show how it currently looks like
with new screen captures.

[lolodomo]

But ok, I will remove first and last spaces in [ ... ]

[lolodomo]

Note that this enhancement could also become THE solution for users to migrate very easily, at least for items and things, from one config file format to another, the day we decide to introduce a new format. The new format should just provide a syntax generator, this is just a class of less than 175 specific lines of code for items (same for things) in the case of DSL format. Then from Main UI, users could simply request the generation of syntax in this new format for all their existing items/things.