Skip to content

Commit 18092b6

Browse files
dilyanpalauzovdilyanpalauzov
committed
jsr223: Describe parameter of SimpleRule.execute(Map inputs) based on trigger
1 parent 3bc886d commit 18092b6

File tree

1 file changed

+126
-9
lines changed

1 file changed

+126
-9
lines changed

‎configuration/jsr223.md‎

Lines changed: 126 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -541,13 +541,77 @@ The following trigger types are defined by openHAB (custom triggers can also be
541541
All parameters are Strings.
542542
Read the JSR223 language specific documentation for examples of using these `TriggerType` objects.
543543

544+
When a trigger is fired, it produces data, which is passed to the ActionHandler.
545+
Below the `inputs` parameter contains the data from the fired trigger:
546+
547+
:::: tabs
548+
549+
::: tab Groovy
550+
551+
```groovy
552+
import org.openhab.core.config.core.Configuration
553+
import org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleRule
554+
import org.openhab.core.automation.*
555+
scriptExtension.importPreset("RuleSupport")
556+
557+
automationManager.addRule(new SimpleRule() {
558+
@Override
559+
Object execute(Action module, Map<String, ?> inputs) {
560+
// inputs is ... described below
561+
}
562+
563+
List<Trigger> triggers = [
564+
TriggerBuilder.create().withId("trig1").withTypeUID("core.ItemStateChangeTrigger")
565+
.withConfiguration(new Configuration([itemName: "r"])).build(),
566+
TriggerBuilder.create().withId("cr2").withTypeUID("timer.GenericCronTrigger")
567+
.withConfiguration(new Configuration([cronExpression: "* * * 25 * *"])).build()
568+
]
569+
})
570+
```
571+
572+
:::
573+
574+
::: tab JS&nbsp;Nashorn
575+
576+
```js
577+
se.importPreset("RuleSupport")
578+
se.importPreset("RuleSimple")
579+
580+
automationManager.addRule(new SimpleRule() {
581+
execute: function(module, inputs) {
582+
// inputs is ... described below
583+
},
584+
getTriggers: function() { return [
585+
TriggerBuilder.create().withId("trig1").withTypeUID("core.ItemStateChangeTrigger")
586+
.withConfiguration(new Configuration({itemName: "r"})).build(),
587+
TriggerBuilder.create().withId("cr2").withTypeUID("timer.GenericCronTrigger")
588+
.withConfiguration(new Configuration({cronExpression: "* * * 25 * *"})).build()
589+
] }
590+
})
591+
```
592+
593+
:::
594+
595+
::::
596+
597+
When `trig1` fires, inputs.get("module") is `"trig1"`.
598+
The table below `core.ItemStateChangeTrigger` shows that five keys and values will be inserted into `inputs`.
599+
The values are inserted twice: once with the trigger id prefix followed by dot in the key, once without.
600+
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")`.
601+
544602
::: details timer.DateTimeTrigger
545603

546-
| Parameter | Description |
547-
|------------|---------------------------------------------------------------------------|
548-
| `itemName` | The name of the `Item` |
549-
| `timeOnly` | Whether only the time of the item should be compared or the date and time |
550-
| `offset` | The offset in seconds to add to the time of the item |
604+
| Parameter | Description |
605+
|------------|-------------------------------------------------------------------------------------------------|
606+
| `itemName` | The name of the `Item` |
607+
| `timeOnly` | Whether only the time of the item should be compared or the date and time. Default is `false`. |
608+
| `offset` | The offset in seconds to add to the time of the item |
609+
610+
Data provided by the trigger:
611+
612+
| Key | Description |
613+
| ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
614+
| `event` | [`org.openhab.core.automation.events.TimerEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/events/timerevent) |
551615

552616
:::
553617

@@ -557,6 +621,12 @@ Read the JSR223 language specific documentation for examples of using these `Tri
557621
|------------------|---------------------|
558622
| `cronExpression` | The cron expression |
559623

624+
Data provided by the trigger:
625+
626+
| Key | Description |
627+
| ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
628+
| `event` | [`org.openhab.core.automation.events.TimerEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/events/timerevent) |
629+
560630
:::
561631

562632
::: details timer.TimeOfDayTrigger
@@ -565,14 +635,27 @@ Read the JSR223 language specific documentation for examples of using these `Tri
565635
|-----------|----------------------------|
566636
| `time` | The time in "hh:mm" format |
567637

638+
Data provided by the trigger:
639+
640+
| Key | Description |
641+
| ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
642+
| `event` | [`org.openhab.core.automation.events.TimerEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/events/timerevent) |
643+
568644
:::
569645

570646
::: details core.ItemCommandTrigger
571647

572-
| Parameter | Description |
573-
|------------|--------------------------|
574-
| `itemName` | The name of the `Item` |
575-
| `command` | The `Command` (optional) |
648+
| Parameter | Description |
649+
|------------|-----------------------------------------------------------------------------------|
650+
| `itemName` | The name of the `Item` |
651+
| `command` | When present, the trigger is fired only when the received command has this value. |
652+
653+
Data provided by the trigger:
654+
655+
| Key | Description |
656+
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
657+
| `event` | [`org.openhab.core.items.events.ItemCommandEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/items/events/itemcommandevent) |
658+
| `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`. |
576659

577660
:::
578661

@@ -583,6 +666,14 @@ Read the JSR223 language specific documentation for examples of using these `Tri
583666
| `itemName` | The name of the `Item` |
584667
| `state` | The `State` (optional) |
585668

669+
Data provided by the trigger:
670+
671+
| Key | Description |
672+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
673+
| `state` | The item [`org.openhab.core.types.State`](https://www.openhab.org/javadoc/latest/org/openhab/core/types/state) |
674+
| `event` | [`org.openhab.core.items.events.ItemStateUpdatedEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/items/events/itemstateupdatedevent) |
675+
| `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. |
676+
586677
:::
587678

588679
::: details core.ItemStateChangeTrigger
@@ -593,6 +684,16 @@ Read the JSR223 language specific documentation for examples of using these `Tri
593684
| `previousState` | The previous `State` (optional) |
594685
| `state` | The `State` (optional) |
595686

687+
Data provided by the trigger:
688+
689+
| Key | Description |
690+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
691+
| `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. |
692+
| `newState` | The new item [`org.openhab.core.types.State`](https://www.openhab.org/javadoc/latest/org/openhab/core/types/state) |
693+
| `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. |
694+
| `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. |
695+
| `event` | [`org.openhab.core.items.events.ItemStateChangedEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/items/events/itemstatechangedevent) |
696+
596697
:::
597698

598699
::: details core.GroupCommandTrigger
@@ -649,6 +750,12 @@ Read the JSR223 language specific documentation for examples of using these `Tri
649750
| `channelUID` | The `ChannelUID` of the `Channel` |
650751
| `event` | The `Channel` trigger `Event` (optional) |
651752

753+
Data provided by the trigger:
754+
755+
| Key | Description | |
756+
|---------|---------------------------------------------------------------------------------------------------------------------------------------------------|
757+
| `event` | [`org.openhab.core.thing.events.ChannelTriggeredEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/thing/events/channeltriggeredevent) |
758+
652759
:::
653760

654761
::: details core.GenericEventTrigger
@@ -669,3 +776,13 @@ Read the JSR223 language specific documentation for examples of using these `Tri
669776
| `startlevel` | The system `StartLevel` |
670777

671778
:::
779+
780+
::: details Triggering explicitly
781+
782+
When a rule is executed without a trigger, e.g. with HTTP POST on `/rest/rules/{rule-uid}/runnow/`, the data provided is:
783+
784+
| Key | Description |
785+
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
786+
| `event` | [`org.openhab.core.automation.events.ExecutionEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/events/executionevent) |
787+
788+
:::

0 commit comments

Comments
 (0)