Rule Machine API


#1

Rule Machine API

It is possible for other apps to use Rules, Triggers, Triggered Rules, and Actions defined in Rule Machine. This is very similar, and uses the same mechanism, as actions in Rule Machine that affect other rules. It is also possible to use Rules, Triggers, Triggered Rules, and Actions from an HTTP request to an endpoint.

Using Rule Machine from other apps

First, import the RM helper class into your app:

import hubitat.helper.RMUtils

The List of Rules

Rule Machine maintains a list of available Rules, Triggers, Triggered Rules, and Actions. This list can be obtained with this method call:

 def rules = RMUtils.getRuleList()

The resulting list, in this example in the variable "rules", can be used as an input to an "enum", as the options.

Supported Actions

It is possible to set the Private Boolean, evaluate a rule, run the rule actions, or stop running rule actions (either delayed or repeating). This is accomplished by sending an action request to Rule Machine. These will each take this form:

 def RMUtils.sendAction(rules, action, appLabel)

Set Private Boolean True:
action "setRuleBooleanTrue"

Set Private Boolean False:
action "setRuleBooleanFalse"

Evaluate Rule:
action "runRule"

Run Rule Actions:
action "runRuleAct"

Stop Rule Actions:
action "stopRuleAct"

Pause Rule:
action "pauseRule"

Resume Rule:
action "resumeRule"

In each case above, a list of rules selected by input is sent. The rule options come from the variable to which they were input as described above, in the options section of the input..

The "appLabel" parameter is passed and will appear in the log entry that the rule makes when it performs the action commanded. Typically, simply pass app.label, for the name of the app that is causing the action. This has no other function than logging.

Example:

 def rules = RMUtils.getRuleList()
 input "theseRules", "enum", title: "Select which rules to stop", options: rules
 RMUtils.sendAction(theseRules, "stopRuleAct", app.label)

Using Rule Machine from HTTP requests

It is also possible to cause Rule Machine to perform these same actions from an HTTP request. To do this one would create a Trigger or a Triggered Rule with either a Local End Point or Cloud End Point. The endpoint URL given by Rule Machine has this form:

http://192.168.0.36/apps/api/10249/trigger?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db

To run rule actions this URL must be modified to include the list of rules and the action. The modification takes this form:

/action=rule1&rule2&rule3

Where action is the action from the list above and rule1&rule2&rule3 are the appIds of the rules to run separated by ampersands.

This parameter is inserted in the endpoint URL just before the ? that precedes the access_token, like this:

http://192.168.0.36/apps/api/10249/trigger/stopRuleAct=943&956&10217?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db

This example would do the same thing as the code example above, where 943&956&10217 are the appIds that were selected by consequence of the input for theseRules, and stopRuleAct is the action to perform.

The appIds are the values selected by the input described above, for example theseRules. The appIds can also be found for a rule by opening the rule and observing its appId in its url, like this:

http://192.168.0.36/installedapp/configure/10249/mainPage

The appId for that rule is 10249.

Get Rule List

To get the list of rules as is returned from getRuleList() use this insert for the URL:

/getRuleList

for full URL like this:

http://192.168.0.36/apps/api/10249/trigger/getRuleList?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db

This returns a JSON object with appId and rule name pairs. The other requests return a JSON object with a human readable description of what was done.


Note: Rule Machine actions Stop Rule Actions, Pause Rule and Resume Rule only work for Rule 2.5 or later.


Hub Update 2.0.2
[RELEASE] WATO - When any Attribute Then this cmd Otherwise that cmd
#2

#3

#4

#5

Does RM accept JSON with the http request? I'd like to use information passed to the rule.


#6

No, this is not supported.


#7

could it be or is that beyond the purpose of what RM is intended for?


#8

How would you use information passed to a rule? I'm not seeing how this fits the general model of RM.


#9

good point. I was just trying to find a way to mirror what webcore does with it. It's not a big deal. Thanks for responding.


#10

How do you determine the app number to use in the link to get the full rule list?


#11

It's the app you created the endpoint in.


#12

Since each rule in Hubitat gets a separate app number, it just has to be any rule created with a local endpoint?


#13

@bravenel whats the use for stopRuleAct? is this meant for rules with persistent rule actions that continue executing till the stopRuleAct is issued or something else?


#14

Look at the collection of actions you can do on other rules in the actions section. Stop is one of them. It can be used to cancel a delay, a periodic trigger, a repeating action.