Using Built-in Handlers

Overview

The goal of this guide is to show simple and useful use cases of the automation system handlers via the Automation Built-in Handlers Demo. It contains 5 rules and each of them is designed to use a combination of different triggers, conditions and actions in order to show how to build useful rules.

There are rules which help us to save money from heating, to make our home more comfortable, or just to provide us with more free time.

All of the rules operate on items which can be found in most of the smart homes and to do things like:

• Close the blinds when there is too much light.
• Dim the bright lights when media is played.
• Turn off the heating every work day morning.
• Turn on the lights when at home after sunset.
• Water the lawn after sunset in the summer.

The rule definitions can be found in src/main/resources/OSGI-INF/automation/rules.

The functional items are defined in com.prosyst.mbs.demo.automation.builtin.handlers.items.

Trigger Handler Factories

Event Trigger

• UID: trigger.Event
• Description: Triggers when event is dispatched by Event Admin service.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  topicFilter	GENERIC	[java.lang.String]	Required	Event Topic Filter	Defines event topic filter.
  propertiesFilter	GENERIC	[java.lang.String]	Optional	Event Properties LDAP Filter	Defines event properties LDAP filter.

• Outputs:

  ID	Type	Classes	Required / Optional	Name	Description
  topic	GENERIC	[java.lang.String]	Required	Event Topic	Provides the dispatched event topic.
  properties	ANY	[java.util.Map, *]	Required	Event Properties	Provides the dispatched event properties.

The trigger.Event handler can be explored in the TurnOnLights.json file from the Automation Built-in Handlers Demo, placed in ../osgi/demo/com.prosyst.mbs.automation.builtin.handlers-demo/src/main/resources/OSGI-INF/automation/rules folder.

Sun Position Trigger

• UID: trigger.SunPosition
• Description: Triggers at time relative to sunrise or sunset.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  event	ENUM	[java.lang.String]	Required	Sun Event	Defines sun event – sunrise or sunset. Options: sunrise sunset
  offset	GENERIC	[java.lang.String]	Optional	Time Offset	Defines time offset, relative to sunset or sunrise. The format is '+/-HH:mm:ss'. Pattern: [+-]?(0?\d:|1[0-2]:)?[0-5]?\d:[0-5]?\d

The trigger.SunPosition handler can be explored in the WaterLawn.json file from the Automation Built-in Handlers Demo, placed in ../osgi/demo/com.prosyst.mbs.automation.builtin.handlers-demo/src/main/resources/OSGI-INF/automation/rules folder.

Repeating Time Trigger

• UID: trigger.RepeatingTime
• Description: Triggers on repeating time event.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  frequency	ENUM	[java.lang.String]	Required	Frequency	Defines repeating time events based on interval of minute, hour, day, week, month or year. Options: minutely hourly daily weekly monthly yearly
  seconds	NUMERIC	[java.util.Set, java.lang.Integer]	Optional	Seconds	Defines a set of seconds within a minute: Min: 0 Max: 59 Step: 1
  minutes	NUMERIC	[java.util.Set, java.lang.Integer]	Optional	Minutes	Defines a set of minutes within an hour: Min: 0 Max: 59 Step: 1
  hours	NUMERIC	[java.util.Set, java.lang.Integer]	Optional	Hours	Defines a set of hours of a day: Min: 0 Max: 23 Step: 1
  months	NUMERIC	[java.util.Set, java.lang.Integer]	Optional	Months	Defines a set of months of a year. Min: 1 Max: 12 Step: 1
  daysOfWeek	ENUM	[java.util.Set, java.lang.String]	Optional	Days of Week	Defines a set of days of a week. Options: Sunday Monday Tuesday Wednesday Thursday Friday Saturday
  daysOfMonth	NUMERIC	[java.util.Set, java.lang.Integer]	Optional	Days of Month	Defines a set of days of a month: Min: 1 Max: 31 Step: 1

The trigger.RepeatingTime handler can be explored in the TurnOffHeating.json file from the Automation Built-in Handlers Demo, placed in ../osgi/demo/com.prosyst.mbs.automation.builtin.handlers-demo/src/main/resources/OSGI-INF/automation/rules folder.

Item Property Changed Trigger

• UID: trigger.ItemPropertyChanged
• Description: Triggers rule on item property changed event.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  uid	GENERIC	[java.lang.String]	Optional	Item UID	Defines item UID for the filter.
  name	GENERIC	[java.lang.String]	Optional	Item Name	Defines item name for the filter.
  tags	GENERIC	[java.util.Set, java.lang.String]	Optional	Item Tags	Defines item tags for the filter.
  objectClass	GENERIC	[java.lang.String]	Optional	Item Object Class	Defines item object class for the filter.
  propertyName	GENERIC	[java.lang.String]	Required	Item Property Name	Defines item property name.
  attributes	ANY	[java.util.Map, *]	Optional	Item Attributes	Defines item attributes for the filter.

• Outputs:

  ID	Type	Classes	Required / Optional	Name	Description
  uid	GENERIC	[java.lang.String]	Required	Item UID	Provides Item UID.
  name	GENERIC	[java.lang.String]	Required	Item Name	Provides item name.
  tags	GENERIC	[java.util.Set, java.lang.String]	Required	Item Tags	Provides item tags.
  objectClass	GENERIC	[java.util.List, java.lang.String]	Required	Item Object Class	Provides item object classes.
  propertyName	GENERIC	[java.lang.String]	Required	Item Property Name	Provides item property name from property changed event.
  attributes	ANY	[java.util.Map, *]	Required	Item Attributes	Provides item attributes.
  newValue	ANY	[*]	Required	Item Property New Value	Provides item property new value from property changed event.
  oldValue	ANY	[*]	Required	Item Property Old Value	Provides item property old value from property changed event.

The trigger.ItemPropertyChanged handler can be explored in the CloseBlinds.json file from the Automation Built-in Handlers Demo, placed in ../osgi/demo/com.prosyst.mbs.automation.builtin.handlers-demo/src/main/resources/OSGI-INF/automation/rules folder.

Item Operation Executed Trigger

• UID: trigger.ItemOperationExecuted
• Description: Triggers rule on item operation executed event.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  uid	GENERIC	[java.lang.String]	Optional	Item UID	Defines item UID for the filter.
  name	GENERIC	[java.lang.String]	Optional	Item Name	Defines item name for the filter.
  tags	GENERIC	[java.util.Set, java.lang.String]	Optional	Item Tags	Defines item tags for the filter.
  objectClass	GENERIC	[java.lang.String]	Optional	Item Object Class	Defines item object class for the filter.
  operationName	GENERIC	[java.lang.String]	Required	Item Event Operation Name	Defines item event operation name.
  attributes	ANY	[java.util.Map, *]	Optional	Item Attributes	Defines item attributes for the filter.

• Outputs:

  ID	Type	Classes	Required / Optional	Name	Description
  uid	GENERIC	[java.lang.String]	Required	Item UID	Provides item UID.
  name	GENERIC	[java.lang.String]	Required	Item Name	Provides item name.
  tags	GENERIC	[java.util.Set, java.lang.String]	Required	Item Tags	Provides item tags.
  objectClass	GENERIC	[java.util.List, java.lang.String]	Required	Item Object Class	Provides item object classes.
  operationName	GENERIC	[java.lang.String]	Required	Item Operation Name	Provides item operation name from operation executed event.
  attributes	ANY	[java.util.Map, *]	Required	Item Attributes	Provides item attributes.

The trigger.ItemOperationExecuted handler can be explored in the DimLights.json file from the Automation Built-in Handlers Demo, placed in ../osgi/demo/com.prosyst.mbs.automation.builtin.handlers-demo/src/main/resources/OSGI-INF/automation/rules folder.

Condition Handlers

Sun Position Condition

• UID: condition.SunPosition
• Description: Satisfied between current and opposite sun event, including time offset.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  event	ENUM	[java.lang.String]	Required	Sun Event	Defines sun event – sunrise or sunset. Options: sunrise sunset
  offset	GENERIC	[java.lang.String]	Optional	Time Offset	Defines time offset, relative to sunset or sunrise. The format is '+/-HH.mm.ss'. Pattern: [+-]?(0?\d:|1[0-2]:)?[0-5]?\d:[0-5]?\d
  operation	ENUM	[java.lang.String]	Required	Operation	Defines when condition is satisfied –- before or after sunrise or sunset. Options: before after

The condition.SunPosition handler can be explored in the TurnOnLights.json file from the Automation Built-in Handlers Demo, placed in ../osgi/demo/com.prosyst.mbs.automation.builtin.handlers-demo/src/main/resources/OSGI-INF/automation/rules folder.

Script Condition

• UID: condition.Script
• Description: Satisfied by script expression
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  source	GENERIC	[java.lang.String]	Required	Source	Defines script path or expression. If there are expressions using a "context" binding, consider changing them accordingly, since this binding is going to be deprecated and removed soon.
  arguments	ANY	[*]	Optional	Arguments	Defines the script arguments.
  language	GENERIC	[java.lang.String]	Optional	Language	Defines which script engine will be used for execution.
  external	GENERIC	boolean	Optional	External	Defines if a source is a script path or an expression.

• Outputs

  ID	Type	Classes	Required / Optional	Name	Description
  result	ANY	[*]	Optional	Result	Provides the executed script result.

Comparator Condition

• UID: condition.Comparator
• Description: Satisfied by operation on left and right operands.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  operation	ENUM	[java.lang.String]	Required	Operation	Defines comparable operation. Options: = != < > <= >=
  leftOperand	ANY	[*]	Required	Left Operand	Provides left operand.
  rightOperand	ANY	[*]	Required	Right Operand	Provides right operand.

The condition.Comparator handler can be explored in the CloseBlinds.json and DimLights.json files from the Automation Built-in Handlers Demo, placed in ../osgi/demo/com.prosyst.mbs.automation.builtin.handlers-demo/src/main/resources/OSGI-INF/automation/rules folder.

Repeating Time Condition

• UID: condition.RepeatingTime
• Description: Satisfied by repeating time event.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  seconds	NUMERIC	[java.util.Set, java.lang.Integer]	Optional	Seconds	Defines a set of seconds within a minute: Min: 0 Max: 59 Step: 1
  minutes	NUMERIC	[java.util.Set, java.lang.Integer]	Optional	Minutes	Defines a set of minutes within an hour: Min: 0 Max: 59 Step: 1
  hours	NUMERIC	[java.util.Set, java.lang.Integer]	Optional	Hours	Defines a set of hours of a day: Min: 0 Max: 23 Step: 1
  months	NUMERIC	[java.util.Set, java.lang.Integer]	Optional	Months	Defines a set of months of year: Min: 1 Max: 12 Step: 1
  daysOfMonth	NUMERIC	[java.util.Set, java.lang.Integer]	Optional	Days of Months	Defines a set of days of month: Min: 1 Max: 31 Step: 1
  daysOfWeek	ENUM	[java.util.Set, java.lang.String]	Optional	Days of Week	Defines a set of days of week. Options: Sunday Monday Tuesday Wednesday Thursday Friday Saturday

The condition.RepeatingTime handler can be explored in the WaterLawn.json file from the Automation Built-in Handlers Demo, placed in ../osgi/demo/com.prosyst.mbs.automation.builtin.handlers-demo/src/main/resources/OSGI-INF/automation/rules folder.

Action Handlers

Item Get Property Action

• UID: action.ItemGetProperty
• Description: Gets Item property value.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  uid	GENERIC	[java.lang.String]	Optional	Item UID	Defines item UID for the filter.
  name	GENERIC	[java.lang.String]	Optional	Item Name	Defines item name for the filter.
  tags	GENERIC	[java.util.Set, java.lang.String]	Optional	Item Tags	Defines item tags for the filter.
  objectClass	GENERIC	[java.lang.String]	Optional	Item Object Class	Defines item object class for the filter.
  attributes	ANY	[java.util.Map, *]	Optional	Item Attributes	Defines item attributes for the filter.
  propertyName	GENERIC	[java.lang.String]	Required	Item Property	Defines item property name.

• Outputs:

  ID	Type	Classes	Required / Optional	Name	Description
  uid	GENERIC	[java.lang.String]	Required	Item UID	Provides item UID.
  name	GENERIC	[java.lang.String]	Required	Item Name	Provides item name.
  tags	GENERIC	[java.util.Set, java.lang.String]	Required	Item Tags	Provides item tags.
  objectClass	GENERIC	[java.util.List, java.lang.String]	Required	Item Object Class	Provides item object classes.
  attributes	ANY	[java.util.Map, *]	Required	Item Attributes	Provides item attributes.
  value	ANY	[*]	Required	Item Property Value	Provides item property value.

The action.ItemGetProperty handler can be explored in the DimLights.json file from the Automation Built-in Handlers Demo, placed in ../osgi/demo/com.prosyst.mbs.automation.builtin.handlers-demo/src/main/resources/OSGI-INF/automation/rules folder.

Item Invoke Operation Action

• UID: action.ItemInvokeOperation
• Description: Executes items operation.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  uid	GENERIC	[java.lang.String]	Optional	Item UID	Defines UID for the filter.
  name	GENERIC	[java.lang.String]	Optional	Item Name	Defines item name for the filter.
  tags	GENERIC	[java.util.Set, java.lang.String]	Optional	Item Tags	Defines item tags for the filter.
  objectClass	GENERIC	[java.lang.String]	Optional	Item Object Class	Defines item object class for the filter.
  attributes	ANY	[java.util.Map, *]	Optional	Item Attributes	Defines item attributes for the filter.
  operationName	GENERIC	[java.lang.String]	Required	Item Operation	Defines item operation name
  arguments	ANY	*[]	Optional	Item Operation Arguments	Defines array of arguments.

• Outputs:

  ID	Type	Classes	Required / Optional	Name	Description
  uid	GENERIC	[java.lang.String]	Required	Item UID	Provides item UID.
  name	GENERIC	[java.lang.String]	Required	Item name	Provides item name.
  tags	GENERIC	[java.util.Set, java.lang.String]	Required	Item Tags	Provides item tags.
  objectClass	GENERIC	[java.util.List, java.lang.String]	Required	Item Object Class	Provides item object class.
  attributes	ANY	[java.util.Map, *]	Required	Item Attributes	Provides item attributes.
  result	ANY	[*]	optional	Item Operation Result	Provides the item operation result.

The action.ItemInvokeOperation handler can be explored in the CloseBlinds.json , TurnOffHeating.json, TurnOnLights.json, and in the WaterLawn.json files from the Automation Built-in Handlers Demo, placed in ../osgi/demo/com.prosyst.mbs.automation.builtin.handlers-demo/src/main/resources/OSGI-INF/automation/rules folder.

History Remove Entry Action

• UID: action.HistoryRemoveEntry
• Description: Removes history entry.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  startId	NUMERIC	[long]	Optional	Query Start Identifier	Defines the selection first entry unique identifier, inclusive. Min: -9223372036854775808 Max: 9223372036854775807 Step: 1
  endId	NUMERIC	[long]	Optional	Query End Identifier	Defines the selection last entry unique identifier, inclusive. Min: -9223372036854775808 Max: 9223372036854775807 Step: 1
  startTime	NUMERIC	[long]	Optional	Query Start Time	Defines the selection start time, inclusive. Min: -9223372036854775808 Max: 9223372036854775807 Step: 1
  endTime	NUMERIC	[long]	Optional	Query End Time	Defines the selection end time, inclusive. Min: -9223372036854775808 Max: 9223372036854775807 Step: 1
  limit	NUMERIC	[int]	Optional	Query Limit	Defines maximum number of entries to be removed. Min: 1 Max: 2147483647 Step: 1
  namespaceFilter	GENERIC	[java.lang.String]	Required	Query Namespace Filter	Defines history entries namespace filter. It can start with a prefix and end with *.
  tokensFilter	GENERIC	[java.lang.String]	Optional	Query Tokens Filter	Defines the tokens LDAP filter of the removed entries.
  orderBy	ENUM	[java.lang.String[]]	Optional	Query Order By	Defines the order by the option of the removed entries: Options: ID ascending ID descending timestamp ascending timestamp descending namespace ascending namespace descending

Item Set Property Action

• UID: action.ItemSetProperty
• Description: Executes items set property operation.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  uid	GENERIC	[java.lang.String]	Optional	Item UID	Defines item UID for the filter.
  name	GENERIC	[java.lang.String]	Optional	Item Name	Defines item name for the filer.
  tags	GENERIC	[java.util.Set, java.lang.String]	Optional	Item Tags	Defines item tags for the filter.
  objectClass	GENERIC	[java.lang.String]	Optional	Item Object Class	Defines item object class for the filter.
  attributes	ANY	[java.util.Map, *]	Optional	Item Attributes	Defines item attributes for the filter.
  propertyName	GENERIC	[java.lang.String]	Required	Item Property	Defines item property name
  value	ANY	[*]	Required	Item Property Value	Defines item property value.

• Outputs:

  ID	Type	Classes	Required / Optional	Name	Description
  uid	GENERIC	[java.lang.String]	Required	Item UID	Provides item UID.
  name	GENERIC	[java.lang.String]	Required	Item Name	Provides item name.
  tags	GENERIC	[java.util.Set, java.lang.String]	Required	Item tags.	Provides item tags.
  objectClass	GENERIC	[java.util.List, java.lang.String]	Required	Item Object Class	Provides item object classes.
  attributes	ANY	[java.util.Map, *]	Required	Item Attributes	Provides item attributes.

The action.ItemSetProperty handler can be explored in the DimLights.json file from the Automation Built-in Handlers Demo, placed in ../osgi/demo/com.prosyst.mbs.automation.builtin.handlers-demo/src/main/resources/OSGI-INF/automation/rules folder.

Script Action

• UID: action.Script
• Description: Executes script action.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  source	GENERIC	[java.lang.String]	Required	Source	Defines the script path or expression. If there are expressions using a "context" binding, consider changing them accordingly, since this binding is going to be deprecated and removed soon.
  arguments	ANY	[*]	Optional	Arguments	Defines the script arguments.
  language	GENERIC	[java.lang.String]	Optional	Language	Defines which script engine will be used for execution.
  external	GENERIC	boolean	Optional	External	Defines if the source is a script path or an expression.

• Outputs:

  ID	Type	Classes	Required / Optional	Name	Description
  result	ANY	[*]	Optional	Result	Provides the executed script result.

History Add Entry Action

• UID: action.HistoryAddEntry
• Description: Adds history entry.
• Inputs:

  ID	Type	Classes	Required / Optional	Name	Description
  value	ANY	[*]	Required	History Entry Value	Defines history entry values.
  timestamp	NUMERIC	[long]	Optional	History Entry Timestamp	Defines the timestamp when this entry is added. Min: -9223372036854775808 Max: 9223372036854775807 Step: 1
  namespace	GENERIC	[java.lang.String]	Required	History Entry Namespace	Defines history entry namespace. Pattern: [a-zA-Z0-9_.-]+(\/[a-zA-Z0-9_.-]+)*
  tokens	GENERIC	[java.util.Map, java.lang.String]	Optional	History Entry Tokens	Defines the tokens as a Map<String, String> of the new entry.

• Outputs:

  ID	Type	Classes	Required / Optional	Name	Description
  id	NUMERIC	[long]	Required	History Entry Identifier	Provides the added entry unique identifier. Min: -9223372036854775808 Max: 9223372036854775807 Step: 1