Thing: move into core the conversions to/from YAML code done by MainUI

[lolodomo]

When we discuss about new format for configuration files, one wish would be to use a common (YAML) syntax in MainUI code tab and in the new file format. To make this dream a reality, a required initial step is to replace the conversion to/from YAML currently hardcoded in MainUI by new REST APIs in core in charge of these conversions. MainUI would then call these new APIs when needed without handling YAML conversion by itself. This would also allow to show easily another format (like our current DSL format) in the code tab just by passing the requested format to the API.

@openhab/webui-maintainers : I need your help to identify what are the APIs you need for that. I guess two APIs are necessary, one to convert to YAML and one to parse YAML.

When entering in the code tab, you need to build the YAML code from the current internal data, these data are potentially different from the thing stored in the registry because the user may have started to change configuration parameters for example. In #4569, I already added the API GET /things/{thingUID}/syntax/generate but it is based on the thing in the registry. So I believe I should add another similar API where you can pass as parameter thing data (ThingDTO) like in the API to create a new thing, and the returned output is the generated YAML code: POST /things/{thingUID}/syntax/generate

Then when leaving the code tab, you need an API to parse the YAML code potentially updated by the user and retrieve the corresponding thing data (ThingDTO). I could add a new API POST /things/{thingUID}/syntax/parse with a parameter in which you provide the YAML code and the returned output is corresponding thing data (ThingDTO).

@florian-h05 : please confirm it would be OK and sufficient for MainUI needs.

In the code tab, I can see that all channels are listed. Does it mean you support adding/removing of channels through this tab ? Or do you show them just for information ? Or just to let the user update a channel configuration parameter ?
Of course in the future config file, the user should not define all these channels while they can be deduced from the thing type. So it is a point to clarify.

[lolodomo]

If this initial step can be achieved, we can then discuss about small improvements of the syntax to make it potentially more user friendly and of course a compromise should be found.
Defining a thing does not require a lot of information, it is relatively simple. Current syntax defined by MainUI looks not so bad and I do not imagine big changes. And we should thing to users already used to the YAML syntax in MainUI code tab.
Note that these adjustments would then require no changes in MainUI as soon as MainUI is using APIs, and they will be automatically applied to what is displayed the code tab.

[lolodomo]

In the code tab, I can see that all channels are listed. Does it mean you support adding/removing of channels through this tab ? Or do you show them just for information ? Or just to let the user update a channel configuration parameter ?

The existing API to update a thing expects at input either no channels and no change of channels for the thing is done in this case, or a list of channels and the thing will then be updated to have only this list of channels. So MainUI needs to maintain a list of all channels for a thing to call the update API. That might be the reason why all channels are shown in the code tab ? I am also asking myself if the purpose is also to let user remove channels ?

That could be something preventing to have exactly the same YAML code if MainUI needs to display all existing channels while in a config file, the user would like to consider only non default channels. Even if the syntax itself remains common.

[FlorianSW]

@FlorianSW : please confirm it would be OK and sufficient for MainUI needs.

Are you sure you wanted to ping me with this? :) I did not work on MainUI or openhab things in quite a while 🙈

[lolodomo]

Are you sure you wanted to ping me with this?

No, it was a mistake, my intention was or course to ping @florian-h05

[florian-h05]

The proposed API are sufficient in general, it of course causes some network traffic but I think we can live with that.

The existing API to update a thing expects at input either no channels and no change of channels for the thing is done in this case, or a list of channels and the thing will then be updated to have only this list of channels. So MainUI needs to maintain a list of all channels for a thing to call the update API. That might be the reason why all channels are shown in the code tab ? I am also asking myself if the purpose is also to let user remove channels ?

a. I have only tried this for Things with unmodifiable channels, there it is possible to modify the channel config.
b. I would expect that for Things with modifiable channels, you can add and remove them from the code tab as well.

In both cases, having them in the code tab is a great help. I think in b, it should be easy to keep the current behaviour because you actually need to define the channels manually, a is more difficult to handle though.

[rkoshak]

MainUI would then call these new APIs when needed without handling YAML conversion by itself. This would also allow to show easily another format (like our current DSL format) in the code tab just by passing the requested format to the API.

Could it make sense to supply the mime type as part of the request instead of creating a whole new API endpoint? If the request includes "application/yaml" instead of "application/json" and it defaults to "application/json" could that work? DSL could use "application/dsl" and so on when/if new formats are developed. Then on the server side it knows what format is desired and can convert (as necessary) back and forth for new and updates to stuff.

Or is that what you are already proposing (it doesn't seem so but I could be wrong)? Or is there something about doing that which wouldn't work?

b. I would expect that for Things with modifiable channels, you can add and remove them from the code tab as well.

I can confirm this, at least when it comes to MQTT and HTTP bindings.

That might be the reason why all channels are shown in the code tab ? I am also asking myself if the purpose is also to let user remove channels ?

My understanding is it just shows the raw JSON returned by the API converted to YAML. I don't think there is any more reasoning than that. And the raw JSON returned by the API includes all the Channels, as would be required to show all the Channels in the Design tab.

To complicate a. a little more, what if I want to modify a Channel that I haven't modified before? There'd need to be a way to only show modified Channels and show all Channels and switch between the two.