Breaking Changes in openHAB 3

openHAB 3 removed deprecated features and concepts in order to clean up the code base and simplify the overall architecture. This is to have less confusion for users on how to do stuff but inavoidably led to incompatibilities with openHAB 2 setups in some parts of the system.

This page is meant to collect the breaking changes that users should be aware of when (or better before) switching from openHAB 2 to 3.

Breaking Changes for Users

General

• The runtime now requires Java 11 instead of Java 8, so please make sure to install an appropriate JVM.
• Most visible change is the new Main UI. It comes with a setup wizard and which replaces Paper UI and HABmin and also serves as a very powerful end-user UI.
• The compatibility layer is gone, so 1.x add-ons will no longer work. If you rely on them and there isn't a new add-on in openHAB 3 for it (yet), you can make use of the new "remote openHAB" binding which allows to keep an old openHAB 2 instance running with the required add-ons and include it into an openHAB 3 setup.
• The administration related parts of the REST API are now secured which eliminates many potential attacks from malware in the local network. As a side effect, some inofficial/custom 3rd party integrations might not work anymore as expected.
  You can use the openhab:users in the console to add or change users.
• Logging definitions have changed to XML format. Your definitions in $OPENHAB_USERDATA/org.ops4j.pax.logging.cfg will be replaced by new defaults in log4j2.xml.

While there has not really been any substantial change, read this updated docs section for a summary of best pratices.

Rules

The next-gen rule engine (NGRE) of openHAB 2.5 has now become the official rule engine within openHAB. Good news is that rule DSL files are almost not impacted by this change. Nonetheless, there is the need to revisit existing rules since there were a couple of breaking changes in the DSL syntax. Note it's best practice to make your rules compatible ahead of time while you still run on OH2.5.

• The implicit variable triggeringItem is now only available for "Member of" triggers - all other item state/command triggers now have an implicit variable triggeringItemName instead.
• Rules now use Java Time API instead of Jodatime so some expressions need to be adapted:
  getHourOfDay → getHour, getMinuteOfHour → getMinute, getMonthOfYear → getMonthValue
  Some simple >and < comparisons may no longer work and you may need to use isAfter()/isBefore() instead. You can replace occurrences of now by ZonedDateTime::now in your 2.5 rules. Use import java.time.ZonedDateTime.
  See also this thread for more information.
• The action executeCommandLine() has a new syntax and needs to be adapted in DSL rule files.

Persistence

• rrd4j persistence is now enabled by default. The default strategy is to persist on every change and once a minute. There is no rrd4j.persist file though.

Add-ons

• iCalendar: calendar is now a Bridge instead of a plain thing. Readding the calendar or changing the configuration in text files is necessary.
• The "Embedded broker" (Moquette) add-on has been removed due to Moquette being an abandoned project with major bugs that won't be fixed anymore. Please use a separate MQTT broker like Mosquitto instead.
• The new Zoneminder binding in openHAB 3 is no longer compatible with Zoneminder versions earlier than 1.34.0.

Old UIs

• Sitemap: the server is no more providing a default sitemap.
• Classic UI: Classic UI has been removed from the OH3 distribution.

Breaking Changes for Developers

Cleaning the code base also means quite some changes for developers. In this section, the most important changes are listed: