Reactions

Reactions in Reactor can be Rule-based or Global. Rule-based Reactions are run when a Rule changes state (e.g. from reset to set or vice versa). Each Rule has two built-in Reactions: its Set reaction, and its Reset reaction. The Set reaction is run when the rule transitions from reset to set state (i.e. when its trigger conditions become met), and the Reset reaction runs when the Rule transitions from set to reset state (when the trigger conditions are no longer met).

Global Reactions are simply reactions that can be invoked by other actions; they are "subroutines" in computer parlance. They only run when called.

The following action types are available in Reactor Reactions:

• Entity Action - Run an action on a entity (e.g. turn a light on or off, change dimming level or thermostat mode, etc.);
• Script Action - Run a script (expression);
• Delay - Delay execution of subsequent actions in the Reaction;
• Run Reaction - Start another Reaction;
• Stop Reaction - Stop a running Reaction;
• Notify - Send a notification;
• Set Variable - Set a variable's value;
• HTTP Request - HTTP GET or POST request to a remove server/service;
• Shell Command - Run a shell command;
• Comment - A comment to help you document your Reaction;
• Group - Group actions to execute conditionally;
• Repeat...While - Execute actions repeatedly until a condition is met.

The Reactions Tab

The Reactions tab is where you will define and edit your global Reactions, which are Reactions that can be run by any rule (i.e. the Reaction's built-in set and reset reactions can use Run Reaction actions to run global Reactions).

Starting at the top of the screenshot the "Show Reactions" dropdown (A) lets you choose which Reactions are shown. Because there are two Reactions for each group, the list can get quite long quickly, and often only a couple of the Reactions are actually used, so this menu lets you filter the view. For example, if you choose "In Use", the view will only show Reactions that have actions in them.

Each Reaction has an action list: the list of actions it will perform. Actions are performed in the order shown in this list.

The "Save" and "Revert" buttons (B) appear in each action list header and are used to save the current Reaction configured, or revert to the last saved, respectively. The revert is the only "undo" offered, so you are encouraged to save often.

Below that are the actions. Each action has a selectable action type (C), the action parameters (D), and action controls (E). The action parameters (D) vary from action type to action type. The action controls (E) have some standard buttons and some action-specific buttons. You can see from the screenshot that every action has up- and down-arrow buttons, and an "X" button; these are "move up", "move down" and "delete", respectively. The action-specific controls are covered in the description of each action type.

At the bottom of each Reaction, below the action list, are two buttons: "Add Action" and "Copy From...". The "Add Action" button adds a new action to the end of the Reaction's action list. The "Copy From..." button presents a pop-up menu from which you can select another Reaction; the selected Reaction's actions will be imported into the current Reaction (at the end).

Special Behaviors of Rule-based Reactions

In the discussion of Rule conditions and groups, there is a callout box ("Important Concept!") that states that rules, like any condition, only have two active states: set and reset. Reactions are only run when the state of a rule changes, that is, goes from reset to set, or from set to reset. Let's use an example to illustrate why this concept is so important.

Let's say we have a rule with two trigger conditions, and it's an OR group, so either condition or both being true results in the group itself being set. We start with both conditions false, so the rule is reset. When one of the conditions goes true, the rule sets, and any actions in the Set reaction for the rule are then launched. However, if later the other condition in the rule also becomes true, the rule is already set and therefore there is no rule state change as a result (it can't be more set than it already is), so the Set reaction is not run again.

Another important concept to understand about Rule-based Reactions is that they can preempt each other. The Set and Reset reactions of a rule are contra-reactions of one another. In order to keep things from getting wildly out of hand when things are changing quickly, Reactor applies the following discipline to these contra-reactions: only one of them may be running at a time. That is, the Set reaction can only run when the Reset reaction is not, and the Reset reaction and only run when the Set reaction is not.

To enforce this, if a rule changes state, it preempts its currently running reaction (if any) so that the reaction for the new state can start immediately. That is, if the Set reaction for a rule is running, and the rule becomes reset, then that Set reaction will be stopped immediately (preempted) and the Reset reaction will be started. The reverse is also true: if a Reset reaction is running and the parent rule sets, the Reset reaction is stopped immediately and the rule's Set reaction is started.

But there is an exception: if the reaction of the new target state is empty (contains zero actions, not even a comment), the running contra-reaction will not be stopped; it is allowed to run to completion. This explicit feature allows logic where it would undesirable for a reaction to not complete its work regardless of a state change of the rule that started it.

A reaction also cannot run if it is already running. Any attempts to start a new run of an already-running reaction are simply ignored.

Reaction Delays

Reactions can have delays, which pause the run of all actions listed after the delay. Multiple delays are permitted. Reactions are durable across reloads of Reactor and reboots of the host system. An interrupted reaction will resume after the restart, and effort is made to keep the delayed actions on schedule. For example, if a delay of 5 minutes in encountered in execution at 2:15:03PM, and a reload or reboot occurs during the delay, the actions would resume at 2:20:03PM as long as the system is up and ready at that time (otherwise, they will resume as soon as the system is ready after the scheduled time).

Timing is not guaranteed!

If, for example, two Reactions are delayed to the same point in time, there is no guarantee which will resume first when the time is reached.

Action Groups

An action group is a group of actions that can be executed conditionally. Sometimes when writing a rule, you will find that you want to perform an action or actions with additional conditions. For example, a motion sensor may trigger a light, but you want the light to come on at 100% brightness during the day, and only 25% brightness at night. Action groups are one way of doing this without creating separate rules for day and night.

The conditions for an action group function identically to the conditions used as constraints in a rule, and use the same user interface. When you create a group action, the conditions required to be met appear at the top of the group. In order for the actions in the group to run, the conditions must be met. If the group contains no conditions, it is assumed to be met and the actions will run.

Disable on Group Constraints

The "Disable" button in group constraints does not disable the action group and prevent its actions from running. The disable flag in this context applies to the constraint conditions only, and has the same meaning it has in rule triggers and constraints — the conditions are treated as if they do not exist. Actions in the action group are not affected by disabled constraints (the actions will still run).

Repeat While

The Repeat...While action is a special version of an action group that continues to execute as long as the group's conditions are met and produce a boolean true result. This can be used, for example, to repeat a command to a device periodically until it responds, or send a notification periodically while the rule's triggering conditions are met.

The actions in a Repeat...While group are executed repeatedly until one of the following occurs:

• The conditions listed on the Repeat...While group produce a result other than boolean true, or...
• If the contra-reaction of the parent Rule is not empty, the reaction stops when the parent Rule's triggering conditions are no longer met and the Rule changes state. For example, if the Repeat...While is in a Rule's Set reaction, and the Reset reaction is not empty, then when the Rule's triggering conditions are no longer met, the Set reaction (and thus the Repeat...While) is stopped. This is consistent with Reactor's normal rule-based reaction execution (see Special Behaviors of Rule-based Reactions above on this page).
• The reaction is stopped by an explicit stop instruction (via the Running Reactions status panel button, an API call, etc.).

Delay Action Required

It is pretty much a requirement that at least one Delay action be used inside a Repeat...While. Otherwise, the actions in the group will run continuously as fast as Reactor can manage, which is almost always going to be an undesirable behavior/side-effects.

NUL effect on Repeat...While

If the constraint conditions of a Repeat...While group produce a non-boolean result, the loop will stop (or not run at all if that's the result of the initial evaluation). This includes empty constraint groups (because constraint groups with no conditions produce a null result, which is non-boolean), and disabled constraints (because disabled constraint groups are treated as if they don't exist, so they are equivalent to empty constraint groups as a result).

Comment Action

The comment action doesn't actually do anything, it's just a placeholder for text that you can use to document your Reaction.

It does have one special feature: if the first character is a "*", the comment text is written to the Notifications widget on the Status page.

Updated: 25-Sep-2024