Migrating from Automation ESH API

The following guide provides information on how to migrate from the deprecated Automation ESH API to the new Automation API.

Bundles List

The following table contains all bundles included in the new Automation module and the way they are mapped to the ESH bundles:

ESH Bundle Symbolic Name	Replacement Bundle Symbolic Name	Description
com.prosyst.mbs.automation.esh.api, org.eclipse.smarthome.automation.api	com.prosyst.mbs.automation.api	The Automation API Bundle exports the API of the new Automation module. It is replacement of the Automation ESH SmartHome API.
com.prosyst.mbs.automation.esh.commands	com.prosyst.mbs.automation.commands	The Automation Console Commands bundle provides the console commands of the new Automation module. It is replacement of the Automation ESH SmartHome Console Commands.
com.prosyst.mbs.automation.esh.core, org.eclipse.smarthome.automation.core, com.prosyst.mbs.automation.esh.storage, org.eclipse.smarthome.automation.parser.gson, org.eclipse.smarthome.automation.provider org.eclipse.smarthome.automation.provider.file	com.prosyst.mbs.automation.core	The Automation Core bundle implements a rule engine and AutomationAdmin service which are part of the new Automation module. The RuleAdmin, ModuleTypeAdmin, TemplateAdmin, RuleRegistry, ModuleTypeRegistry and TemplateRegistry services, that are part of the Automation ESH module, are replaced by the AutomationAdmin service. The Automation Core bundle implements persistent storage for the Rules and Templates added through the AutomationAdmin service. It implements also a JSON parser for Rules and Templates. Module Types are not provided by JSON resources anymore. The parser is used by the bundle resource tracker and the file resource tracker that track the JSON resources and add them automatically to the AutomationAdmin.
com.prosyst.mbs.automation.esh.handler.core, com.prosyst.mbs.automation.esh.handler.item	com.prosyst.mbs.automation.handler.core	The Automation Handler Core bundle contains handlers related to the Functional Items. They give opportunity to check and change properties of the Functional Items and to invoke Functional Item operations. It also contains handlers related to any events – time, Sun or others.
com.prosyst.mbs.automation.esh.handler.script	com.prosyst.mbs.automation.handler.script	The Automation Handler Script bundle contains handlers related to Scripting module. They give opportunity to Automation module to execute user-defined scripts.
	com.prosyst.mbs.automation.handler.history	The Automation Handler History bundle contains handlers related to History module. They give opportunity to Automation module to add and remove history entries.
com.prosyst.mbs.automation.esh.inventory	com.prosyst.mbs.automation.inventory	The Automation Inventory bundle provides API implementation for the Apache Felix Inventory Printer Framework. It is replacement of Automation ESH Inventory bundle.
com.prosyst.mbs.automation.esh.rest.api		The Automation ESH REST API bundle hosts common JAX-RS annotated interface mappings for the functional items management. RESTful Web Service to be shared between Bosch IoT Gateway Software and RM implementation. There is no replacement of this bundle. The new Automation module uses FIM RESTful Web Service and Automation Admin Functional Item operations.
com.prosyst.mbs.automation.esh.webconsole	com.prosyst.mbs.automation.webconsole	The Automation Web Plugin bundle provides web interface for listing rules, handlers and templates; managing rules and templates. It is replacement of Automation ESH Plugin bundle.

Automation Naming Convention

All UIDs and IDs should match to the regular expression:
"[a-zA-Z0-9._-]+"

If there is a rule or template that has a UID that does not match, it should be modified manually to correspond to this requirement, before the backup to be performed.
Wherever there is a need of a namespace definition, it should match to the regular expression:
"[a-zA-Z0-9._-]+(/{1}[a-zA-Z0-9._-]+)*"

Backup / Restore

Backup/restore procedure is supported for the persisted Automation ESH resources – rules and templates. After restore, they will be fully functional without any changes, as long as they do not contain composite modules. Composite module types are not supported anymore. If the rules or templates have such types, these composite modules should be manually replaced by those participating in the composite module type, before the backup to be performed.
The templates provided by bundles are not persisted, but they will be loaded automatically if they are rewritten in the newly supported JSON format as follows:

The rules:
- actions and conditions are merged in flow. To keep the behavior of the rule, put in flow all conditions in the order in which they were in the original rule, followed by all actions in the order in which they were in the original rule.
- visibility is removed
The modules:
- type -> handlerUID
- label -> name
- configuration and inputs are merged in bindings
The templates:
- label -> name
- configDescriptions -> variables
- actions and conditions are merged in flow. Like in the rules, add the conditions, followed by the actions, keeping the order from the original template.
- visibility is removed
The variables(configDescriptions):
- name -> id
- type has new values – GENERIC, NUMERIC, ENUM, BEAN, ANY; Strings and Booleans become GENERIC, Integers and Decimals become NUMERIC, these with options become ENUM, all other should be split between BEAN and ANY.
- there is a new one – classes, its value is a list with names of the class and its containers – refer to the containers defined by the java.util package. The last element in the list is the class name of the type which meta-data is specified. The elements can be any of the supported Functional Item types. For example, if the type is NUMERIC, the class can be:
  - primitive(int) – the classes contains one element from type "int"
  - array with primitive(int) elements – the classes contains one element "int[]"
  - array with strings– the classes contains one element "java.lang.String[]"
  - Integer element – the classes contains one element "java.lang.Integer"
  - a list with Integer elements – the classes contains two elements "java.util.List" and "java.lang.Integer", listed in this order
  - a list with array with Integer elements – the classes contains two elements "java.util.List[]" and "java.lang.Integer", listed in this order
  - a map with a list with Integer elements – the classes contains three elements "java.util.Map", "java.util.List" and "java.lang.Integer", listed in this order
- groupName -> namespace, it should match to the regular expression:
"[a-zA-Z0-9._-]+(/{1}[a-zA-Z0-9._-]+)*"
- label -> name
- options has new value – list of strings
- readOnly, multiple, multipleLimit, unit, unitLabel, defaultValue, filterCriteria, limitToOptions, advanced, verify are removed

All other JSON fields remain the same.

If any of the templates has module from Item Property Condition module type, this module should be split into two modules in the following sequence:

Item Get Property action and
Comparator condition

The Item Property Condition module type is not supported anymore.

3. The rules provided by bundles are persisted and will be restored with the backup/restore procedure.

Module Types

All custom Module Types should be refactored to implement com.prosyst.mbs.services.automation.Handler and corresponding other interface from com.prosyst.mbs.services.automation.handler package. The module type json files will not be parsed anymore. The Module Types should be registered as OSGi services. In this way the Automation Admin can track them under the corresponding Handler interface:

ESH Class/Interface	Replacement Class/Interface	Description
org.eclipse.smarthome.automation.type.ModuleType	com.prosyst.mbs.services.automation.Handler	common for all handlers
org.eclipse.smarthome.automation.type.ActionType	com.prosyst.mbs.services.automation.Handler	common for all handlers
org.eclipse.smarthome.automation.type.ConditionType	com.prosyst.mbs.services.automation.Handler	common for all handlers
org.eclipse.smarthome.automation.type.TriggerType	com.prosyst.mbs.services.automation.Handler	common for all handlers
com.prosyst.mbs.services.automation.items.ModuleTypeInfo	com.prosyst.mbs.services.automation.Handler	common for all handlers
org.eclipse.smarthome.automation.handler.ModuleHandler	com.prosyst.mbs.services.automation.Handler	common for all handlers
org.eclipse.smarthome.automation.handler.ActionHandler	com.prosyst.mbs.services.automation.handler.ActionHandler	used as action handler for concrete module type, handles all modules from this type
org.eclipse.smarthome.automation.handler.ConditionHandler	com.prosyst.mbs.services.automation.handler.ConditionHandler	used as condition handler for concrete module type, handles all modules from this type
org.eclipse.smarthome.automation.handler.TriggerHandler	java.lang.AutoCloseable	used as trigger handler, each trigger has its own personal handler
org.eclipse.smarthome.automation.handler.ModuleHandlerFactory	com.prosyst.mbs.services.automation.handler.TriggerHandlerFactory	used as handler factory for concrete trigger type

Providers

All applications that implement Providers, should be refactored to use the Automation Admin methods to plug their rules and templates to the system. The Providers are not supported anymore.

Classes and Interfaces

The following table contains all classes and interfaces that have replacement in the new Automation module:

ESH Class/Interface	Replacement Class/Interface
org.eclipse.smarthome.automation.RuleRegistry	com.prosyst.mbs.services.automation.AutomationAdmin
org.eclipse.smarthome.automation.ManagedRuleProvider	com.prosyst.mbs.services.automation.AutomationAdmin
com.prosyst.mbs.services.automation.items.RuleAdmin	com.prosyst.mbs.services.automation.AutomationAdmin
org.eclipse.smarthome.automation.template.RuleTemplateRegistry	com.prosyst.mbs.services.automation.AutomationAdmin
com.prosyst.mbs.impl.services.automation.ManagedRuleTemplateProvider	com.prosyst.mbs.services.automation.AutomationAdmin
com.prosyst.mbs.services.automation.items.RuleTemplateAdmin	com.prosyst.mbs.services.automation.AutomationAdmin
org.eclipse.smarthome.automation.type.ModuleTypeRegistry	com.prosyst.mbs.services.automation.AutomationAdmin
com.prosyst.mbs.services.automation.items.ModuleTypeAdmin	com.prosyst.mbs.services.automation.AutomationAdmin
org.eclipse.smarthome.automation.Module	com.prosyst.mbs.services.automation.Module
org.eclipse.smarthome.automation.Action	com.prosyst.mbs.services.automation.Module
org.eclipse.smarthome.automation.Condition	com.prosyst.mbs.services.automation.Module
org.eclipse.smarthome.automation.Trigger	com.prosyst.mbs.services.automation.Module
com.prosyst.mbs.services.automation.items.ModuleInfo	com.prosyst.mbs.services.automation.Module
com.prosyst.mbs.services.automation.items.ActionInfo	com.prosyst.mbs.services.automation.Module
com.prosyst.mbs.services.automation.items.ConditionInfo	com.prosyst.mbs.services.automation.Module
com.prosyst.mbs.services.automation.items.TriggerInfo	com.prosyst.mbs.services.automation.Module
com.prosyst.mbs.services.automation.items.RuleInfo	com.prosyst.mbs.services.automation.RuleInfo
com.prosyst.mbs.services.automation.items.RuleTemplateInfo	com.prosyst.mbs.services.automation.TemplateInfo
org.eclipse.smarthome.automation.Rule	com.prosyst.mbs.services.automation.RuleInfo, com.prosyst.mbs.services.automation.Rule
org.eclipse.smarthome.automation.template.RuleTemplate	com.prosyst.mbs.services.automation.TemplateInfo, com.prosyst.mbs.services.automation.Template
org.eclipse.smarthome.automation.template.Template	com.prosyst.mbs.services.automation.Template
org.eclipse.smarthome.automation.RuleStatusInfo	com.prosyst.mbs.services.automation.RuleStatus
org.eclipse.smarthome.automation.RuleStatus	com.prosyst.mbs.services.automation.RuleStatus.State
org.eclipse.smarthome.automation.core.internal.Connection	com.prosyst.mbs.services.automation.InputBinding
org.eclipse.smarthome.automation.type.Input	com.prosyst.mbs.services.automation.ParameterMetadata
org.eclipse.smarthome.automation.type.Outpput	com.prosyst.mbs.services.automation.ParameterMetadata
org.eclipse.smarthome.config.core.ConfigDescriptionParameter	com.prosyst.mbs.services.automation.ParameterMetadata
org.eclipse.smarthome.config.core.Configuration	java.util.Map

Registries' and Admins' Methods Mapping

The following table contains mapping for the registries' and admins' methods in the new Automation module:

ESH Method	Replacement Method
RuleAdmin.get(uid)	AutomationAdmin.getRule(uid)
RuleRegistry.get(key)	AutomationAdmin.getRule(uid)
ManagedRuleProvider.get(key)	AutomationAdmin.getRule(uid)
RuleAdmin.getAll()	AutomationAdmin.getRules(null)
RuleRegistry.getAll()	AutomationAdmin.getRules(null)
RuleRegistry.getByTag(tag)	AutomationAdmin.getRules(LDAP filter)
RuleAdmin.getByTags(String...tags)	AutomationAdmin.getRules(LDAP filter)
RuleRegistry.getByTags(String...tags)	AutomationAdmin.getRules(LDAP filter)
RuleAdmin.add(RuleInfo)	AutomationAdmin.addRule(RuleInfo)
RuleRegistry.add(element)	AutomationAdmin.addRule(RuleInfo)
ManagedRuleProvider.add(element)	AutomationAdmin.addRule(RuleInfo)
RuleAdmin.update(RuleInfo)	AutomationAdmin.updateRule(RuleInfo)
RuleRegistry.update(element)	AutomationAdmin.updateRule(RuleInfo)
ManagedRuleProvider.update(element)	AutomationAdmin.updateRule(RuleInfo)
RuleAdmin.remove(uid)	AutomationAdmin.removeRule(uid)
RuleRegistry.remove(key)	AutomationAdmin.removeRule(uid)
ManagedRuleProvider.remove(key)	AutomationAdmin.removeRule(uid)
RuleAdmin.setEnabled(uid, true)	AutomationAdmin.enableRule(uid)
RuleRegistry.setEnabled(uid, true)	AutomationAdmin.enableRule(uid)
RuleAdmin.setEnabled(uid, false)	AutomationAdmin.disableRule(uid)
RuleRegistry.setEnabled(uid, false)	AutomationAdmin.disableRule(uid)
RuleAdmin.run(uid)	AutomationAdmin.runRule(uid)
RuleRegistry.run(uid)	AutomationAdmin.runRule(uid)
RuleAdmin.getStatusInfo(String)(uid)	com.prosyst.mbs.services.automation.Rule.getStatus()
RuleRegistry.getStatusInfo(String)(uid)	com.prosyst.mbs.services.automation.Rule.getStatus()
RuleTemplateAdmin.get(uid)	AutomationAdmin.getTemplate(uid)
RuleTemplateRegistry.get(key)	AutomationAdmin.getTemplate(uid)
ManagedRuleTemplateProvider.get(key)	AutomationAdmin.getTemplate(uid)
RuleTemplateAdmin.getAll()	AutomationAdmin.getTemplates(null)
RuleTemplateRegistry.getAll()	AutomationAdmin.getTemplates(null)
RuleTemplateRegistry.getByTag(tag)	AutomationAdmin.getTemplates(LDAP filter)
RuleTemplateAdmin.getByTags(String...tags)	AutomationAdmin.getTemplates(LDAP filter)
RuleTemplateRegistry.getByTags(String...tags)	AutomationAdmin.getTemplates(LDAP filter)
RuleTemplateAdmin.add(RuleTemplateInfo)	AutomationAdmin.addTemplate(TemplateInfo)
RuleTemplateRegistry.add(element)	AutomationAdmin.addTemplate(TemplateInfo)
ManagedRuleTemplateProvider.add(element)	AutomationAdmin.addTemplate(TemplateInfo)
RuleTemplateAdmin.update(RuleTemplateInfo)	AutomationAdmin.updateTemplate(TemplateInfo)
RuleTemplateRegistry.update(element)	AutomationAdmin.updateTemplate(TemplateInfo)
ManagedRuleTemplateProvider.update(element)	AutomationAdmin.updateTemplate(TemplateInfo)
RuleTemplateAdmin.remove(uid)	AutomationAdmin.removeTemplate(uid)
RuleTemplateRegistry.remove(key)	AutomationAdmin.removeTemplate(uid)
ManagedRuleTemplateProvider.remove(key)	AutomationAdmin.removeTemplate(uid)
ModuleTypeAdmin.get(uid)	AutomationAdmin.getHandler(uid)
ModuleTypeRegistry.get(key)	AutomationAdmin.getHandler(uid)
ModuleTypeAdmin.getAll()	AutomationAdmin.getHandlers(null)
ModuleTypeRegistry.getAll()	AutomationAdmin.getHandlers(null)
ModuleTypeRegistry.getByTag(tag)	AutomationAdmin.getHandlers(LDAP filter)
ModuleTypeAdmin.getByTags(String...tags)	AutomationAdmin.getHandlers(LDAP filter)
ModuleTypeRegistry.getByTags(String...tags)	AutomationAdmin.getHandlers(LDAP filter)
ModuleTypeAdmin.getTriggers()	AutomationAdmin.getHandlers(LDAP filter)
ModuleTypeRegistry.getTriggers()	AutomationAdmin.getHandlers(LDAP filter)
ModuleTypeAdmin.getConditions()	AutomationAdmin.getHandlers(LDAP filter)
ModuleTypeRegistry.getConditions()	AutomationAdmin.getHandlers(LDAP filter)
ModuleTypeAdmin.getActions()	AutomationAdmin.getHandlers(LDAP filter)
ModuleTypeRegistry.getActions()	AutomationAdmin.getHandlers(LDAP filter)

For all services, classes, interfaces and methods that are not mentioned there is no replacement and they should not be used.