Availability

This feature is available since Orbeon Forms 4.5. It is available with all supported relational databases but not the eXist database.

What is form definition versioning?

Without form definition versioning

Without form definition versioning, Orbeon Forms only keeps track of a single published form definition for a given application name/form name (see terminology). This means that if you republish a form, the previously-published form definition gets overwritten (although there is an auditing trail).

This also means that when opening existing data for editing or viewing, Orbeon Forms always uses the latest published version of the form definition. This can lead to unexpected results, as fields might have been added, removed, or renamed in the new form definition. In fact, the form definition could be completely different from the form definition used to create and save the data currently stored in the database!

With form definition versioning

Form definition versioning introduces the idea that published form definitions for a given application name/form name also have a version number. When creating a new version upon publishing, the version number is "1", and when publishing again with a new version the number increases: "2", "3", etc. So you can talk about "version 2 of the Acme Order form".

When saving form data, the data in the database is associated not only with the application name and form name, but also with the version of the form definition that was used to create or edit that data. So when you open that data for editing or viewing at a later time, Form Runner can use the matching version of the form definition.

When publishing, if versioning is supported by the persistence layer, you have a choice to create a new form version or to override an existing one. This is detailed in Publishing.

Compatibility of changes

There are different types of changes you can make to a form definition which impact whether existing data in the database will be compatible with those changes.

NOTE: If there is not yet any data created by that given form definition version in the database, then compatibility is not a problem.

Examples of compatible changes:

• updating labels, hints, help messages, and explanatory texts

• adding items to selection controls

• changing the initial value of a control, either directly with the control or via an Initial Value formula

• moving a control within the same grid or section

• changing grid column widths

• adding a language

• updating permissions

• updating email settings

Examples of incompatible changes:

• renaming a control

• adding a control, grid, or section

• removing a control, grid, or section

• renaming a control, grid, or section

• moving a control between grids or sections

• changing the nesting of grids or section within subsections

See also Simple data migration below.

Simple data migration

Availability

This feature is available since Orbeon Forms 2018.2.

This is an Orbeon Forms PE feature.

Rationale

Simple data migration is an option which sits between "overwrite an existing form definition in an incompatible way" and "create a whole new form definition version". When enabled, simple data migration allows you to overwrite a form definition, but keep certain changes compatible, namely, the updated form definition can:

• add and remove controls

• add and remove grids and sections

When you load existing data with the updated form definition, the following happens:

• If the data is missing placeholders for data associated with new controls, grids or sections, those are automatically added.

• If the data has extra placeholders for data associated with removed controls, grids or sections, those are automatically removed.

Configuration

This option is disabled by default. You can enable it in the Form Settings's Form Options tab:

• Use property: Use the value set by the oxf.fr.detail.data-migration property.

• Enabled: Perform simple data migration when loading and receiving data.

• Disabled: Do not perform simple data migration when loading and receiving data.

• Raise an error: If the data is incompatible upon load, raise an error. The user will not be able to access the data.

The oxf.fr.detail.data-migration is set as follows by default:

<property
    as="xs:string"
    name="oxf.fr.detail.data-migration.*.*"
    value="disabled"/>

Limitations

When using form definition versioning, form definitions and form data must both be stored in the same persistence provider, which must support versioning. See issue #3926.

For example:

<property
    as="xs:string"
    name="oxf.fr.persistence.provider.acme.*.*"
    value="mysql"/>

or:

<property
    as="xs:string"
    name="oxf.fr.persistence.provider.acme.*.form"
    value="mysql"/>
​
<property
    as="xs:string"
    name="oxf.fr.persistence.provider.acme.*.data"
    value="mysql"/>

However, the following does not work:

<property
    as="xs:string"
    name="oxf.fr.persistence.provider.acme.*.form"
    value="mysql"/>
​
<property
    as="xs:string"
    name="oxf.fr.persistence.provider.acme.*.data"
    value="oracle"/>

See also

• ​Application name and form name​

• ​Publishing​

  • ​Overwriting of existing version​

  • ​Versioning comments​

• ​Summary Page​

• Blog posts:

  • ​Form versioning​

  • ​Choosing the best versioning option when publishing a form​

  • ​Versioning comments​

  • ​Simple data migration​

• ​Persistence API and versioning​

• ​Form Settings​