From 18092b6056b78e3b18afecf6f4065a426af5fa40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=B8=D0=BB=D1=8F=D0=BD=20=D0=9F=D0=B0=D0=BB=D0=B0?= =?UTF-8?q?=D1=83=D0=B7=D0=BE=D0=B2?= Date: Mon, 6 Oct 2025 18:27:48 +0300 Subject: [PATCH] jsr223: Describe parameter of SimpleRule.execute(Map inputs) based on trigger --- configuration/jsr223.md | 135 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 126 insertions(+), 9 deletions(-) diff --git a/configuration/jsr223.md b/configuration/jsr223.md index cdbf9a99b1..9dbc4c2977 100644 --- a/configuration/jsr223.md +++ b/configuration/jsr223.md @@ -541,13 +541,77 @@ The following trigger types are defined by openHAB (custom triggers can also be All parameters are Strings. Read the JSR223 language specific documentation for examples of using these `TriggerType` objects. +When a trigger is fired, it produces data, which is passed to the ActionHandler. +Below the `inputs` parameter contains the data from the fired trigger: + +:::: tabs + +::: tab Groovy + +```groovy +import org.openhab.core.config.core.Configuration +import org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleRule +import org.openhab.core.automation.* +scriptExtension.importPreset("RuleSupport") + +automationManager.addRule(new SimpleRule() { + @Override + Object execute(Action module, Map inputs) { + // inputs is ... described below + } + + List triggers = [ + TriggerBuilder.create().withId("trig1").withTypeUID("core.ItemStateChangeTrigger") + .withConfiguration(new Configuration([itemName: "r"])).build(), + TriggerBuilder.create().withId("cr2").withTypeUID("timer.GenericCronTrigger") + .withConfiguration(new Configuration([cronExpression: "* * * 25 * *"])).build() + ] +}) +``` + +::: + +::: tab JS Nashorn + +```js +se.importPreset("RuleSupport") +se.importPreset("RuleSimple") + +automationManager.addRule(new SimpleRule() { + execute: function(module, inputs) { + // inputs is ... described below + }, + getTriggers: function() { return [ + TriggerBuilder.create().withId("trig1").withTypeUID("core.ItemStateChangeTrigger") + .withConfiguration(new Configuration({itemName: "r"})).build(), + TriggerBuilder.create().withId("cr2").withTypeUID("timer.GenericCronTrigger") + .withConfiguration(new Configuration({cronExpression: "* * * 25 * *"})).build() + ] } +}) +``` + +::: + +:::: + +When `trig1` fires, inputs.get("module") is `"trig1"`. +The table below `core.ItemStateChangeTrigger` shows that five keys and values will be inserted into `inputs`. +The values are inserted twice: once with the trigger id prefix followed by dot in the key, once without. +That is, `inputs` will have eleven keys and six values: `inputs.get("module")`, `inputs.get("oldState") == inputs.get("trig1.oldState")`, `inputs.get("newState") == inputs.get("trig1.newState")`, `inputs.get("lastStateUpdate") == inputs.get("trig1.lastStateUpdate")`, `inputs.get("lastStateChange") == inputs.get("trig1.lastStateChange")` and `inputs.get("event") == inputs.get("trig1.event")`. + ::: details timer.DateTimeTrigger -| Parameter | Description | -|------------|---------------------------------------------------------------------------| -| `itemName` | The name of the `Item` | -| `timeOnly` | Whether only the time of the item should be compared or the date and time | -| `offset` | The offset in seconds to add to the time of the item | +| Parameter | Description | +|------------|-------------------------------------------------------------------------------------------------| +| `itemName` | The name of the `Item` | +| `timeOnly` | Whether only the time of the item should be compared or the date and time. Default is `false`. | +| `offset` | The offset in seconds to add to the time of the item | + +Data provided by the trigger: + +| Key | Description | +| ------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `event` | [`org.openhab.core.automation.events.TimerEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/events/timerevent) | ::: @@ -557,6 +621,12 @@ Read the JSR223 language specific documentation for examples of using these `Tri |------------------|---------------------| | `cronExpression` | The cron expression | +Data provided by the trigger: + +| Key | Description | +| ------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `event` | [`org.openhab.core.automation.events.TimerEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/events/timerevent) | + ::: ::: details timer.TimeOfDayTrigger @@ -565,14 +635,27 @@ Read the JSR223 language specific documentation for examples of using these `Tri |-----------|----------------------------| | `time` | The time in "hh:mm" format | +Data provided by the trigger: + +| Key | Description | +| ------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `event` | [`org.openhab.core.automation.events.TimerEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/events/timerevent) | + ::: ::: details core.ItemCommandTrigger -| Parameter | Description | -|------------|--------------------------| -| `itemName` | The name of the `Item` | -| `command` | The `Command` (optional) | +| Parameter | Description | +|------------|-----------------------------------------------------------------------------------| +| `itemName` | The name of the `Item` | +| `command` | When present, the trigger is fired only when the received command has this value. | + +Data provided by the trigger: + +| Key | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `event` | [`org.openhab.core.items.events.ItemCommandEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/items/events/itemcommandevent) | +| `command` | The received command. The value’s type of this key depends on item’s type and cannot be `UnDefType`, e.g. for a `StringItem` the type of `command` is `StringType`, and for `SwitchItem` type is `OnOffType`. | ::: @@ -583,6 +666,14 @@ Read the JSR223 language specific documentation for examples of using these `Tri | `itemName` | The name of the `Item` | | `state` | The `State` (optional) | +Data provided by the trigger: + +| Key | Description | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `state` | The item [`org.openhab.core.types.State`](https://www.openhab.org/javadoc/latest/org/openhab/core/types/state) | +| `event` | [`org.openhab.core.items.events.ItemStateUpdatedEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/items/events/itemstateupdatedevent) | +| `lastStateUpdate` | The time of the previous state update [`java.time.ZonedDateTime`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/ZonedDateTime.html) - since openHAB 5.0. The value is `null`, when the item was just initialized. | + ::: ::: details core.ItemStateChangeTrigger @@ -593,6 +684,16 @@ Read the JSR223 language specific documentation for examples of using these `Tri | `previousState` | The previous `State` (optional) | | `state` | The `State` (optional) | +Data provided by the trigger: + +| Key | Description | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `oldState` | The old item [`org.openhab.core.types.State`](https://www.openhab.org/javadoc/latest/org/openhab/core/types/state). The value is `UnDefType.NULL`, when the item was just initialized. | +| `newState` | The new item [`org.openhab.core.types.State`](https://www.openhab.org/javadoc/latest/org/openhab/core/types/state) | +| `lastStateUpdate` | The time of the previous state update [`java.time.ZonedDateTime`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/ZonedDateTime.html) - since openHAB 5.0. The value is `null`, when the item was just initialized. | +| `lastStateChange` | The time of the previous state change [`java.time.ZonedDateTime`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/ZonedDateTime.html) - since openHAB 5.0. The value is `null`, when the item was just initialized. | +| `event` | [`org.openhab.core.items.events.ItemStateChangedEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/items/events/itemstatechangedevent) | + ::: ::: details core.GroupCommandTrigger @@ -649,6 +750,12 @@ Read the JSR223 language specific documentation for examples of using these `Tri | `channelUID` | The `ChannelUID` of the `Channel` | | `event` | The `Channel` trigger `Event` (optional) | +Data provided by the trigger: + +| Key | Description | | +|---------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| `event` | [`org.openhab.core.thing.events.ChannelTriggeredEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/thing/events/channeltriggeredevent) | + ::: ::: details core.GenericEventTrigger @@ -669,3 +776,13 @@ Read the JSR223 language specific documentation for examples of using these `Tri | `startlevel` | The system `StartLevel` | ::: + +::: details Triggering explicitly + +When a rule is executed without a trigger, e.g. with HTTP POST on `/rest/rules/{rule-uid}/runnow/`, the data provided is: + +| Key | Description | +| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `event` | [`org.openhab.core.automation.events.ExecutionEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/events/executionevent) | + +:::