Design Pattern: Associated Items

Tags: #<Tag:0x00007f212a377ad8> #<Tag:0x00007f212a377970>

(Rich Koshak) #1

Please see Design Pattern: What is a Design Pattern and How Do I Use Them for how to read and use DPs.

Problem Statement

Often one will have a number of separate Items which are all related to each other in some way. For example, one might have a Contact on a door and a DateTime to represent when the last time the door was opened. This is easy enough to keep track of if there are only one or two such Items, but if one has a lot of similar Items or is using a lot of genetically coded rules where one cannot hard code the names of the associated Items inside the rule mapping between the Items becomes difficult.


Name Items that are associated with each other such that given the name of one Item the names of the other Items can be created with just a little bit of String manipulation. With the associated Item’s name, one can get a reference to that Item by pulling it out of a Group’s members using the findFirst method. Or one can pull it out of the Item registry directly.


postUpdate Action

In this example there are two door Contacts and two associated DateTime Items to store the last time the Door was opened or closed. A Rule triggers when one of the Contacts is updated and update the associated DateTime Item.


Group gDoors:Contact

Contact Front "Front Door" <frontdoor> (gDoors)

DateTime Front_LastUpdate "Front Door Last Update [%1$tm/%1$td %1tH:%1tM]" <clock> 

Contact Back "Back Door" <frontdoor> (gDoors)

DateTime Back_LastUpdate "Back Door Last Update [%1$tm/%1$td %1tH:%1tM]" <clock> 


rule "A Door's State Changed"
    Member of gDoors changed
    if(previousState == NULL) return;
    postUpdate("_LastUpdate", now.toString)

Theory of Operation

The Rule gets triggered when any member of gDoors changes. If the door changed from NULL we don’t care about this change so we exit the Rule. We then use the name of the door Item to create the LastUpdate Item’s name and send it and update with now.toString.

The key is the Item’s names and the line:

postUpdate("_LastUpdate", now.toString)

Note: This is one of the few examples where the postUpdate Action is recommended for us.

Group findFirst

In this example there are a bunch of Items that represent the online/offline status of devices and network services. When any of these Items change state to offline, generate an alert and set a flag indicating that the Item went offline. When that Item comes back online generate an alert and reset the flag. Use a timer to avoid flapping.


Group:Switch:AND(ON, OFF) gSensorStatus "Sensor's Status [MAP(]"

Group:Switch gOfflineAlerted

Switch vNest_Online "Nest Status [MAP(]"
    <network> (gSensorStatus)
    { nest="<[thermostats(Entryway).is_online]" }

Switch vNest_Online_Alerted (gOfflineAlerted)

Switch vNetwork_Cerberos "Cerberos Network [MAP(]"
  <network> (gSensorStatus, gResetExpire)
  { channel="network:servicedevice:cerberos:online", expire="2m" }

Switch vNetwork_Cerberos_Alerted (gOfflineAlerted)

// Dozens more Item pairs


import java.util.Map

val Map<String, Timer> timers = newHashMap

rule "A sensor changed its online state2"
    Member of gSensorStatus changed
    if(previousState == NULL) return;

    var n = transform("MAP", "",
    val name = if(n == "") else n

    // val alerted = gOfflineAlerted.members.findFirst[ a | =="_Alerted"] as SwitchItem
    val alerted = ScriptServiceUtil.getItemRegistry.getItem("_Alerted") as SwitchItem
    if(alerted === null) {
        logError("admin", "Cannot find Item " +"_Alerted")
        aInfo.sendCommand( + " doesn't have an alerted flag, it is now " + transform("MAP", "", triggeringItem.state.toString) + "!")

    // If we are flapping, reschedule the timer and exit
    if(timers.get( !== null) {
        logWarn("admin", name + " is flapping!")

    // If alerted == OFF and triggeringItem == OFF then sensor went offline and we have not yet alerted
    // If alerted == ON and triggeringItem == ON then the sensor came back online after we alerted that it was offline
    if(alerted.state == triggeringItem.state) {
        val currState = triggeringItem.state
        // wait one minute before alerting to make sure it isn't flapping
        timers.put(, createTimer(now.plusMinutes(1), [ |
            // If the current state of the Item matches the saved state after 5 minutes send the alert
            if(triggeringItem.state == currState) {
                aInfo.sendCommand(name + " is now " + transform("MAP", "", triggeringItem.state.toString) + "!")
                alerted.postUpdate(if(currState == ON) OFF else ON)
            timers.put(, null)

Theory of Operation

If the sensor changed from NULL we don’t care so immediately return.

Get the friendly name for the Item.

Use the findFirst method to pull the associated Alerted Item from gOfflineAlerted based on the name of the triggeringItem. If the Item doesn’t exist, log the error and send an alert to indicate the configuration error (i.e. missing Alerted Item) and exit.

If there is already a timer set for this triggeringItem reschedule the timer.

If the alerted Item’s state equals the triggeringItem’s state it means we need to alert. Create a five minute timer. If after five minutes the triggeringItem has remained unchanged send an alert.

The keys are the Item’s names and the line

val alerted = ScriptServiceUtil.getItemRegistry.getItem("_Alerted") as SwitchItem

Item Registry

Many thanks and full credit goes to @5iver for discovering this option. We can access Items from the Item registry directly using the ScriptServiceUtil.

In this example we have a Rule that turns on/off some lights depending on whether the weather says it is cloudy or not.


Switch vIsCloudy // set to ON when the weather says it is cloudy
String vTimeOfDay // represents the current time of day

Group gLights_ON_WEATHER // Group of lights to turn on when it is cloudy


import org.eclipse.smarthome.model.script.ScriptServiceUtil

// Thoery of operation: If it is day time, turn on/off the weather lights when cloudy conditions
// change. Trigger the rule when it first becomes day so we can apply cloudy to lights then as well.
rule "Turn on lights when it is cloudy"
    Item vIsCloudy changed or
    Item vTimeOfDay changed to "DAY"
    // We only care about daytime and vIsCloudy isn't NULL
    if(vTimeOfDay.state != "DAY" || vIsCloudy.state == NULL) return;

    // give the side effects of time of day time to complete
    if( == "vTimeOfDay") Thread::sleep(500)

    logInfo("lighting", "It is " + vTimeOfDay.state.toString + " and cloudy changed: " + vIsCloudy.state.toString +", adjusting lighting")

    // Apply the cloudy state to all the lights in the weather group
    gLights_ON_WEATHER.members.forEach[ SwitchItem l |

        val overrideName ="_Override"
        val override = ScriptServiceUtil.getItemRegistry.getItem(overrideName)

        if(override.state != ON && l.state != vIsCloudy.state) l.sendCommand(vIsCloudy.state as OnOffType)
        if(override.state == ON) logInfo("lighting", + " is overridden")

The keys are the Item’s name and the lines:

import org.eclipse.smarthome.model.script.ScriptServiceUtil
    val override = ScriptServiceUtil.getItemRegistry.getItem(overrideName)

Advantages and Disadvantages


  • Allows for the creation of very generic Rules
  • Allows for the addition and subtraction of Items that get processed by a given Rule using Group membership


  • Generates a proliferation of Items
  • Constrains Item naming schemes

Related Design Patterns

Design Pattern How It’s Used
[Rules DSL] Get item from string name! Source for the Item Registry Example
Design Pattern: Unbound Item (aka Virtual Item) Most associated Items are Unbound Items
Design Pattern: Working with Groups in Rules More examples of findFirst and forEach and other Group manipulations
Design Patterns: Generic Is Alive The Group findFirst example is a specific implementation of this DP
Design Pattern: Motion Sensor Timer The anti-flapping timer in the Group findFirst example is a specific implementation of this DP
Design Pattern: Human Readable Names in Messages Used in the Group findFirst example to transform the Item name to a more human readable name for logs and alerts.
Design Pattern: Separation of Behaviors Alerting implementation in Group findFirst and the setting of vIsCloudy in the Item Registry example
Design Pattern: Time Of Day Used to calculate the time of day in the Item Registry example

Design Pattern: Working with Groups in Rules
Whole house lighting
How can I build a dynamic Item name for itemValue?
OpenHAB 2.0 Rules: Create list of HSBTypes
Design Pattern: Human Readable Names in Messages
2 items in one line
Lambda functions fail (not thread safe?)
Convert String to Item
Rule which iterates through group(s) of similar items
Rule which iterates through group(s) of similar items
Rule which iterates through group(s) of similar items
[Loxone Binding] Update of Openhab item, does not update Loxone item, Why?
Timers in functions not possible?
Groups ... if state in group1 execute action in group2
How does OH know the state of a switch?
Design Pattern : Expire Binding based Countdown timer
Http1 binding using a base url
Setting up a cron based sprinkler
Creating rules: how to make them general ? Shoudl I use proxy-items, or variables?
Rule to calculate pump filtration time depending on temperature
Help shortening one of my persistence rules
Way to save system settings
Help with RPI Openhab full hang. (WAS Rule for longest ever uptime?)
Combining similar rules
Automatic lighting control without timers
Xtend Scripts vs JSR223?
Xtend Scripts vs JSR223?
Determine Object type in a Group (Dimmer or Switch)
Please test the new Expire Binding
[SOLVED] Question on the sendCommand()
Advice - New home, fresh install via Docker, fresh start
Item values and logical ranges at updates
Openhab 2 Contact Sensor Time Rule
Help me condense this rule
How I have automated my lights
Rules triggering at Group-Change of an Item
Feedback from a new openHAB(ian) user
Rules stop executing after a while
Issue with final parameters when using lambda to create "function"
What are your top 3 automations
Rule for Rollershutters - with proxy items and reed-contacts
Inactivity of items // no updates // automatically tracking
Lambda in rule fails with 'Error during the execution of rule '{RuleName}': null'
[SOLVED] Close Rollershutters when sun shines using groups
Generic rule to display last sensor update time
Lambda Procedure error: java.lang.NullPointerException
A More Clever System for "Locking" Lights?
Turning off devices based on Presence
How to make rules easy?
Help with better HVAC rule design
3 different methods to use scenes with Google Home & openHAB
Consolidation help
Cancel timer doesn`t work
Use an string item state as a name and state for another item
Suggestion for controlling my underfloor heating, Roth Touchline
Use variable for item
Cron Heating Rules
Alarm Notification "only" for the First OFF
Roku Support
Design Pattern: Gate Keeper
Intergas Incomfort Lan2RF rules
Open the closed Rollershutter after Window opens
Rule optimization: Window OPEN reminder
Monoprice 6-zone Audio amp items, sitemap & rules
Simplifying Rule
Squeezebox Player WIP (Help Appreciated)
Array of type switch
Light switches
Make my rule files shorter --> working with groups
Iterating over a group, want to check an alternate item, sometimes
How to have a history of commands in Basic UI
Setting light themes in rules
Taking A Rule To The Next Level
Design Pattern: Encoding and Accessing Values in Rules
How to store additional info in ITEM?
Type Conversions
Openhab.log goes crazy
Create a custom Item
Looking for optimal datastructure
JSR223 Jython Openhab Imports Erroring?
Match name of similiar items in two different groups
MQTT device initial state checking
YAGSA - Yet Another Group Structure Approach
Wildcard for Group.members.filter - Use String Patterns and ConfigItems
"First Time" Rule
Fire Rule when groupmember receives command
Best practice for .rules
Persistence query in habpanel
How to create a complex light status check rule?
reelyActive Smart Spaces Revisited
Basic switch questions, clarification about returned value
Design Pattern: Manual Trigger Detection
Notifications in group design pattern
How to model location of an item?
Item or Variable Name with Variable as part of the name
Design Pattern: Cascading Timers
Time and temperature spreadsheet schedule
No working trigger functions openHAB 2.1
Rule not working anymore
Switch with 2 SendCommand actions
Style Guide for openHAB?
MQTT long press design pattern (dimmer)
Alert when item in a group has not been updated for x hours?
How to check if an item exists?
Identify itemname based on part of a name
Unable to get DateTime to work
Lambda calling other lambda?
Help Needed: sendCommand not working with arrayList of String
Construct Other Item Names from another
Current and Correct Documentation of Syntax for Things and Items Needed
An Approach for Better Light Timers
Automation/Orchestration Design Patterns
Individual Alarm clock for each Day of week, with adjustable duration
Arrays in Openhab 1.8.3
Set last tripped/alarm date, or last action date to an item - best practice?
Set last tripped/alarm date, or last action date to an item - best practice?
Return to earlier state
Send Modbus Data to File
Delay on item action exec binding
Add a property to a item or type
Make rule with 196 if-statements more generic
Generic Presence Detection
Creating "mode switches" for seasonal activities
Finally not called -> deadlock
Roadmap to Happiness - What is missing in the core framework
Roadmap to Happiness - What is missing in the core framework
Hot Tank monitoring, with energy calculations
Getting rule name in rule
Basics of a Lambda expression
[SOLVED] Can't set NEST structure away in OH2.3
[SOLVED] Groupping items properly
Arrays as Global Variables
Displaying time since last update of an item
Using part of an item's name to reference another item in a rule
Combine number and rollershutter items into a single item for use with rule?
( ) #2

Nice! I did not know that’s possible… or at least I didn’t know how. That would totally simplify one workaround I have in my setup. Thanks

(Ben Jones) #3

I wasn’t aware of this item.lastUpdate, is that an OH2 only thing?

(Rich Koshak) #4

It’s been around as long as I’ve been using OH so at least since 1.6. It’s one of the standard persistence methods on all Items along with maxSince, minSince, previousState, etc. See the “Persistence Extensions in Scripts and Rules” section of the [Persistence wiki page](Persistence Extensions in Scripts and Rules).

If you don’t have persistence setup for the Item it returns null though.

(Ben Jones) #5

Great - learning every day! Thanks @rlkoshak. Does it work with any persistence, i.e. MapDB, or just historical based stuff like InfluxDB?

(Rich Koshak) #6

It works for any queryable persistence so MapDB yes as well as InfuxDB et al but not with write only persistence services like MQTT or my.openhab.

I primarily use lastUpdate with MapDB myself.

(Ben Jones) #7

Great stuff - thanks again, and thanks for your very useful tutorials on rule design patterns. I am sure many are gaining a lot of value from these.

(Tomme) #8

Thank you for your very helpful post about associated items!
I am now trying to create a generic rule that works for any room in the house but I have one problem:
I want to use a Timer in that rule. You showed how to get an Item by name that had been defined in an Items file before (ie DateTime). But I cannot define a Timer in an Items file nor is it possible to add a Timer to a group programmatically (?).
I do not want to use a single hard coded timer variable that is shared between all rooms because it might be the case that multiple timers are active at the same time.
Any suggestions how I could solve this?

(Rich Koshak) #9

That is correct.

Create a hashMap of Timers using the Item name as the key.

import java.util.Map

val Map<String, Timer> timers = newHashMap

rule "Rule that creates some Timers"
    Item MyGroup received update // or whatever
    val i = blah blah blah // what ever you do to get the Item

    val Timer t = timers.get(
    if(t == null) {
        timers.put(, createTimer(now.plusMinutes(1), [|
            // do timer stuff
            timers.put(, null)
    else {

(Dries) #10

I’m currently struggling with a rule. The rule needs to be triggered by any item in a specific group. So the trigger is similar as in your example.

However, in your example, the rule processes all items in that group. I would like my rule only to do stuff with the single item that was triggered.

So how do I identify the item (in group gDoors in your example) that triggered the rule?


I may have found a solution, not sure if it is “best practice”, but initial tests seem to point out it is reliable.

    Item gRaamcontact received update
	val LastWindowContact = gRaamcontact.members.sortBy[lastUpdate].last
	logInfo("Window","Last contact =" + LastWindowContact)

I’m not sure if it is always reliable when 2 contacts are changed at the same time…


(Rossko57) #11

It’s worth looking further in the Tutorials & Example forum section

(Rich Koshak) #12

Depending on the speed of your persistence you man need to add a sleep before the sortby.

It isn’t a best practice so much as the only way to do it in this case. The alternative is one rule per switch which each call a lambda.

(Dries) #13

Thank you both.

I thought I had read all the rule-tutorials by now, I guess I missed that one.

@rlkoshak: So far I didn’t had any persistence-issues. I guess my mapDB is fast enough. I just added a small sleep just to be sure (100ms). I didn’t want to make it too big, because then the chance of two contacts being changed at the same time will increase.

(Luke Corkill) #14

I’ve been working through a few of the Design Pattern articles - they’re helping me get a better understanding of Openhab2. Thank-you for taking the time to write them up.

I have been trying to add the LastUpdate feature to my setup, using this as a guide. I think I’m nearly there, but I get an error at the assocDT.postUpdate(new DateTimeType(door.lastUpdate)) stage;
This gives the output (full detail further below)

2017-07-02 18:40:24.019 [ERROR] [.script.engine.ScriptExecutionThread] - Rule 'A Door's State Changed': Could not invoke constructor: org.eclipse.smarthome.core.library.types.DateTimeType.DateTimeType(java.lang.String)

The code I am using is very similar to the original post in this article (and the associated one on persistence), with a few log lines for debugging and a temporary workaround for Groups following a recent OH update: Groups seem to be broken

2017-07-02 18:32:47.040 [INFO ] [rthome.model.script.associated items] - Door state change rule started
2017-07-02 18:32:47.190 [INFO ] [rthome.model.script.associated items] - dtStr = testDoor_LastUpdate
2017-07-02 18:32:47.215 [INFO ] [rthome.model.script.associated items] - assocDT = testDoor_LastUpdate (Type=DateTimeItem, State=NULL, Label=test Door Last Update, Category=clock, Groups=[gDoorsLastUpdate])
2017-07-02 18:32:47.279 [INFO ] [rthome.model.script.associated items] - door.lastUpdate = 2017-07-02T18:32:46.000+01:00
2017-07-02 18:32:47.330 [ERROR] [.script.engine.ScriptExecutionThread] - Rule 'A Door's State Changed': Could not invoke constructor: org.eclipse.smarthome.core.library.types.DateTimeType.DateTimeType(java.lang.String)

Key snippets below - wondering if anyone can suggest how to fix?;

From .rules


val logName = "associated items"

rule "A Door's State Changed"
    Item gDoors received update // NOTE: the rule will trigger multiple times per event
        logInfo(logName, "Door state change rule started")
        gDoors.members.forEach[door |
        // Get the associated DateTime Item
        val dtStr = + "_LastUpdate"
        val assocDT = gDoorsLastUpdate.members.filter[dt| == dtStr].head as DateTimeItem
        logInfo(logName, "dtStr = " + dtStr)
        logInfo(logName, "assocDT = " + assocDT )
        logInfo(logName, "door.lastUpdate = "+ door.lastUpdate)

        // Update assocDT with the door's lastUpdate
        assocDT.postUpdate(new DateTimeType(door.lastUpdate))


from .items


Group:Contact  gDoors                           // temporary workaround following recent OH update:
Group gDoorsLastUpdate

Contact  testDoor               "test Door"                             <frontdoor>     (gDoors,GarageDoorGroup,gHistory,gNewDoorGroup)   {mqtt="<[mysensorsMQTT:mysensors/in/100/2/1/0/16:state:MAP(]"}
DateTime testDoor_LastUpdate    "test Door Last Update [%1$tm/%1$td %1tH:%1tM]" <clock> (gDoorsLastUpdate)

This gives the output:

2017-07-02 18:40:23.807 [INFO ] [rthome.model.script.associated items] - Door state change rule started
2017-07-02 18:40:23.952 [INFO ] [rthome.model.script.associated items] - dtStr = testDoor_LastUpdate
2017-07-02 18:40:23.970 [INFO ] [rthome.model.script.associated items] - assocDT = testDoor_LastUpdate (Type=DateTimeItem, State=NULL, Label=test Door Last Update, Category=clock, Groups=[gDoorsLastUpdate])
2017-07-02 18:40:23.996 [INFO ] [rthome.model.script.associated items] - door.lastUpdate = 2017-07-02T18:40:23.000+01:00
2017-07-02 18:40:24.019 [ERROR] [.script.engine.ScriptExecutionThread] - Rule 'A Door's State Changed': Could not invoke constructor: org.eclipse.smarthome.core.library.types.DateTimeType.DateTimeType(java.lang.String)

To be honest I understand enough of the syntax for the assocDT.postUpdate to work out what’s causing the error.

Any ideas on how to fix, or dig deeper into the logs?



(Rich Koshak) #15

lastUpdate returns a Joda DateTime object. You can not update a DateTimeItem with a Joda DateTime object. You either need to create a new DateTimeType using the last update.millis or you can try using door.lastUpdate.toString in your call to postUpdate. I think the default toString is the right format for OH to parse it into a DateTimeType.

(Luke Corkill) #16

Thanks the .toString seems to be working

(Kees Van Gelder) #17

Recently I wondered what more goodies OH had in store to surprise me with.
I think you just showed one. This is totally useful and will apply on many things other than just door updates. Thanks

(rzylius) #18

Great article.

Could you advise how your design proposal could work if I need to use pairs of objects. Like temperature measuring (room_temp) and target temperature (room_target_temp)? if I have 8 rooms, I would like to have a rule iterating every room and comparing corresponding room temperature with target temperature.


(Rich Koshak) #19

Just like you describe. Just make sure you can name the Items in such a way that you can easily reconstruct the name of the associated Items using the name of the Item you are iterating over.

So, if you have a Bedroom_Temp name the associated Item Bedroom_Temp_Target and your loop would look something like:

Rooms.members.forEach[room |
    val target = TargetTemps.members.findFirst[room | == + "_Target"]

(rzylius) #20

Thank you, Rich, makes perfect sense! as I understand in two loops the name variable “room” should not duplicate, so updated:

Rooms.members.forEach[room |
val target = TargetTemps.members.findFirst[r | == + “_Target”]