Upgrading from older versions
To upgrade to a new version of Orbeon Forms you'll want to:
Review the compatibility notes (see Compatibility notes for previous versions).
Make sure you have a backup of your current environments, including:
databases
containers
Orbeon Forms WARs
all Orbeon Forms configurations
Make sure to first upgrade in a safe test environment.
Do a "clean Install" of the new version of Orbeon Forms.
Don't install it "over" the old version, or try to just update some
jarfiles or any other files in the old version (unless directed to do so by Orbeon support).Check that that your clean install works as expected out of the box.
Often, the only file you need to modify is the
properties-local.xml(insideWEB-INF/resources/config), but you might have created or made changes to other files, such asform-builder-permissions.xmlor even `web.xml``.
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-datadirectory to the new web app.If using a relational database, you might have to run some upgrade DDL at the database level. Search for "upgrade" in the relational database configuration documentation, and check if there is some DDL you need to run to upgrade your database schema. This means running the
*-to-*.sqlDDL files from the older version to the new version.
Thoroughly test that everything is working as expected with the new version of Orbeon Forms.
Finally, let us know if you encounter issues while upgrading, via the community, by email, or via professional support.
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.
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 201x.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 can be harder to upgrade between 4.0 and 4.6 than between 4.5 and 4.6.
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 201x.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 201x.x releases.
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.
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:
​2017.2​
​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​
See also Orbeon Forms release history.
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
Considered
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.
See the release notes of all the versions for more details.
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