Expose _getTriggeredData as a utility for managed rules

[rkoshak]

There is a difference between how the event Object appears in managed rules and file based rules. I file based rules the event Object is parsed out and converted from the original Java so it's much easier to get at all the information in the event. Managed users get the raw Java event Object.

While not necessary every time, it is sometimes desirable to access information from the payload and other parts of the event which is awkward and requires experimentation and investigation to figure out what is available and how to access it.

I could create a separate library which basically reproduces what _getTriggeredData does, but it would be better overall if managed rules users could just call that function directly or indirectly to convert their Java Object to the exact same event Object that file users see. While we can't intercept the event directly, at least we have the option to convert it ourselves on demand.

I'll be happy to submit a PR but don't won't if there is some technical or philosophical reasons I don't know which makes this a bad idea.

Your Environment

• openHAB version used (check Main UI -> About): OH 5.0 M4
• openhab-js version used (run console.log('openhab-js ' + utils.OPENHAB_JS_VERSION) from a JS script): 5.11.1
• Operating System and version (e.g. desktop or mobile, Windows 10, Raspbian Buster, ...): Official Docker running on Ubuntu 24.04

[florian-h05]

Have you tried whether _getTriggeredData works in managed rules?
(Copy it from the openhab-js code into a managed rule to try it)

IIRC I have tried this some time ago and it failed due to the input in file-based rules and the event in managed rules being different ... but I am not sure, so better test this.

[rkoshak]

IIRC I have tried this some time ago and it failed due to the input in file-based rules and the event in managed rules being different ... but I am not sure, so better test this.

I think it won't work as written for exactly that reason. However, except for the line data.raw = input; there is nothing that is extracted from input that could not also be extracted from input.get('event'); instead. So my proposal would be:

1. Rewrite _getTriggerdData to pull all the data from the event Object instead of input and change the name of the function.
2. Create a new function called by file based rules, we'll name it _getTriggeredData to minimize impacts across the library. This will call 1 with the extracted event Object instead of input, and then add input to that result before returning data. Nothing should change from file based rule's perspective.
3. Expose 1 so it can be called from managed rules with the event Object. Managed rules don't need the raw input because all that stuff outside the event Object from calling rules is already available. That line above was added because arguments passed into file based rules was not available.

I'll need to do a little bit of checking to figure out how to get at everything (e.g. triggeringGroup) but about 90% of this function I've already working code to pull the information from the event Object in a managed rule.

The first part of 2 would look something like:

function getTriggeredDataFromEvent (event) {
  const data = {};
  // Dynamically added properties, depending on their availability

  // Item triggers
  if (event.itemCommand !== undefined) data.receivedCommand = event.itemCommand.toString();
  if (event.oldItemState !== undefined) data.oldState = event.oldItemState.toString();
  if (event.itemState !== undefined) {
    data.newState = event.itemState.toString();
    data.state = event.itemState.toString();
  }
...

1 would look something like:

function _getTriggeredData(input){
  const event = input.get('event');

  const data = getTriggeredDataFromEvent(event);

  // Add input to data to passthrough any properties not captured below
  data.raw = input;

  return data;
}

It that seems acceptable I'll prepare a PR over the next few days.

Edit: It looks like triggeringGroup is not available in the event. :-(. But I can skip that and add it only in the file based function same as I did for data.raw to avoid a breaking change. It would be nice if that were there for all but I still think it's worth making this proposed changed even if managed rules users can't use it.

Edit 2: This is weird, for a managed rule even when you subscribe to a ThingStatusInfoChangedEvent event, it's a ThingStatusInfoEvent that get passed into the scripts in the event. This is important because ThingStatusInfoEvent doesn't have the getOldStatus() method which is needed to populate oldStatus. It's there in the payload when I do a generiic trigger and filter on ThingStatusChangedEvent though and all the data I need is available.

Is this maybe a bug in core?

[florian-h05]

The execute method of the ActionHandler should receive the same amount of data, what file-based JS rules process as input is put into the ctx variable of the UI-based script. Unfortunately with different key names, so openhab-js doesn't find them.
I have applied a small core tweak which allows me to use _getTriggeredData for UI-based rules, see openhab/openhab-core#4919.

[florian-h05]

Together with some enhancements to the add-on itself I have in mind, we might be able to automatically provide the pure-JS event object in UI-based rules for openHAB 5.1.0.

[rkoshak]

Excellent, so this can be closed then, right?

It will be a big improvement is all users can expect the same event object. Even if it can't be done automatically having a way to convert what we have with a function call would be an improvement.

If I understand correctly, once #4919 gets merged, ctx in managed rules and the input passed to _getTriggeredData will exactly match so we can just have the one function to call.

Of course, just having the one native JS event Object be there would be ideal.

[florian-h05]

Excellent, so this can be closed then, right?

Not yet, I need this as a reminder to work on it.

If I understand correctly, once #4919 gets merged, ctx in managed rules and the input passed to _getTriggeredData will exactly match so we can just have the one function to call.

Exactly.

[florian-h05]

With openhab/openhab-addons#19019, it should be possible to automatically convert the event object for UI-based rules as long as rules is available. I will try once all my required PRs are merged.

[florian-h05]

@rkoshak
Technically we can soon automatically convert the event data in UI-based rules, though I wonder what's the best approach. Automatically converting event from Java -> JS would be a bad idea, since the "signature" of the event object changes, e.g. event.itemState -> event.receivedState.
This would be breaking and require users to do much manual adjustment. I'd rather additionally provide the pure JS event data, though I then would need a nice name for it.

[rkoshak]

Can we split the difference and have the event Object support both? It's ugly for sure but that would mean there would be no immediate changes required for managed rules users, at least not right away.

This could be temporary, for one or two releases, perhaps with a warning in the logs when using the old properties, and then after 5.1 release we can remove the old stuff. This would have the lowest short term impact to the end users, even if it makes the helper library code ugly for a time.

The other alternative would be to call the new event something like jsevent for now but then rename it to event after 5.1 and eliminate the current Java event object or rename that to javaevent.

Ultimately the end goal should be to make it exactly the same between files and managed. That simplifies the docs and makes code posted to the forum a little more portable between the two. It should make long term maintenance easier.

I'd prefer the first option as that means I only need to make changes to my rules once. Providing a second event Object would mean two changes.

I've a question about data passed from a calling rule. Do those still get passed into the rule the same way or is it now only available through event.raw like with file based rules? This will certainly impact me and users of my rule templates if these values are not injected into the rule the same way now that everything is wrapped.

It's not a huge deal, just an impact that we need to consider.

[florian-h05]

I would opt for option 1, this allows for a better transition.

I've a question about data passed from a calling rule. Do those still get passed into the rule the same way or is it now only available through event.raw like with file based rules? This will certainly impact me and users of my rule templates if these values are not injected into the rule the same way now that everything is wrapped.

How do you access that data at the moment?

[rkoshak]

In a managed rule the passed in arguments are injected by name.

For example, given the call:

rules.runRule('myRule', { 'foo': true, 'bar': false }, true);

in a managed rule the two passed in arguments are accessed just using their name.

if(foo && !bar){

but in a file based rule they are accessed through:

if(event.raw.foo && ! event.raw.bar) {

[florian-h05]

in a managed rule the two passed in arguments are accessed just using their name.

That should still work, though event.raw.foo will also work whtn using getTriggeredDate.