Upgrading

Steps

We recommend you test your upgrade in a non-production environment, and only upgrade your production environment once you've validated the upgrade. Also, before upgrading, we recommend you have a current backup of your database. Once done:

1. Stop your application server (e.g. Tomcat).

2. Move your existing Orbeon Forms install to a temporary directory. For instance, with Tomcat, in Tomcat's webapps directory, move any existing orbeon folder, as well as the orbeon.war file, if present, out of the way before proceeding.

3. Install the new orbeon.war. With Tomcat, this is often done by uncompressing the orbeon.war into an orbeon directory (unzip -d orbeon orbeon.war), and moving the orbeon directory inside the Tomcat webapps directory.

4. Restart your application server and test that your clean install works as expected "out of the box", that is without any of your custom configurations.

5. Put back configurations you had with your previous installation. Often, the only file you need to modify is WEB-INF/resources/config/properties-local.xml, but you might have created or made changes to other files, such as WEB-INF/resources/config/form-builder-permissions.xml, WEB-INF/resources/config/log4j.xml or WEB-INF/web.xml.

6. Migrate your database if needed.

   • If you're using the internal eXist and want to keep the forms you created, and corresponding data captured with those forms, you'll want to move the WEB-INF/exist-data directory to the new web app.

   • If using a relational database, open the page Using Form Runner with a relational database, and:

     • You might have to run some upgrade DDL at the database level. In the page linked above, find the section about the database you are using, and in the table with the DDL, given the version you are upgrading from and the version you are upgrading to, check if there is some DDL you need to run.

     • Open the "DDL to create from scratch" for the version you are upgrading to, and check that your database has all the indexes mentioned in this file. Make sure to check this, even if you didn't have to run any upgrade DDL.

7. Restart your application server and test that everything is working as expected with the new version of Orbeon Forms. While, or before doing so, you might also want to review the compatibility notes which might give you some indication of what you might to pay especially attention to when testing.

Finally, let us know if you encounter issues while upgrading, via the community, by email, or via professional support.

Why upgrade to newer versions of Orbeon Forms?

Minor releases

Orbeon Forms minor releases (or "dot releases", or "point releases"), for example Orbeon Forms 2020.1.1, 2020.1.2, etc., contain important bug-fixes but no new features (in some rare cases, minor features can be introduced). We recommend upgrading to newer minor releases in all cases.

Major releases

Major releases contain new features and bug-fixes. In some cases, bug-fixes cannot be backported to earlier versions of Orbeon Forms, for example in the case where the fix required an important change in the internal architecture of the software.

The only sure way to keep up to date is to eventually update to a newer major version of Orbeon Forms. We acknowledge that upgrading, while it should always be smooth, comes with some risks, as with any software upgrade.

You can reduce that risk by not upgrading to the first published major release, and wait until a subsequent dot release. For example, instead of immediately upgrading to Orbeon Forms 2021.1, wait until Orbeon Forms 2021.1.1 or 2020.1.2.

Where do bug-fixes go?

The way we handle fixes, generally, is as follows:

• All new fixes go into the branch for the next major version of Orbeon Forms (for example the future Orbeon Forms 2019.1).

• Most fixes (as opposed to new features) go into the previous major version of Orbeon Forms as well (for example Orbeon Forms 2020.1), and are released as a dot release at a later time (for example Orbeon Forms 2020.1.6).

• Some important fixes are backported to earlier versions of Orbeon Forms (for example 2019.2.x) at Orbeon's discretion.

• We backport certain features to customer branches on demand. But the more time passes between versions, the harder and riskier it becomes to backport fixes. This is because the codebase is more likely to change over time.

Compatibility policy

• Compatibility: We strive to remain backward compatible between versions of Orbeon Forms and not to break features, whether on purpose or by accident.

• Deprecation and removal: Over time, we may mark some features as deprecated. After being deprecated for a while, these features can even be removed from the product. Over years, this means that backward compatibility is not always guaranteed.

• Compatibility notes: Release notes for each version might contain compatibility notes. When upgrading, please make sure to always review compatibility notes.

Difficulty of upgrades

NOTE: As a reminder, starting with Orbeon Forms 2016.1, we are using a versioning scheme with the number of the year first followed by the number of the major release during that year. See Release History for details.

• Between any two subsequent 4.x releases, or 20xx.x releases, upgrades are expected to be fairly straightforward.

• The longer the interval of time between two release, the harder the upgrade might be. For example, it will be easier to upgrade between 2022.1 and 2023.1 than between 2016.1 and 2023.1.

• Orbeon Forms 4.0 was a large release with many changes. In general upgrading between pre-4.0 releases and 4.x releases is more difficult than upgrades between two 4.x or 20xx.x releases.

• Since Orbeon Forms 4.0, we have switched to a faster release cycle, with releases every few months. So there are typically more changes between, say, 3.8 and 3.9, and especially 3.9 and 4.0, than between two subsequent 4.x or 20xx.x releases.

Areas of compatibility

• Form Runner / Form Builder DDL: The relational database definitions are subject to change between releases. We provide scripts to upgrade the definitions between versions.

• Form Runner form format: We strive to keep the format, when form definitions are not modified by users, fully backward compatible.

  • Form Builder, upon loading and republishing forms, can upgrade the format of form definitions when needed.

  • Similarly, and since Orbeon Forms 4.6, the Form Runner Home page has an "Upgrade" feature to upgrade published form definitions.

• XForms support: We strive for maximum backward compatibility at the XForms source level. But because the XForms processing model is quite advanced, some subtle details are subject to change, such as the order in which some events are dispatched.

• Look and feel and CSS: Often users adapt the Orbeon Forms look and feel using custom CSS. It is hard to guarantee full backward compatibility here due to the lack of encapsulation provided by CSS. Upgrades can require custom CSS to be adapted. 4.0 in particular introduced the Twitter Bootstrap library for the user interface, and that was a major change from previous versions.

• Configuration properties: We strive to keep properties backward compatible. On rare occasions, configuration properties have changed in incompatible ways, in particular in 4.0 the Form Runner persistence providers configuration have changed.

Compatibility notes for previous versions

When about to upgrade, we recommend you go through the release notes for all versions between the version you are using and the one you are upgrading to, paying particular attention to the compatibility notes sections. Here are the releases which contain backward compatibility notes:

• 2023.1.1

• 2023.1

• 2022.1.1

• 2022.1

• 2021.1

• 2020.1

• 2019.2

• 2019.1

• 2018.2

• 2018.1

• 2017.1

• 2016.2

• 2016.1

• 4.10

• 4.9

• 4.8

• 4.7

• 4.6.2

• 4.6.1

• 4.6

• 4.5

• 4.4

• 4.3

• 4.2

• 4.0

• 3.9

Reliance on Orbeon Forms internals

Recommendation

In general, we strongly recommend that you do not rely on Orbeon Forms internals, but only on published APIs.

This includes not modifying the content of any JAR files present in Orbeon Forms.

When it happens

Our users sometimes customize Orbeon Forms by relying on the internals of Orbeon Forms. This might even be on Orbeon's advice, when no better solution are available at a given time. In such cases, upgrading can be more difficult, because the internals of Orbeon Forms are subject to change, and backward compatibility of look and feel is difficult to achieve with only CSS.

When this happens, we consider the reasons changes relying upon Orbeon Forms internals, and evaluate how this could be improved in the future. Examples include:

• Available

  • Form Runner: Buttons and Processes

  • Form Runner: Custom dialogs and model logic

• Considered

  • Stable API for Form Runner

What are the benefits of upgrading Orbeon Forms versions?

Each new version brings:

• stability, security and other bug-fixes

• new features

In addition, we can support newer version of Orbeon Forms much better than older versions.

In addition, if you are on the 3.x series of Orbeon Forms, the 4.x series brings:

• an improved look and feel

• a rewritten Form Builder relying on a better foundation

• more configurable features

• many new features

See also

• Orbeon Forms release history