Skip to content

Commit fa7dfdb

Browse files
dilyanpalauzovdilyanpalauzov
committed
jsr223: Describe parameter of SimpleRule.execute(Map inputs) based on trigger
1 parent b199256 commit fa7dfdb

File tree

1 file changed

+120
-9
lines changed

1 file changed

+120
-9
lines changed

‎configuration/jsr223.md‎

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

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

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

549613
:::
550614

@@ -554,6 +618,12 @@ Read the JSR223 language specific documentation for examples of using these `Tri
554618
|------------------|---------------------|
555619
| `cronExpression` | The cron expression |
556620

621+
Data provided by the trigger:
622+
623+
| Key | Description |
624+
| ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
625+
| `event` | [`org.openhab.core.automation.events.TimerEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/events/timerevent) |
626+
557627
:::
558628

559629
::: details timer.TimeOfDayTrigger
@@ -562,14 +632,27 @@ Read the JSR223 language specific documentation for examples of using these `Tri
562632
|-----------|----------------------------|
563633
| `time` | The time in "hh:mm" format |
564634

635+
Data provided by the trigger:
636+
637+
| Key | Description |
638+
| ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
639+
| `event` | [`org.openhab.core.automation.events.TimerEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/events/timerevent) |
640+
565641
:::
566642

567643
::: details core.ItemCommandTrigger
568644

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

574657
:::
575658

@@ -580,6 +663,14 @@ Read the JSR223 language specific documentation for examples of using these `Tri
580663
| `itemName` | The name of the `Item` |
581664
| `state` | The `State` (optional) |
582665

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

585676
::: details core.ItemStateChangeTrigger
@@ -590,6 +681,16 @@ Read the JSR223 language specific documentation for examples of using these `Tri
590681
| `previousState` | The previous `State` (optional) |
591682
| `state` | The `State` (optional) |
592683

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

595696
::: details core.GroupCommandTrigger
@@ -666,3 +767,13 @@ Read the JSR223 language specific documentation for examples of using these `Tri
666767
| `startlevel` | The system `StartLevel` |
667768

668769
:::
770+
771+
::: details Triggering explicitly
772+
773+
When a rule is triggered outside of a trigger, e.g. with HTTP POST on `/rest/rules/{rule-uid}/runnow/`, the data provided by the trigger is:
774+
775+
| Key | Description |
776+
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
777+
| `event` | [`org.openhab.core.automation.events.ExecutionEvent`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/events/executionevent) |
778+
779+
:::

0 commit comments

Comments
 (0)