Binding state descriptions break profiles

[rkoshak]

I hesitate to bring this up here but I think it's a big enough issue to warrant the AC's attention.

Consider the following scenario (I'm going to pick on the Zwave binding but this is not limited to Zwave by any means).

• I have a Zwave door sensor device with a Channel that is linked to a Contact item.
• When I link that channel to any Item, the binding "injects" State Description mapping options so when the Item is displayed is uses "Closed" and "Open" instead of "CLOSED", and "OPEN".

So far, so good. The end user has less work to do to get something that looks nice on the UI.

However, what if I want to link this Channel to a DateTime Item using one of the Timestamp profiles (this applies to any profile that can change the type of the item from the type defined by the channel like transform or hysteresis)?

This is where it breaks. The options injected by the binding are not compatible with a DateTime Item. There is no way one can define their own State Description to override the stuff injected by the binding meaning the user loses all ability to control how the Item appears on the UI. The only way to avoid the problem and regain the ability to specify one's own state description for that DateTime Item is to drop use of the profile and use a rule.

I believe, as shown in issue openhab/openhab-core#2037 the problem is even more severe for the hysteresis profile which completely breaks. (Look at the many forum threads linked to that issue too for more cases and more problems caused but the current behavior).

While I'm not the biggest fan of profiles, binding authors should not be able to completely break them. Furthermore, binding authors should not be able to inject display metadata that cannot be overridden by the end users. Ultimately the end user should have final say in how their Item appears.

I think this issue rises to the AC level because:

• State Description is used in more places than the UIs so any change will likely ripple across multiple repos.
• This could potential impact multiple binding authors.
• I think it's definitely going to impact core since that's where the profiles are implemented.

I don't know the code well enough to offer a solution but I would like to see profiles not to be broken and control over how items are displayed on any UI fully in control of the end users, not the binding authors. But that doesn't mean I think the bindings should not be able to offer state description info, just that what is offered by the binding should be overridable by the end user.

If I'm wrong and this is a much narrower problem than it appears, I would ask that attention be paid to the issue linked above because it's much larger than just the hysteresis profile.

Thanks!

[kaikreuzer]

Hi Rich, happy New Year and sorry for the late reply!

My first reaction to the described problem is that this looks like a bug to me. state descriptions that are provided by a binding are clearly tied the item type of the channel itself. If the user links a different type of item (such as DateTime in your example) through a profile, the state description should not be applied at all.

As per the possibility to overwrite what a binding suggests, the standard mechanism since old 1.x times is still to use a custom transformation, e.g. with MAP as it is still done in our demo files for OPEN/CLOSED states of contacts.

If we'd thus change the core to not provide the binding state description, if an incompatible profile is used: Would that fully address your concerns or is there something I'm still missing?

[rkoshak]

Happy New Year.

If the user links a different type of item (such as DateTime in your example) through a profile, the state description should not be applied at all.

That would be the behavior I would expect. But that would only solve part of the problem.

As per the possibility to overwrite what a binding suggests, the standard mechanism since old 1.x times is still to use a custom transformation

I'm not certain that actually works in MainUI. There, the "label" part of the Item is replaced with the State Description. And based on what I've seen reported (I need to set up a test myself) using a transformation there won't work since it will be ignored and the binding's will take precedence. However, I'm not sure that's been tried with a compatible Item to the Channel yet. It might just be a problem when the Item is different from the type expected by the Channel in which case the proposal should work.

I'll come back after I test that out.

[kaikreuzer]

It might be that the Main UI does not fully support these concepts of using transformations to define (and overwrite) the representation of a state. That's probably something @ghys knows best.

[ghys]

Apologies for not picking this up earlier.

Unless I missing something I introduced the stateDescription and commandDescription metadata namespaces (2 years ago already, wow!) in openhab/openhab-core#1362 which would be good candidates to address (or at least provide a good workaround to) this problem.
So if you're using a profile that expects another item type than the one expected from the channel/channel type you still have the option to override things using these. Whether you can "unset" state or command descriptions that don't apply to the different item type mandated by the profile remains to be seen.
I'm not sure how to address this. Maybe @rkoshak you could play with these metadata namespaces (you can set them in the UI) and report what you think is missing?

[rkoshak]

OK, I'm back and someone on the forum beat me to creating an experiment to verify the behavior myself.

First, as shown the thread from before the binding injected State Description stuff essentially breaks the State Description metadata for Items that do no match the original Item type. I think the proposed solution would work there.

In this thread: https://community.openhab.org/t/solved-transformation-issues-map/131216 I've gathered more info when it comes to the case where the Item type isn't changed.

It appears that the Options provided by the binding will override the Pattern, even if one uses a MAP transform in the Pattern. In short, supplying MAP(contacts.map):%s as the pattern will do nothing. The Options provided by the binding will still apply. It's not until the user supplies their own Options (in this case I had the user copy the contents of their contact.map as the Options in UI) the desired result occurs.

It is surprising and confusing to users when "hidden" State Description settings seem to override their own configs. So even though the hidden settings can be overridden, it's not at all clear when and how that needs to be done.

So if you're using a profile that expects another item type than the one expected from the channel/channel type you still have the option to override things using these.

One of my concerns is how does the user know they would need to do this? Right now it's not until it appears that their settings in State Description are not working. Is there any way to populate the UI with what the binding is providing? I think that will go a long way towards helping users identify when the binding is doing something and when the binding has injected their own. The binding supplied metadata appears to be in the JSON returned by the API Explorer so should be available.

you still have the option to override things using these.

I don't know anything about commandDescription but the Items we've been dealing with are updated, not commanded so would that still apply?

If stateDescription corresponds to the "Add Metadata" -> "State Description" form in MainUI for an Item, then overriding it there does not work. For example, if I've a Contact Channel that is providing Options linked to a DateTime Item with the timestamp profile, no matter what I do (i.e. supply a Pattern, supply my own Options, try to override the Options with a blank) the Pattern supplied by the user will not be used.

So, to summarize:

Case 1: Item type is different from Channel type

• no changes to the State Description metadata through MainUI will take effect as long as the binding supplied Options (and those Options are not valid for the Item type)
• the binding supplied Options cannot be "unset" by adding a blank or empty string (on the code tab) rendering the user supplied Pattern ignored
• unlinking the Item from the Channel will cause the user supplied Pattern to be used

I'm not sure I understand the Hysteresis issue fully, but there are problems here for the Profiles too, not just in MainUI.

Case 2: The Item type matches the Channel type so the State Description stuff supplied is valid
In this case the user can override the binding supplied State Description. But it is not at all obvious when/why to do so.

• If Options are provided by the binding, it appears that the user supplied State Description Pattern is ignored.
• The Options can be overridden with user supplied Options.

Is there any more information or experiments I can run to shed more light on this? It seems to be two separate issues, which might have two separate solutions.

[rkoshak]

It's been a long time with no replies. Should we consider this one closed?

[kaikreuzer]

Yeah, I think the complexity of the issue let us leaving it behind and not following up, sorry.
I would leave it to you to decide if you'd want to revive the discussion here. My feeling is that it might after further analysis rather turn out to be a few bug reports for the core as I do not really think that there is any dispute on how it should be, but rather some uncertainty on how things exactly work right now and why.