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.

Set Global Variable

A Global Variable can be set by an endpoint trigger. The format for the parameter is this:

/setGlobalVariable=varName:varString

The varString portion is assumed to be URL encoded, and is URL decoded before being stored into the varName global variable.


Note: Rule Machine actions Stop Rule Actions, Pause Rule and Resume Rule only work for Rule 2.5 or later. Rule Machine action Set Global Variable only works for Rule 3.0 or later.


[RELEASE] WATO - When any Attribute Then this cmd Otherwise that cmd
Hub Update 2.0.2
Stuck using RM API
Rule Machine Global Variables
[Released] Rule Machine 3.0
Support for PowerSource capability
pinned #2

unpinned #3

pinned #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.


#15

Is there any plans to add support to set Global Variables with the RM API? I was thinking about using this option for weather alerts to RM.


#16

Will take a look at it.


#17

Where can the Access Token be found at for RM API? The Access Tokens from the Dashboard or Maker doesn't appear to work (getting invalid token error) for either the Local or Cloud Endpoints.


#18

See the instructions above in the first post for Using Rule Machine from HTTP requests.


#19

Thanks, I found it.


#20

@bravenel What was the answer to opening up Global Variables to this API?