<h1>Rule 4.0 -- The new Rule Machine</h1>

Rule 4.0 is the culmination of a journey in the transformation of Rule Machine. At once it simplifies and adds power, resulting in a fully generalized automation engine. The prior top-level organization of RM is thrown out, replaced by a simpler interface. The changes are described below, and how what was done in prior versions is now accomplished. Gone are Rules, Triggers, Triggered Rules, Actions and Schedules. Instead, you define what causes a rule to run, and then what it does. The functionality of Button Controller is fully incorporated into Rule Machine, but with more power and flexibility. New conditional logic capabilities are provided, allowing the most subtle or complex automations to be created. You define what causes the rule to run, and then what it does.

'''What Became of Rule, Trigger, Triggered Rule, Action and Schedule?'''

To explain how the former RM concepts of Rule, Trigger, Triggered Rule, Actions and Schedule are now accomplished, and how Button Controller is incorporated, first we address the easy and obvious:

What was a Trigger is now the basic format for all rules. Select Trigger Events and define actions.

What was an Action is accomplished by simply omitting Trigger Events and only defining actions. Obviously, such a rule needs to be run by some other rule or from the RM API.

What was a Schedule is now available as a new type of Trigger Event, Days of Week Schedule.

Button Controller is fully incorporated as a new type of Trigger Event, Button Device. Once Button Device is selected the full UI of Button Controller 3.0 is pulled up to define actions for any of the buttons available on the selected device. Unlike Button Controller, these actions have full access to conditional logic and global variables.

'''How to Build a Rule in Rule 4.0'''

Now, for the more complex cases of a Rule, and a Triggered Rule, we will explain how a former Rule 3.0 Rule is done in Rule 4.0. In a Rule the rule itself can be thought of as an overarching IF-THEN-ELSE, where if the rule was true in the IF part, then Actions for True would run, and if false, Actions for False would run. This same logic can now simply be done with conditional actions IF-THEN and ELSE in the actions section of a rule. As will be described below, IF-THEN now has the same full logical expression capability of the former Rule with AND, OR, XOR, NOT logical operators and nested parenthetical sub-expressions.

The trigger event is contact sensor "Front Door *changed*". In an old Rule, this is exactly how the Condition of Front Door *open* was interpreted -- the rule would be evaluated whenever any event happened for the Front Door. Instead of that being implicit in the old Rule, now it is explicit in the 4.0 rule. In the old Rule, our rule was "Front Door *open*". Now we make that the condition of an IF-THEN action. What were Actions for True become the actions following IF-THEN, and Actions for False become the actions following ELSE. Most Rules follow this basic format.

'''What became of Rule Truth and Cancel on Truth Change?'''

There are two subtle issues from Rule 3.0 that have changed, cancel on truth change and requiring truth change to take action. The concept of rule truth is gone in Rule 4.0. Instead, all of this is now explicit in the way you write the actions for a rule. Below are two examples to illustrate cancel on truth change, first for 3.0 and then 4.0. This rule uses Cancel On Truth Change to keep some lights on as long as motion is active:

If we don't want the actions to run unless there was a change, the equivalent of change in rule truth of a 3.0 Rule, we can do that explicitly using Private Boolean. In the example above, if one of the two motion sensors went inactive, and then became active again before the lights turned off, the actions would run again, turning the lights on again. Generally, this is harmless.

What this accomplishes is that once the lights are turned on from motion active, Private Boolean is set to false, and the lights will not be turned on again until the full delay timer has run its course and the lights have been turned off. When that happens, Private Boolean is set to true, and the whole cycle can repeat.

'''What about Triggered Rules?'''

All "rules" in Rule 4.0 are in effect Triggered Rules. The rules shown above, the equivalents in Rule 4.0 for Rules in 3.0, are all triggered rules. They each have a trigger event, and then conditional actions. Instead of a rule with Actions for True and Actions for False, as with other rules in 4.0 they simply use conditional logic in the actions to create an equivalent IF-THEN-ELSE structure.

== Events ==

Each rule has one or more Trigger Events that when triggered, cause the rule's actions to run.

<p>Events are created by the devices in your system. Each device creates events appropriate to the type of device. A Trigger Event listens for specific events. When a trigger receives a selected event, it causes the defined actions to run.</p>

<p>Rule Machine allows the following events in a Hubitat Elevation system to be acted upon. Each event results in a single test. The supported events and states that can be tested are listed below.</p>

<pre>Acceleration: active / inactive
Battery: value
Button: pressed / held / doubleTapped / released
Button Device: select actions for any buttons of a button device
Certain Time: at a certain time, including sunrise / sunset with offset
Cloud End Point: hitting URL fires
Contact: open / closed
Days of Week Schedule: at certain time on certain days of the week
Dimmer level: value
Door: open, closed, opening, closing, unknown
Energy meter: value
Garage door: open, closed, opening, closing, unknown
HSM alert: intrusion, intrusion-delay, intrusion-home, intrusion-home-delay, intrusion-night, cancelRuleAlerts, intrusion-night-delay,
smoke, water, rule, arming, armingHome, armingNight, cancel
HSM status: armed away, armed home, armed night, delayed arming home, delayed arming night, delayed arming away, disarmed, all disarmed
Humidity: value
Illuminance: value
Local End Point: hitting URL fires
Lock: locked / unlocked
Mode: any of your hub's modes
Motion: active / inactive
Music player: playing, paused, stopped
Periodic: allows periodic schedules for minutes, hourly, daily, weekly, monthly or yearly
Physical dimmer level: value
Physical switch: on / off
Power meter: value
Power source: mains / battery
Presence: present / not present or arrives / leaves
Private Boolean: true / false
Rule truth: true / false
Smoke detector: clear, detected, tested
Switch: on / off
Temperature: value
Thermostat mode: heat / cool / auto / off / emergency heat
Thermostat state: heating / cooling / fan only / idle / pending heat / pending cool
Variable: value
Water sensor: dry / wet

Note: value means compare current value to a number, to another device with an offset, or to a variable with an offset, or changed, increased, decreased</pre>

<p>For each event that refers to a device, one or more devices can be selected, and then the device state required for the condition to be met can be selected. When multiple devices are selected, the condition/event may apply for ANY (default) or ALL of the devices. </p>

== Actions ==

Actions are the portion of a rule that defines what the rule does when it is triggered to run.

'''Actions as ordered script'''

As you define actions you are creating a script of actions to perform when the rule runs. Instead, for example, of only being able to have a single action for turning on switches in Rule 2.5, you can now have as many actions for each action type as you want. And these actions can be run in whatever order you want. No longer is there a predefined order of execution for RM actions -- it's up to you to order the actions however you want. You can insert a new action anywhere in the list of actions, or at the end of the list.

'''Actions can be edited'''

The UI provides the facility to edit or delete any action you have defined, giving you complete control over your list of actions.

Screen shot: [https://community.hubitat.com/uploads/default/original/3X/0/1/0168c7cd17a0877a0756834dc24d1476a9231b5c.png]

'''Delay per action and Delay (Pause) all actions'''

There are three types of delays included in Rule 3.0:
1. Each individual action can have its own delay, which for Rules may include a cancel-on-truth-change option.
2. All actions can be delayed, effectively pausing the action execution for some amount of time.
3. All actions can be delayed for a period of time that depends on the current mode (Delay Actions Per Mode).

These are further described below.

''Delay per action''

Each action you define can have an optional delay. These delays can be defined with hours, minutes, and seconds. Seconds can have decimal fractions, allowing millisecond resolution. In a Rule, delays can have the option to be cancelled in the event of a change of rule truth. It is important to realize that the delay assigned to an individual action affects only that action, and not subsequent actions. Any subsequent action is executed immediately after the delayed action starts its delay timer -- it doesn't wait for that delay timer to run. When that delay timer expires, the delayed action is executed (unless the delay was cancelled).

''Delay all actions''

It is also possible to delay all actions (also with optional cancel). The script of actions runs sequentially when the rule runs, with each action happening in order. Actions with delays start their timer, which can vary for each action, and the next action in order then runs. By using the Delay Actions action the entire script can be 'paused' by a delay. This feature can also be specified on a per mode basis, so that the time the script is paused varies according to the current mode.

As a consequence of these new features, some of the actions in Rule 2.5 have not been included in Rule 3.0. Specifically, those actions which incorporated a delay, or a delay with cancel, have not been included, since now every action can have such delays.

== Conditional Actions and Logical Expressions ==

In Rule 4.0 IF-THEN-ELSE-ENDIF conditional blocks can be nested. The UI uses textual indentation to help guide you in keeping track of which IF-THEN-ELSE-ENDIF block you are currently adding actions to. It falls on you to complete each level of nested IF-THEN blocks.

In Rule 4.0 the condition of an IF-THEN or ELSE-IF action can be a full logical expression built up from individual conditions, and logical operators AND, OR, XOR, and NOT. Parenthesized sub-expressions are also possible. This is the same user interface used to create the rule portion of a Rule or Triggered Rule for Rule 3.0. An individual condition can be created 'on the fly' while defining a logical expression. Every such condition is kept in the list of available conditions. This list of available conditions is available on the Define Actions page. It can be opened, and presents the familiar user interface for creating, editing and deleting conditions. If a condition is edited, those changes will be reflected where it is used in an IF-THEN or ELSE-IF conditional action.

This combination of nested IF-THEN blocks and full logical expression for each IF-THEN and ELSE-IF allows creativity for rules in Rule 4.0 that is limited only by your imagination. To help you with complex logic structures, one more new action is provided: Exit Rule. With Exit Rule the execution of actions for that rule stops, irrespective of where in the rule it is. Pending delays are not cancelled, and current repetitions are not stopped. These can be managed separately if so desired with Stop Repeating Actions, Stop Rule Actions, and Cancel Delayed Actions, as appropriate.

'''Automatic Condition Creation'''

When Event Triggers are defined, corresponding conditions are created for most types. Some, like button, Certain Time, etc, do not have state and so have no corresponding condition. These created conditions are available in the Define Actions page for use in Conditional actions. These can be edited. For example, in the rule above where Motion Changed was the trigger event, there is an IF-THEN for Motion Active as the first action. Instead of having to create that by hand, it is automatically created. One needs to edit it to modify from using Changed to using Active.

Every condition that you create in a Conditional action is available for use in other actions, and can be edited.

'''IF-THEN-ELSE'''

You can introduce conditional execution of actions using:
IF (condition) THEN
some actions...
ELSE-IF (condition) THEN
some actions...
ELSE
some actions...
END-IF

IF-THEN and ELSE-IF both accept a logical expression as described above. IF-THEN-ELSE can be nested. If the expression on the IF part is true, then those actions following the IF and before any ELSE-IF or ELSE statements are run. If the expression is false, then those actions are skipped, and the ELSE part or ELSE-IF part are run. In the case of ELSE-IF, its expression is tested, and the following actions run or not depending on the result. There can be as many ELSE-IF sections as you want, and both ELSE-IF and ELSE are optional. END-IF is also optional, and if omitted means all remaining actions are part of the preceding IF-THEN, ELSE-IF or ELSE. It is strongly recommended that you use END-IF as a regular practice.

== Repeat Actions ==

Portions, or all of, the script of actions can be repeated, similar to Rule 2.5's Repeat These Actions. As with Rule 2.5, this supports stopping repetition upon rule truth change for a Rule, and allows for a selected number of iterations. When a Repeat Actions is introduced to the script, following actions will be repeated. A new feature, End Repetition, can be placed in the script. When this is done, only those actions between Repeat Actions and End Repetition are repeated.

Repeat Actions
some actions...
End Repetition

A Repeat Actions, like any action, can have a condition specified. If the condition is false, the Repeat Actions block of actions will not be executed. If the condition becomes false during repetition, the repetition will be stopped (not in the case of Repeat a selected number of times). This provides three features well known to computer programmers; A while-loop, a for-loop and repeat-until loop. The while-loop runs only if the condition is true, and stops if it is false. A for-loop runs for a fixed number of times, but if a condition exists, it will only start that iteration if the condition is true; the condition is not retested during iteration. A repeat-until loop runs until a condition becomes true, running at least once.

''While loop - repeat while the condition is true:''
IF (condition) Repeat Actions
some actions...
End Repetition

''For loop (repeat n times):''
Repeat Actions n times
some actions...
End Repetition

''Conditional For loop (repeat n times if condition is true):''
IF (condition) Repeat Actions n times
some actions...
End Repetition

''Repeat-Until loop:''
Repeat Actions
some actions
IF (condition) Stop Repeating Actions
End Repetition

Repeat Actions may not be nested. End Repetition is optional, and if omitted, all actions after Repeat Actions are repeated. Note the "End Repetition" does not have anything to do with the when the Repeated Actions will stop repeating -- it merely marks the end of the list of actions to be repeated. If you use Repeat These Actions without N Times (for loop), and without a Condition (while loop), and without a Conditional Stop, and without Stop on Truth Change (for rules only), that means to repeat forever. That is probably not what you want to have happen. In this case, some other rule would need to cause the repetition to stop.

== Wait for Events and Wait for Condition ==

Wait for Events pauses rule execution until some specified event occurs. Multiple events can be defined to cause the wait to end. In effect, this introduces another trigger-like capability into the actions. There is also an event type specifically for Wait for Events, Elapsed Time. When the Elapsed Time expires, the wait will be over, irrespective of other events the wait may be waiting for.

Wait for Condition is similar to Wait for Events, but instead a condition is evaluated. If the condition is true, no wait occurs. Otherwise, the rule execution is paused until the condition is met.

Wait for Events and Wait for Condition may be used in a Simple Conditional Action. Both pending Wait for Events and Wait for Condition are cancelled each time a rule is triggered, and be cancelled by another rule with Stop Rule Actions, or by Cancel Wait action (which presumably would have been in a delayed action).

== Custom Actions ==

In addition to Custom Commands as have been available in prior versions, Rule 3.0 introduces Custom Actions. A Custom Action allows you to select a device, and send any of the commands that device supports along with parameters it may take. While Custom Commands are pre-defined and available to all rules, a Custom Action is created within your actions and is specific to the rule where it is created.

== Global Variables ==

Global Variables are now displayed on Rule Machine main page. When creating one, it must be initialized. Global variable values can also be changed in Rule Machine. When a global variable is deleted, a warning is given if the variable is in use in a rule/trigger et al, and if deleted anyway, they are removed from the rule where they are in use. This removal may leave such a rule with holes in it. Conditions based on variables will be removed, which in turn may erase the rule definition. Actions that set variables will be removed. Variables used in comparisons will leave the comparison missing what is to be compared. Actions with dimmers/bulbs set by variables will have missing settings. Manage your global variables with some care to avoid problems.

''Global Variables Can Be Used for Level/Color''

Global variables can be used in actions that set dimmer or bulb levels, color temperature, or hue/saturation values. To use a variable in this way, include it with %global-variable-name%. In each case only a "Number" global variable is allowed, and it is not range checked

''Global Variables can be set by endpoint''

A string Global Variable can be set by an endpoint trigger. This is an addition to the [Rule Machine API](https://community.hubitat.com/t/rule-machine-api/7104).

''Global Variables can be used with parameters for Custom Actions''

A Global Variable can be used with parameters by using %global-variable-name%.

''Global Variables in messages''

To include the value of a global variable in a message string (or HTTP request url or body), use %global-variable-name%.

== Run actions from UI ==

When you first create a new rule, you must hit Done on the main page to install the rule. If you reopen the rule, its actions can be run by hitting Run Actions button. If you change the Trigger Events in any way, you must either hit Done or Update Rule button.

You can select which types of logging you want to see in Logs. This is a very good way to determine exactly what a rule is doing.

== List of Actions ==

<pre> Conditional Actions
IF (conditions) THEN
ELSE-IF (conditions) THEN
ELSE
END-IF
Simple Conditional Action
Control Switches, Push Buttons
Turn switches on
Turn switches off
Toggle switches
Flash switches
Set switches per mode
Push a button
Push a button per mode
Set Dimmers and Bulbs
Set dimmer level
Toggle dimmer level
Adjust dimmer level
Set dimmer level per mode
Fade dimmer level over time
Start raising dimmer level
Start lowering dimmer level
Stop changing dimmer level
Set color and level
Toggle color and level
Set color and level per mode
Set color temperature and level
Toggle color temperature and level
Set color temperature and level per mode
Activate Scenes, Adjust Shades or Fans
Activate scenes
Activate scenes per mode
Open shades
Close shades
Set shade position
Set fan speed
Cycle fans
Control HSM, Garage Doors, Locks or Valves
Arm/Disarm Hubitat® Safety Monitor
Open garage door
Close garage door
Lock locks
Unlock locks
Open valves
Close valves
Control Thermostats or Thermostat Scheduler
Set thermostats
Set Thermostat Scheduler
Send or Speak a Message, Send HTTP Request
Send or Speak a Message
Send HTTP Get
Send HTTP Post
Control Music Player, Sounds
Control Music Player
Sound Tone
Sound Chime
Control Siren
Set Mode or Global Variables, Run Custom Action
Set Mode
Set Global Variable
Run Custom Action
Set Private Boolean, Run/Stop/Pause Rules
Set Private Booleans True
Set Private Booleans False
Run Rule Actions
Stop Rule Actions
Pause Rules
Resume Rules
Capture/Restore, Device Refresh or Polling
Capture Devices
Restore Devices
Refresh devices
Poll devices
Start Z-Wave poll on switches
Stop Z-Wave poll on switches
Start Z-Wave poll on dimmers
Stop Z-Wave poll on dimmers
Delay or Repeat Actions, Wait
Delay Actions
Delay Actions Per Mode
Cancel Delayed Actions
Repeat Actions
End Repetition
Stop Repeating Actions
Wait for Events
Wait for Condition
Cancel Wait
Exit Rule</pre>

Rule Machine

2019-07-03T00:52:11Z

Bravenel:

Rule Machine

2019-07-03T00:51:10Z

Bravenel:

Rule Machine

2019-07-03T00:50:33Z

Bravenel:

Bravenel:

<h1>New Version of Rule Machine: Rule 3.0</h1>

We are introducing a new version of Rule Machine, with Rule 3.0. Rule 3.0 is a new child app for the parent Rule Machine. Existing child app instances that are installed, Rule and Rule 2.5, will continue to function as before. New rules that are created will be Rule 3.0. This release marks the end of development for Rule 2.5, just as its release marked the end of development for Rule. There is no reason to recreate existing old rules in Rule 3.0, unless you want to. The author still has a majority of his rules running the original Rule child.

In recent releases of Rule 2.5, a major effort was made to redo the UI for defining Conditions, Trigger Events, and Rules. In each case, the UI was streamlined and flattened to a single page. The ability to easily edit Conditions, and redo Rules was introduced. Rule 3.0 brings this same UI overhaul to Action definition. The UI is streamlined and flattened, and actions can be easily edited. But, the changes don't stop there: Rule 3.0 introduces considerable new power and flexibility to Rule Machine actions.

See the Rule Machine Introduction here:
*[[Rule Machine]]<sup>®</sup>

<h2>New Features</h2>

Rule 3.0 represents a complete overhaul of action definition. There are a number of new concepts and capabilities provided.

'''Actions as ordered script'''

As you define actions you are creating a script of actions to perform when the rule runs. Instead, for example, of only being able to have a single action for turning on switches in Rule 2.5, you can now have as many actions for each action type as you want. And these actions can be run in whatever order you want. No longer is there a predefined order of execution for RM actions -- it's up to you to order the actions however you want. You can insert a new action anywhere in the list of actions, or at the end of the list.

'''Actions can be edited'''

The UI provides the facility to edit or delete any action you have defined, giving you complete control over your list of actions.

Screen shot: [https://community.hubitat.com/uploads/default/original/3X/0/1/0168c7cd17a0877a0756834dc24d1476a9231b5c.png]

'''Delay per action and Delay (Pause) all actions'''

There are three types of delays included in Rule 3.0:
1. Each individual action can have its own delay, which for Rules may include a cancel-on-truth-change option.
2. All actions can be delayed, effectively pausing the action execution for some amount of time.
3. All actions can be delayed for a period of time that depends on the current mode (Delay Actions Per Mode).

These are further described below.

''Delay per action''

Each action you define can have an optional delay. These delays can be defined with hours, minutes, and seconds. Seconds can have decimal fractions, allowing millisecond resolution. In a Rule, delays can have the option to be cancelled in the event of a change of rule truth.

''Delay all actions''

It is also possible to delay all actions (also with optional cancel). The script of actions runs sequentially when the rule runs, with each action happening in order. Actions with delays start their timer, which can vary for each action, and the next action in order then runs. By using the Delay Actions action the entire script can be 'paused' by a delay. This feature can also be specified on a per mode basis, so that the time the script is paused varies according to the current mode.

As a consequence of these new features, some of the actions in Rule 2.5 have not been included in Rule 3.0. Specifically, those actions which incorporated a delay, or a delay with cancel, have not been included, since now every action can have such delays.

'''Conditional Actions'''

Each action can have a condition tested to control whether or not it is executed. These conditions offer the same choices as those used to define rules, but are independent of the Conditions of a Rule. When such a conditional action is edited, the condition may be edited as well. This simple condition applies to a single action.

'''IF-THEN-ELSE'''

You can introduce conditional execution of actions using:
IF (condition) THEN
some actions...
ELSE-IF (condition) THEN
some actions...
ELSE
some actions...
ENDIF

IF-THEN and ELSE-IF both accept a condition as described above. IF-THEN-ELSE may not be nested. If the condition on the IF part is true, then those actions following the IF and before any ELSE-IF or ELSE statements are run. If the condition is false, then those actions are skipped, and the ELSE part or ELSE-IF part are run. In the case of ELSE-IF, its condition is tested, and the following actions run or not depending. There can be as many ELSE-IF sections as you want, and both ELSE-IF and ELSE are optional. ENDIF is also optional, and if omitted means all remaining actions are part of the preceding IF-THEN, ELSE-IF or ELSE.

'''New Repeat Actions'''

Portions, or all of, the script of actions can be repeated, similar to Rule 2.5's Repeat These Actions. As with Rule 2.5, this supports stopping repetition upon rule truth change for a Rule, and allows for a selected number of iterations. When a Repeat Actions is introduced to the script, following actions will be repeated. A new feature, End Repetition, can be placed in the script. When this is done, only those actions between Repeat Actions and End Repetition are repeated.

Repeat Actions
some actions...
End Repetition

A Repeat Actions, like any action, can have a condition specified. If the condition is false, the Repeat Actions block of actions will not be executed. If the condition becomes false during repetition, the repetition will be stopped (not in the case of Repeat a selected number of times). This provides three features well known to computer programmers; A while-loop, a for-loop and repeat-until loop. The while-loop runs only if the condition is true, and stops if it is false. A for-loop runs for a fixed number of times, but if a condition exists, it will only start that iteration if the condition is true; the condition is not retested during iteration. A repeat-until loop runs until a condition becomes true, running at least once.

''While loop - repeat while the condition is true:''
IF (condition) Repeat Actions
some actions...
End Repetition

''For loop (repeat n times):''
Repeat Actions n times
some actions...
End Repetition

''Conditional For loop (repeat n times if condition is true):''
IF (condition) Repeat Actions n times
some actions...
End Repetition

''Repeat-Until loop:''
Repeat Actions
some actions
IF (condition) Stop **This Rule**
End Repetition

Repeat Actions may not be nested. End Repetition is optional, and if omitted, all actions after Repeat Actions are repeated. Note the "End Repetition" does not have anything to do with the when the Repeated Actions will stop repeating -- it merely marks the end of the list of actions to be repeated. If you use Repeat These Actions without N Times (for loop), and without a Condition (while loop), and without a Conditional Stop, and without Stop on Truth Change (for rules only), that means to repeat forever. That is probably not what you want to have happen. In this case, some other rule would need to cause the repetition to stop.

'''New Custom Actions'''

In addition to Custom Commands as have been available in prior versions, Rule 3.0 introduces Custom Actions. A Custom Action allows you to select a device, and send any of the commands that device supports along with parameters it may take. While Custom Commands are pre-defined and available to all rules, a Custom Action is created within your actions and is specific to the rule where it is created.

'''Global Variable Improvements'''

Global Variables are now displayed on Rule Machine main page. When creating one, it must be initialized. Global variable values can also be changed in Rule Machine. When a global variable is deleted, a warning is given if the variable is in use in a rule/trigger et al, and if deleted anyway, they are removed from the rule where they are in use. This removal may leave such a rule with holes in it. Conditions based on variables will be removed, which in turn may erase the rule definition. Actions that set variables will be removed. Variables used in comparisons will leave the comparison missing what is to be compared. Actions with dimmers/bulbs set by variables will have missing settings. Manage your global variables with some care to avoid problems.

''Global Variables Can Be Used for Level/Color''

Global variables can be used in actions that set dimmer or bulb levels, color temperature, or hue/saturation values. To use a variable in this way, include it with %global-variable-name%. In each case only a "Number" global variable is allowed, and it is not range checked

''Global Variables can be set by endpoint''

A string Global Variable can be set by an endpoint trigger. This is an addition to the [Rule Machine API](https://community.hubitat.com/t/rule-machine-api/7104).

''Global Variables can be used with parameters for Custom Actions''

A Global Variable can be used with parameters by using %global-variable-name%.

''Global Variables in messages''

Unlike Rule 2.5, in Rule 3.0 to include the value of a global variable in a message string (or HTTP request url or body), use %global-variable-name%.

'''Run rule from UI'''

In prior version of Rule Machine, upon hitting Done on the main page of a Rule, that Rule would be evaluated. This behavior was problematic, as unintended actions would sometimes take place upon that event. In Rule 3.0 this is no longer the case. Instead, each Rule, Trigger, Triggered Rule and Actions has a button on the main page to run the rule. In the case of a Rule or a Triggered Rule the actions run as a consequence of this are determined by the truth of the rule, which is displayed at the bottom of the rule definition and in the app name at the top of the page. In the case of Trigger and Actions, the actions are simply run. In each case, hitting Done on the main page does not cause any action, although it does establish event subscriptions and schedules for the rule.

'''Other new features'''

''New HTTP action''

A new HTTP request action is now available: send an HTTP Post. This accepts URL and a body, which may be JSON, XML, or form encoded.

''New Siren Actions''

Rule 3.0 now offers actions to control a siren device, with commands siren, strobe, both and off.

''New Dimmer Actions''

Start raising, start lowering, and stop changing dimmer levels added.

''New Color Action''

Color per mode is now available.

''Set Color Temperature''

Set Color Temperature now has option to set the level in same action.

''Shade Actions''

Shade actions now use the Window Shade capability. Available action are open, close and set position.

''Fan Speed and Fan Actions''

Capability "Fan Speed" is now supported for Conditions and Trigger Events. This uses the Fan Control capability used for fans. A new action, Set Fan Speed, is available. The Adjust Fan action is changed from controller of fan-as-dimmer, to using Fan Speed commands: low, medium-low, medium, medium-high, high, on, off and auto.

''Power Source Capability''

Capability "Power Source" is now fully supported for Conditions and Trigger Events. This supports two states: mains and battery.

'''Screen Shots'''

Editing Set Global Variable: [https://community.hubitat.com/uploads/default/optimized/3X/e/a/eaf220111902248dfd28534ce5234e58f6537e80_2_1380x882.png]

IF-THEN Example: [https://community.hubitat.com/uploads/default/optimized/3X/2/d/2d75ae5aee767eefd653aec85df169ce65ef80cb_2_1380x986.png]

Rule-3.0

2019-05-10T19:20:22Z

Bravenel:

<h1>New Version of Rule Machine: Rule 3.0</h1>

We are introducing a new version of Rule Machine, with Rule 3.0. Rule 3.0 is a new child app for the parent Rule Machine. Existing child app instances that are installed, Rule and Rule 2.5, will continue to function as before. New rules that are created will be Rule 3.0. This release marks the end of development for Rule 2.5, just as its release marked the end of development for Rule. There is no reason to recreate existing old rules in Rule 3.0, unless you want to. The author still has a majority of his rules running the original Rule child.

In recent releases of Rule 2.5, a major effort was made to redo the UI for defining Conditions, Trigger Events, and Rules. In each case, the UI was streamlined and flattened to a single page. The ability to easily edit Conditions, and redo Rules was introduced. Rule 3.0 brings this same UI overhaul to Action definition. The UI is streamlined and flattened, and actions can be easily edited. But, the changes don't stop there: Rule 3.0 introduces considerable new power and flexibility to Rule Machine actions.

See the Rule Machine Introduction here:

<h2>New Features</h2>

Rule 3.0 represents a complete overhaul of action definition. There are a number of new concepts and capabilities provided.

'''Actions as ordered script'''

As you define actions you are creating a script of actions to perform when the rule runs. Instead, for example, of only being able to have a single action for turning on switches in Rule 2.5, you can now have as many actions for each action type as you want. And these actions can be run in whatever order you want. No longer is there a predefined order of execution for RM actions -- it's up to you to order the actions however you want. You can insert a new action anywhere in the list of actions, or at the end of the list.

'''Actions can be edited'''

The UI provides the facility to edit or delete any action you have defined, giving you complete control over your list of actions.

Screen shot: [https://community.hubitat.com/uploads/default/original/3X/0/1/0168c7cd17a0877a0756834dc24d1476a9231b5c.png]

'''Delay per action and Delay (Pause) all actions'''

There are three types of delays included in Rule 3.0:
1. Each individual action can have its own delay, which for Rules may include a cancel-on-truth-change option.
2. All actions can be delayed, effectively pausing the action execution for some amount of time.
3. All actions can be delayed for a period of time that depends on the current mode (Delay Actions Per Mode).

These are further described below.

''Delay per action''

Each action you define can have an optional delay. These delays can be defined with hours, minutes, and seconds. Seconds can have decimal fractions, allowing millisecond resolution. In a Rule, delays can have the option to be cancelled in the event of a change of rule truth.

''Delay all actions''

It is also possible to delay all actions (also with optional cancel). The script of actions runs sequentially when the rule runs, with each action happening in order. Actions with delays start their timer, which can vary for each action, and the next action in order then runs. By using the Delay Actions action the entire script can be 'paused' by a delay. This feature can also be specified on a per mode basis, so that the time the script is paused varies according to the current mode.

As a consequence of these new features, some of the actions in Rule 2.5 have not been included in Rule 3.0. Specifically, those actions which incorporated a delay, or a delay with cancel, have not been included, since now every action can have such delays.

'''Conditional Actions'''

Each action can have a condition tested to control whether or not it is executed. These conditions offer the same choices as those used to define rules, but are independent of the Conditions of a Rule. When such a conditional action is edited, the condition may be edited as well. This simple condition applies to a single action.

'''IF-THEN-ELSE'''

You can introduce conditional execution of actions using:
IF (condition) THEN
some actions...
ELSE-IF (condition) THEN
some actions...
ELSE
some actions...
ENDIF

IF-THEN and ELSE-IF both accept a condition as described above. IF-THEN-ELSE may not be nested. If the condition on the IF part is true, then those actions following the IF and before any ELSE-IF or ELSE statements are run. If the condition is false, then those actions are skipped, and the ELSE part or ELSE-IF part are run. In the case of ELSE-IF, its condition is tested, and the following actions run or not depending. There can be as many ELSE-IF sections as you want, and both ELSE-IF and ELSE are optional. ENDIF is also optional, and if omitted means all remaining actions are part of the preceding IF-THEN, ELSE-IF or ELSE.

'''New Repeat Actions'''

Portions, or all of, the script of actions can be repeated, similar to Rule 2.5's Repeat These Actions. As with Rule 2.5, this supports stopping repetition upon rule truth change for a Rule, and allows for a selected number of iterations. When a Repeat Actions is introduced to the script, following actions will be repeated. A new feature, End Repetition, can be placed in the script. When this is done, only those actions between Repeat Actions and End Repetition are repeated.

Repeat Actions
some actions...
End Repetition

A Repeat Actions, like any action, can have a condition specified. If the condition is false, the Repeat Actions block of actions will not be executed. If the condition becomes false during repetition, the repetition will be stopped (not in the case of Repeat a selected number of times). This provides three features well known to computer programmers; A while-loop, a for-loop and repeat-until loop. The while-loop runs only if the condition is true, and stops if it is false. A for-loop runs for a fixed number of times, but if a condition exists, it will only start that iteration if the condition is true; the condition is not retested during iteration. A repeat-until loop runs until a condition becomes true, running at least once.

''While loop - repeat while the condition is true:''
IF (condition) Repeat Actions
some actions...
End Repetition

''For loop (repeat n times):''
Repeat Actions n times
some actions...
End Repetition

''Conditional For loop (repeat n times if condition is true):''
IF (condition) Repeat Actions n times
some actions...
End Repetition

''Repeat-Until loop:''
Repeat Actions
some actions
IF (condition) Stop **This Rule**
End Repetition

Repeat Actions may not be nested. End Repetition is optional, and if omitted, all actions after Repeat Actions are repeated. Note the "End Repetition" does not have anything to do with the when the Repeated Actions will stop repeating -- it merely marks the end of the list of actions to be repeated. If you use Repeat These Actions without N Times (for loop), and without a Condition (while loop), and without a Conditional Stop, and without Stop on Truth Change (for rules only), that means to repeat forever. That is probably not what you want to have happen. In this case, some other rule would need to cause the repetition to stop.

'''New Custom Actions'''

In addition to Custom Commands as have been available in prior versions, Rule 3.0 introduces Custom Actions. A Custom Action allows you to select a device, and send any of the commands that device supports along with parameters it may take. While Custom Commands are pre-defined and available to all rules, a Custom Action is created within your actions and is specific to the rule where it is created.

'''Global Variable Improvements'''

Global Variables are now displayed on Rule Machine main page. When creating one, it must be initialized. Global variable values can also be changed in Rule Machine. When a global variable is deleted, a warning is given if the variable is in use in a rule/trigger et al, and if deleted anyway, they are removed from the rule where they are in use. This removal may leave such a rule with holes in it. Conditions based on variables will be removed, which in turn may erase the rule definition. Actions that set variables will be removed. Variables used in comparisons will leave the comparison missing what is to be compared. Actions with dimmers/bulbs set by variables will have missing settings. Manage your global variables with some care to avoid problems.

''Global Variables Can Be Used for Level/Color''

Global variables can be used in actions that set dimmer or bulb levels, color temperature, or hue/saturation values. To use a variable in this way, include it with %global-variable-name%. In each case only a "Number" global variable is allowed, and it is not range checked

''Global Variables can be set by endpoint''

A string Global Variable can be set by an endpoint trigger. This is an addition to the [Rule Machine API](https://community.hubitat.com/t/rule-machine-api/7104).

''Global Variables can be used with parameters for Custom Actions''

A Global Variable can be used with parameters by using %global-variable-name%.

''Global Variables in messages''

Unlike Rule 2.5, in Rule 3.0 to include the value of a global variable in a message string (or HTTP request url or body), use %global-variable-name%.

'''Run rule from UI'''

In prior version of Rule Machine, upon hitting Done on the main page of a Rule, that Rule would be evaluated. This behavior was problematic, as unintended actions would sometimes take place upon that event. In Rule 3.0 this is no longer the case. Instead, each Rule, Trigger, Triggered Rule and Actions has a button on the main page to run the rule. In the case of a Rule or a Triggered Rule the actions run as a consequence of this are determined by the truth of the rule, which is displayed at the bottom of the rule definition and in the app name at the top of the page. In the case of Trigger and Actions, the actions are simply run. In each case, hitting Done on the main page does not cause any action, although it does establish event subscriptions and schedules for the rule.

'''Other new features'''

''New HTTP action''

A new HTTP request action is now available: send an HTTP Post. This accepts URL and a body, which may be JSON, XML, or form encoded.

''New Siren Actions''

Rule 3.0 now offers actions to control a siren device, with commands siren, strobe, both and off.

''New Dimmer Actions''

Start raising, start lowering, and stop changing dimmer levels added.

''New Color Action''

Color per mode is now available.

''Set Color Temperature''

Set Color Temperature now has option to set the level in same action.

''Shade Actions''

Shade actions now use the Window Shade capability. Available action are open, close and set position.

''Fan Speed and Fan Actions''

Capability "Fan Speed" is now supported for Conditions and Trigger Events. This uses the Fan Control capability used for fans. A new action, Set Fan Speed, is available. The Adjust Fan action is changed from controller of fan-as-dimmer, to using Fan Speed commands: low, medium-low, medium, medium-high, high, on, off and auto.

''Power Source Capability''

Capability "Power Source" is now fully supported for Conditions and Trigger Events. This supports two states: mains and battery.

'''Screen Shots'''

Editing Set Global Variable: [https://community.hubitat.com/uploads/default/optimized/3X/e/a/eaf220111902248dfd28534ce5234e58f6537e80_2_1380x882.png]

IF-THEN Example: [https://community.hubitat.com/uploads/default/optimized/3X/2/d/2d75ae5aee767eefd653aec85df169ce65ef80cb_2_1380x986.png]