Getting Started: Rules - Basic and Rule Templates

This has now been merged into the main docs (should be available sometime in the next day or so after the next build). Thanks for all comments and edits! I’m closing this thread now.

I’m returning to the Getting Started Tutorial. This is a first draft before I submit it to the official docs to give people a chance to review and make changes. It’s a wiki so please edit as necessary and leave a comment.


Very basic rules can be defined in the UI without the need for code. These rules will follow a when X event occurred if Y is true do Z format. For example, when a member of the Temperatures Group changes, if it changed to a value over 70 °F, command the AlertLight Item to “red”.

But, even though this section talks about basic rules, don’t skip it. All rules built through the UI are defined the same way and most of this information will not be repeated.

For this example we will be creating two rules, one that sets a Switch Item to ON when the cloudiness reading goes above 50% and another to OFF when it falls below 50%.

Create the Rule

Navigate to Settings and Rules and click on the + icon in the lower right corner.


Each rule has four pieces of metadata.

Metadata Purpose Notes
Unique ID uniquely identifies the rule must be completely different from all other rule’s UIDs, initialized with a random value but I strongly recommend entering your own UID.
Name “title” of the rule This will be the name under which the rule is shown in MainUI and is the primary field used for search and sorting
Description describes what the rule does do not skip, provide information about what the rule does and what it does it to; leave breadcrumbs you can use later to associated rules with Items and Channels
Tags arbitrary tags Another place to leave breadcrumbs or to group rules together. Note the Script and Schedule tags have a special meaning (see previous page), and although Semantic tags are available, rules are not yet integrated into the Semantic Model.

Here is how this rule appears in the list of rules (note the use a couple of tags):

All but the Unique ID can be changed later. In my system this rule is used to drive my lights and it’s based on weather readings so it’s tagged as appropriate.


Under triggers, click on the green + icon labeled “Add Trigger” to define what events should cause this rule to run. This brings up a form that lets you choose the type of the trigger and enter some information about the trigger.

The title and description are optional and will be automatically populated with meaningful information when you select the trigger. However pay attention and if there is more information that might be useful to you later add that.

We need an Item changed event to trigger this rule so it runs when the cloudiness percentage Item changes. So I select “Item Event” and select my Item and click “Pick” in the upper right corner.

Choose “changed” since we only care when the Item changes. Notice the title and description is filled out with reasonable information.

You will notice that there are “from state” and “to state” fields. These can be used to further narrow down when the rule triggers, but do not confuse these with conditions. You can only include a single state here (e.g. from state: ON to state: OFF). You cannot use comparison operations here (e.g. < 70) and need a condition for that. Therefore these are mostly useful with Switch, Contact, Player, and sometimes String Items. Any Item that has a range of values rather than a few discrete values will not use these.


In this case we have two conditions. We only want the actions to run when the Item is at or above 50% and the status Item vIsCloudy isn’t already ON.

Click the green + icon under “But only if” labeled “Add Condition”.

Choose Item Condition because we want to check the state of an Item and select the Item. Note, sometimes if the Item not part of the model it can be hard to find. If that happens to you, select any Item to start and then you can get a flat list of all your Items on the next screen.

In this case we want to check if the vCloudiness Item is >= to 50 %.

Notice the %. This Item is a Number:Dimensionless representing a percentage. So I’ve used the units here. This will work with any supported units of measurement and there will be a warning in the logs if your Item has units but the “State” does not.

Next we don’t want to run the actions if vIsCloudy is already ON.


Finally, we want this rule to send the ON command when triggered and the conditions are met.

Click the green + icon labeled “Add Action” under the “Then” section and choose “Item Action”. By now the steps should be familiar, select the Item, in this case vIsCloudy and you are presented with the Item action form. In this case we want to send command ON.

The rule is now done! Click Save and watch the log for errors and to see if the rule is working (more on that later).

Copy a Rule

We now have a rule that sets vIsCloudy to ON and we need a corresponding rule to trigger it when OFF. Since this second rule is very similar to the one we just created, we can copy/paste/edit.

First, open the code tab for the rule we just created. This will show a text version of the rule. You should see a section corresponding to each of the parts of the rule (but note that the order of the configured pieces may not match

Copy the text shown here to the clipboard.

Create a new rule (see above), enter the metadata for the rule (this time we are commanding the Item to OFF) and then open the code tab for this new rule. Paste the contents of the clipboard to the code tab and make the edits as necessary.

In this case we want to change the operator for the first condition to <, the state for the second condition to OFF, and the command for the action to OFF. The code would look like this:

This will work for any UI Rule, not just basic rules.

Note, when asking for help on the forum, the experts will want to see this code version pasted as text rather than a screen shot of either the Design tab or the Code tab.

Rule Templates

At some point basic rules will not be sophisticated enough to reach your goal. The first place to look when that’s is the case are the rule templates posted to the Marketplace. You can find them under Settings and Automation.

Installation and Configure

Under the “Languages & Technologies” section there are “Rule Templates” and “Blockly Libraries” sections (discussed on the next page). These are community created capabilities posted to the Marketplace. Someone may have already written the code for you so all you have to do is install and configure it.

Rule Template

In MainUI click on a rule template that seems to do what you want. This will open it’s documentation page which explains how the template works, configuration parameters, dependencies, etc.

To install the template, click on “Add” next to the template’s logo. If installation was successful, you can now create one or more rules based on the template. Navigate to Rules and click the blue + icon to create a new Rule.

Fill out the Rule’s metadata as usual. However, now you will see a “Create from Template” section listing all the installed templates. Choose the template you want to base this rule on.

The bottom of the form will change from the three sections described previously to a form showing the parameters the rule template defines.

In this case, the parameters are selecting a DateTime Item to trigger the rule and which defines the “alarm time” and a “Script” to call when at the date and time in that DateTime Item.


Your rule, once instantiated becomes its own thing separated from the template, just as if you had cut and paste the code as in the first example. Therefore, it will not change even if the rule template is changed or removed. To update a template and a rule use the following process.

  1. Notice that there has been an update to a template that you want to use (keep checking back).

  2. Select the template in MainUI and click “Remove”. Then click “Add” to refresh the template with the new changes.

  3. Go to Settings and Rules and navigate to the rule you want to update. Click the pause icon to disable that rule. Or if you don’t want to keep a backup, delete it. Note, if you just disable you won’t be able to use the same rule UID for the new rule.

  4. Create the rule following the steps from above.

  5. Once the new version of the rule is tested, delete the disabled version of the rule.


What if a rule template does almost what you need but not everything? Since the rule, once instantiated, becomes severed from the template, you can modify the end rule as much as you want. Don’t be afraid to take a rule template as a starting point and further refine it.

If you make additions to a rule template that you want to share, work with the original poster of the template to add your updates to the original template (posting a new template with only minor differences is against the marketplace rules).

Previous Introduction
Next: Blockly

I don’t see the wiki edit button at the moment, it might not have gotten enabled.

The UI editor has both the semantic tags field and the user generated tags field. I think it might be important to point out that, for the time being, semantic tags on rules are not really meaningful in teh way otehr semantic tags are and that the focus should be on the user entered tags.

I might argue that for many number items changed to 0, changed to 1, and changed to 100 % are common enough to be worth at least a mention.

The conditions in this yaml are not ordered in the build order above so your “first condition” is actually the second listed under conditions and id 5. This may prove confusing. Plus, this might be a good place to put a warning not to panic if the yaml appears reordered relative to the construction order of the rule.

I suggest analogizing this to the copy/paste technique used in the first two examples to make this point even more obvious.

I forgot to make it a wiki on this one. Should be there now.

I started to write that up but I couldn’t figure out the best way to say it so I decided to come back. It was slowing me down and I want to get something up in front of people as fast as possible. Now that it’s a wiki, if you have good wording please add it and we can word smith it from there.

The struggle I have is I don’t want to discourage the use of semantic tags necessarily but I also don’t want to go into na big paragraph’s long explanation that someday they may be used for something but today they aren’t so do what makes sense to you.

Only if it’s guaranteed to be an integer. 0 and 0.00000000000000123 are not equal. So I could see adding mention of Dimmers but I’m not sure I would encourage the use of Numbers here unless the user really knows what they are getting (in which case they don’t need us to tell them they can do it).

But the real reason I didn’t mention Numbers is because many users immediate jump to trying to use from state: >=50 and to state: < 50 which is, as we know, nonsense.

Weird, I wrote them based on the order they appeared in MainUI. I barely looked at the YAML. I just assumed that they would be listed in the YAML in the same order.

Definitely worth the mention.

That works for me.

Feel free to make what edits you can. I’ve already started the Blockly page and probably won’t get back here for edits until tomorrow.

Thanks for the feedback!

Looking more closely, the problem goes deeper than the one description. You clearly worked with the rule enough times between the first code screenshot and the second that they don’t match at all (id numbers of each component are different and the conditions are in a different order). I guess this must have something to do with how the UI now orders the json for text stability, but you’ll have to update one or the other screenshot.

I actually didn’t. I never actually edited the “real” rule. I started to create the triggers, conditions, and actions enough to show the Item selection dialog so I could screen grab it. But then I canceled out and showed the rule that I’ve already created (this is a live rule I use in my config).

Maybe it’d be better to create a new rule from scratch instead.

I almost did so but decided using one I already have would be faster. I guess not.

For now I’ll fake it. I’ll take a copy of the first rule, edit it in the code tab for the screen shot and leave it at that.

This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.