Transformations terms

I assert that there’s a need for some clarification on the terms surrounding transformations. This started as we were discussing some modifications to how the community marketplace is shown, but despite our best efforts myself and @rlkoshak have been unable to reach a consensus. I get that many things OH is a bit “ad hoc”, and that things end up the way the author that volunteers to do it, does it. That’s fine in many situations, but when it comes to “fundamental concepts” for how OH does what it does, I think some coordination and consensus is beneficial.

The concrete reason it came up now was that @rlkoshak suggested that the add-on under “Transformations” should be separated into two sub-categories instead of being presented as one mixed group like they are now. This is now:


…and this is with the suggested subcategories:

The idea is to do something similar to how “Automation” (“Languages & Technologies”, “Rule Templates” and “Block Libraries”) and “User Interfaces” (“Widgets for the Main UI” and “Other UI Add-ons”) is organized, the separate “different concepts” from each other so that it’s easier for the users to understand what they’re looking at.

We both agree on this point, where we disagree is when it comes to the names of the new categories. I argue that I’ve always found “transformations” a bit confusing, but because so many, seemingly different, things/concepts are called transformations and because of the “partial overlap” with “profiles”. So, I think it’s important that when something is done to transformations, it’s important that things get less confusing, not more.

I can’t properly argue for @rlkoshak’s standpoint, but I think he just wants to make as few changes as possible while getting the add-ons categorized.

The reason I think it’s confusing is that what is called TransformationService and Transformation in Core are both often just referred to as “transformations”.

To me that doesn’t compute, since it means that “a transformation use another transformation to transform values”. That’s at the point where I as a user, feel that there’s something essential that I’m missing. What I now understand, after studying the source code, is that a Transformation basically is “a configuration for a TransformationService that tells it how to transform the value”.

But wait, there’s more. Installed scripting languages are automatically registered as ScriptTransformationServices, which means that scripting languages in a way are “transformations” too. You can transform a value using a scripting language and a Transformation alone, but in this case the Transformation is a script, not “a mere configuration” as with the other TransformationServices.

It is what it is, and it all makes sense from a technical point of view, I’m just trying to argue why this might be confusing for users, and why I think that clear and concise terms might be beneficial.

The documentation states that:

Transformations are used to translate data from a cluttered or technical raw value to a processed or human-readable representation. They are often useful, to interpret received Item values, like sensor readings or state variables, and to translate them into a human-readable or better processable format.

That’s fine, but it’s generic and doesn’t say anything about how this is organized. The documentation further says that:

Transformations are performed by Transformation Services which are available as transformation add-ons. The relevant add-on needs to be installed via the Main UI or addons.cfg before use.

This paragraph sheds light on a bit of the inconsistency (that I claim exist). The documentation actually calls them “Transformation Services” but then go on to say that they are available (for installation) as “transformation add-ons”. Again, this doesn’t compute for me - transformations are performed by transformation services that you install as transformations…

Further down in the documentation, it states:

You can find the available transformation services here.

If you follow the link, you get to something called:

Data Transformation

Transformations are used to translate between technical and human-readable values for items.

What is actually listed under “Data Transformations” are all TransformationServices.

In MainUI, under “Settings → Transformations” you get to this screen:

So, here “transformation” actually means that it means in Core, what you see there are Transformations, not TransformationServices, and they rely on a suitable TransformationService being installed to do anything.

In short (I know short isn’t my strong side, but I’m trying), I call for a “cleanup” of the terms both in documentation, in the user interfaces and when it’s discussed on the forum. My suggestion is that the terms from Core is used, “transformation service” and “transformation”. A “script transformation” will then end up as a “transformation”, but that will have to be ok, even though it can in theory be as capable as a “transformation service”. The changes to achieve this to the documentation are pretty minimal as far as I can tell, but @rlkoshak things that this will lead to confused users that (mostly he) must guide through “the new jungle”, and he’s thus understandably hesitant.

@rlkoshak on the other hand wants to call the category for Transforations in the marketplace for “Transformation Configs” and the leave everything else as it is. I think that will add to the confusion, as it is yet another term used for something that already has a name.

To me, a very basic concept of organization is that you have exactly one term for one concept. When the user understands what this term means, he/she knows what the subject is about every time he/she comes across the term. When the same concept has multiple terms, people will assume that those are different concepts, and will end up being confused (again my claim).

So, this is the situation. The technical changes needed in MainUI are simple, and I’ve figured out how that should be done. @florian-h05 has offered to get it merged once we agree, so everything is on track to get this done, except that we can’t agree.

Instead of this stalling, I call for more participants to weigh in. It’s helpful to have these concepts separated in the community marketplace, whatever you call them, so we should be able to agree on something and then move on with the implementation.

So, please, study the situation and present your view :pray:

2 Likes

I would use ‘transform’ as the specific case here.

de.map is a transform that requires the Map Transformation Service

There is some precedent for this in various fields (although even there it is not always 100% consistent): a Fourier transform is one specific type of integral transformation.

It also, in my opinion, changes the least while still offering a distinction in cases where such precision is required.

That said, Rich’s proposal of Transformation config is a good compromise. I feel it is already consistent with (or at least hinted at by) several areas of the UI. For example the Transformation help panel:
image

Or the patterns to add Transforms to other configurations:

Tip: Use SCALE(config:scale:blinds_position):%s as pattern for Item state description metadata.

And it is consistent with the configuration terminology already widely used in other areas.

I have no problem with “configuration” itself, but the fact that you call the same things different things in different places. Why should the very same thing be called a “transformation” in one place, and a couple of clicks away, it should be called “transformation config”? And, at the same time, when is says “transformation” there, it means what is called “transformation service” in the documentation.

I think it’s all about being consistent with what is referred to, and maybe more fundamentally: What is meant by a “transformation”? I have no problem with calling this “transformation”, or using “transform” as a verb for manipulating a value by applying some logic. My problem is that one should decide what this means, is it “the act of transforming the value” or is it somehow the name of the “tool” one uses to do it.

A “transformation service”, as defined by Core, cannot transform a value alone. It just offers a “framework”/system for doing transformations. It needs to get explicit instructions about how to apply do the actual transformation to do something meaningful. This is what is called “transformation” in most places in OH, but that should now suddenly be called “transformation config”.

It’s not that I think “transformation configuration” is misleading in itself, it’s that it should then be called that everywhere. And, doing that requires many more changes than what I suggest. So, the only way to “apply minimum changes” is to be inconsistent. To be consistent, the “minimum changes” approach is to go with “transformation service” and “transformation”.