Skip to content

jsr223: Describe parameter of SimpleRule.execute(Map inputs) based on trigger #2582

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

jsr223: Describe parameter of SimpleRule.execute(Map inputs) based on trigger #2582

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 126 additions & 9 deletions configuration/jsr223.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<String, ?> inputs) {
// inputs is ... described below
}

List<Trigger> 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&nbsp;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) |

:::

Expand All @@ -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
Expand All @@ -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`. |

:::

Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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) |

:::