Orbeon Forms 2023.1

Sunday, December 31, 2023

Today we released Orbeon Forms 2023.1! This release is absolutely packed with new features and bug-fixes!

Major new features

Token-based permissions

This feature allows you to specify that a user can access form data with readonly or read-write permissions, provided that they are provided a link containing a permission token.

This introduces new permissions in the Form Runner permissions dialog:

Links generated by Form Runner can optionally include a token that can be shared in a control value, template-generated output, including emails. The token is valid for a certain amount of time.

An optional "Share" icon is available at the top of a form's Detail page, which allows users to generate and copy a link with a token, provided the form supports token-based permissions.

New configuration properties are introduced to configure the token-based permissions feature. For more information, see the documentation.

Comprehensive form and data export

This version introduces a powerful export feature. This is available from the Form Runner Admin page and lets you export a mix of form definitions and form data following several criteria. The result is a zip file containing all the exported form definitions and data, as well as associated attachments.

This is useful in particular for backup purposes and analytics.

For more information, see the documentation

Purging of historical form data

This feature is related to the Export feature above. It allows you to delete form data following several criteria. This is useful for GDPR compliance, as well as for reducing the database size.

For more information, see the documentation and this blog post.

Data revision history

Form Runner saves revisions of the data. Each revision of the data has an associated timestamp. Starting with Orbeon Forms 2023.1, Form Runner provides a UI to access the revision history of a given form data.

Note that this feature is distinct from form definition versioning.

For more information, see the documentation

Configurable PDF header and footer

In past versions, you could configure the PDF header and footer using CSS. However, this was cumbersome and error-prone.

You can now configure the PDF header and footer using a declarative configuration. And if you need to add custom CSS, you can still do so, and it's easier than before.

For more information, see the documentation.

Video component

You can now add videos to a form. You can use the "Video Attachment" control, which allows users to upload a video, or the "Static Video" control, which allows you to specify a static video. This mirrors what is possible with the "Image Attachment" and "Static Image" controls.

The static video This is useful for illustrations, training, and other purposes.

The video player supports scrubbing thanks to changes to the Orbeon Forms persistence backend to retrieve byte ranges.

You can see the Video component in action in the Controls form.

For more information, see the Video component and Video attachment documentation.

Bulk data updates

This new feature allows you to update multiple form data at once directly from a form's Summary page. This is useful for example to update the status of multiple forms at once.

For this to work, the form author must have enabled the "Allow bulk edit" option for at least one form control in the "Control Settings" dialog.

For more information, see the documentation.

Enhancements to email sending

The user interface for email settings has been improved, in particular for attachments settings.

In addition, the following enhancements to the email configuration are introduced:

  • You can now send an email conditionally for a specific template (doc)

  • You can now specify custom email headers, even dynamically (doc)

Time window

This new feature enables you to prevent users from filling out new forms before a given start date or after a given end date. The screenshot below illustrates what you can expect to find in the corresponding tab of the Form Settings in Form Builder.

For more information, see the documentation.

Configurable messages and resources in Form Builder

This new Form Builder dialog allows the form author to configure both:

  • standard Form Runner messages, such as success and error messages

  • and custom resources, such as Form Runner labels, hints, and other messages

For more information, see the documentation.

Formulas console

The Formulas console allows you to view formulas errors that occur when testing a form.

For more information, see the documentation.

Copying control content

This new Form Builder action allows you to explicitly copy complex form content from some controls to other controls, including handling of repetitions.

For more information, see the documentation.

Table of contents configuration

When not using the Wizard view, as well as in readonly modes such as View and PDF modes, you can now show the table of contents either on the left, on the top, or not at all. The table of content scrolls the page as needed. This is useful for long forms with many sections. You can also control in which modes the table of contents is shown.

When enabled in PDF files, the table of contents is always shown on top:

For more information, see the documentation.

"Copy to clipboard" button

The following form controls can now optionally show a "Copy to clipboard" button:

  • "Text Field"

  • "Text Area"

  • "Calculated Value"

You control this in the "Control Settings" dialog, using the new "With Clipboard Copy" control appearance.

This causes an icon to appear next to the form control. Activating the icon copies the value of the form control to the clipboard.

Open selection

The "Dynamic Dropdown with Search" supports open selection.

For more information, see the documentation.

Summary page fields roles

You can now restrict showing a field in the Summary page by one or more user roles.

For more information, see the documentation.

Session expiration warning

When a user's session is about to expire, Form Runner can now show a dialog warning the user.

For more information, see the documentation.

Other new features and enhancements

Option to store attachments in the filesystem

If you handle large and/or a large number of attachments, you can now configure Form Runner to store attachments in the filesystem instead of the database. This can improve performance and reduce the size of the database.

For more information, see the documentation.

Summary page processes

Form Runner supports processes associated with buttons, but so far this was only available on the Detail page. You can now configure processes associated with buttons on the Summary page.

For more information, see the documentation.

Security features

SHA-256

Orbeon Forms now standardizes on SHA-256.

Note that this was also backported to Orbeon Forms 2022.1.3 and newer.

See the documentation.

Improved encryption passwords

We have now separated oxf.fr.field-encryption.password and oxf.crypto.password, in addition to the new oxf.fr.access-token.password which is used by the tokens feature described above.

WARNING: Please be sure to read the compatibility notes about oxf.fr.field-encryption.password below, as well as the field-level encryption documentation.

The oxf.crypto.check-password-strength property allows checking and reporting about password strength. By default, this is enabled, and reports an error if the passwords are not set or too weak.

If you start Orbeon Forms with a oxf.crypto.password that hasn't been set or that is set to a password that is too weak, by default Orbeon Forms will show a banner at the top of every Form Runner page informing the user that some changes to the configuration need to be made. Exactly what changes need to be made is shown in the log file.

See the documentation.

Performance improvements

The following performance enhancements should be noted:

  • The Form Builder "Edit Source" performance with large form definitions is greatly improved.

  • Landing page loading times are improved.

  • Free text search performance in PostgreSQL has been enhanced. This improvement necessitates a new index, so if you are upgrading, ensure you run the appropriate upgrade script.

  • Form Runner can cache accesses to form definition metadata in the persistence API (doc).

Usability and accessibility features

Grid Tab Order

You can now set whether the tab navigation order within a grid is:

  • By row first, then by column

  • By column first, then by row

See the documentation.

HTML autocomplete attribute

The new "Autocomplete attribute" dropdown allows specifying an HTML autocomplete value.

See the documentation.

Localizations

Thanks to external contributors:

  • There are now Catalan language resources for Form Runner.

  • The Norwegian Form Runner resources have also been updated.

Other usability and accessibility features

  • Form Runner

    • The Wizard supports separate short section labels (doc)

    • Empty file attachments are now rejected by default (doc)

    • Invalid attachment messages are improved

    • Automatic hints are supported for the maximum file size and file types (doc)

    • Automatically focus on the first invalid field after closing Errors/Validation dialogs

    • The Excel import now shows errors immediately when reviewing uploaded data

    • The "Date" field supports the native date picker on the desktop (doc)

    • New experimental properties allow configuring automatic PDF accessibility and PDF/A settings (doc)

  • Form Builder usability

    • "Test PDF" produces meaningful filenames

    • Cmd/Ctrl-Enter commit the value in "Edit Source"

    • You are warned when referring to a non-existent variable in a formula

    • You can easily reset the value of a "Yes/No Answer" (doc)

New and improved APIs

  • Client-side APIs

    • The Wizard supports navigating to a specific section via URL (doc)

    • New JavaScript API to register a listener for process callbacks (doc, doc)

    • New JavaScript API to get a reference to an object representing a Form Runner form (doc)

    • New JavaScript API to activate Process buttons (doc)

    • New JavaScript API to activate a form control (doc)

    • Improved JavaScript to set the value of a form control (doc)

  • Server-side APIs

    • Page path and parameters information are passed to the file scanner (doc)

    • Export services are now also exposed as pages URLs (doc)

    • A new API allows you to produce PDF and TIFF exports using service URLs (doc)

    • New parameters allow controlling PDF production (doc)

Other Form Builder features

You can now directly download a form definition XHTML from Form Builder (doc)

Other Form Runner features

  • You can now opt to keep the "Formatted Text Area" colors in PDF output (doc)

  • The Summary page field search can show dropdown values for controls without static items (doc)

  • The success-message() and error-message() now support HTML (doc)

  • The Import page validate static lists of choices when using named ranges Excel files

  • The Excel and XML export buttons can also be present on the Summary page (doc)

  • XPath functions for checking permissions now work (doc)

  • You can now configure the "Dynamic Dropdown with Search" with a minimum input length (doc)

  • You can configure the Image Annotation start stroke color (doc)

  • You can now optionally show required stars in produced PDF files (doc)

Enhancements to actions

New actions are introduced:

  • Add fr:control-setfocus action (doc)

  • Add fr:control-setvisited action (doc)

  • Add fr:dataset-clear action (doc)

  • Add fr:control-setsize to the Action Syntax (doc)

In addition:

  • Actions can now optionally run their services asynchronously (doc)

  • The action syntax is supported in Section Templates

Embedding and offline support

Offline support for attachments

Form Runner now includes support for attachments in the offline mode.

Note that this feature is currently only usable when embedding Orbeon Forms within a native application. It is not available when using the Form Runner standalone web application. However, you can attach files in the "Test Offline" mode of Form Builder.

For more information, see the API documentation, and the Test offline feature.

Offline support for asynchronous service calls

The SubmissionProvider service call API now supports asynchronous responses, as well as streamed and chunked request and response bodies.

For more information, see the API documentation, and the Test offline feature.

This in particular allows the Dropdown with Search control to work offline, as well as the ability to stream attachments content, for example between a native application and Form Runner.

Cross-site JavaScript embedding

You can now embed Form Runner forms in a different domain than the one where Form Runner is deployed. This is done through the Form Runner JavaScript embedding API.

Promise returns an object

embedForm() returns a JavaScript Promise object representing the form. The object supports functions documented in The FormRunnerForm object.

XForms features

  • event() is supported for replace="all" submissions (doc)

  • You can tunnel context information to submission and error events (doc)

  • Delayed events support passing atomic properties (doc)

Platform features

  • We upgraded to Font Awesome 6

  • Orbeon Forms now supports Tomcat 10+, WildFly 27+ (doc)

  • In addition to Ehcahe 2.x, we added support for the JCache API (JSR-107) (doc)

  • Expired sessions now send a status code 440 to the client

Compatibility and upgrade notes

Field-level encryption password

The oxf.fr.field-encryption.password property controls a separate encryption password for field-level encryption. In previous versions, the general oxf.crypto.password property is used instead.

If you are upgrading from an earlier version of Orbeon Forms to version 2023.1, you need to set oxf.fr.field-encryption.password to the same value as oxf.crypto.password used previously. This step is required for Orbeon Forms to allow you to read existing encrypted data, as well as to write new encrypted data.

If you fail to do this, Orbeon Forms will report an error when you try to read or write encrypted data.

Once you have set oxf.fr.field-encryption.password, we recommend that you can change oxf.crypto.password to a different value.

It is generally safe to change oxf.crypto.password, even regularly, as this is not used to encrypt data at rest.

WARNING: But keep in mind that oxf.fr.field-encryption.password needs to remain stable so that existing encrypted value can be read back. If that password is changed or lost, the existing data will not be readable anymore.

Please be sure to read the field-level encryption documentation.

Password strength checker

A password strength checker will cause an error if one of the passwords configured in your properties-local.xml is too weak. Ideally, use randomly-generated strong passwords.

If you are using field-level encryption, and if you already have data in your database that contains encrypted fields, and if you are getting an error upon starting Orbeon Forms telling you that the encryption password is too weak, you can disable the password strength checker:

<property
    as="xs:boolean"
    name="oxf.crypto.check-password-strength"
    value="false"/>

We do not recommend disabling this in general. Instead, always use strong randomly-generated passwords.

Visiting of visible fields

In Orbeon Forms, a form control can be visited or not. Visited controls have typically been visited by the user, which means that the user navigated through the form control, possibly without changing its value. One way to visit form controls is to navigate using the "Tab" key, or to click on the form control and then click outside of it. Another way is to use the default "Save" or "Send" buttons, which by default visit all the form controls before proceeding. The notion is used to determine whether to show validation errors associated with that form control.

With Orbeon Forms 2023.1, form controls are also marked as visited when they are calculated, visible, and their value changes. This is useful to immediately show validation errors associated with such form controls, which are typically implemented with the Calculated Value form control.

If you don't wish this behavior, you can turn it off globally with the following property:

<property
    as="xs:boolean"
    name="oxf.xforms.xbl.fr.error-summary.visit-value-changed"
    value="false"/>

CRUD API

Using the CRUD API to PUT data or data attachments now requires the presence in the database of the corresponding form definitions.

In previous versions, in some cases, PUTting data for a non-existent form definition could succeed. This is no longer the case, and you should make sure that a matching form definition exists before PUTting data.

eXist DB removal

This version of Orbeon Forms removes Form Runner support for the eXist DB database. Use of this database in this context has been deprecated for a long time, and we have not been able to maintain it for a while. If you are using eXist DB, please migrate to a relational database.

The demo/samples forms that ship with Orbeon Forms now use an embedded relational SQLite database.

Note that the above removal regards eXist support by Form Runner only. You can still use eXist with plain XForms applications, by using <xf:submission> and an external eXist database.

web.xml

In order to support both Tomcat 10+ and WildFly 27+, which support the Servlet API version 5.0, 6.0 or newer, and older versions of the Servlet API, which are incompatible at the Java package level, the web.xml structure has been changed.

Orbeon Forms now automatically detects the Servlet API version and registers its main components accordingly. To achieve this, the following elements are no longer present:

  • <filter>

  • <filter-mapping>

  • <listener>

  • <servlet>

  • <servlet-mapping>

Instead, the configuration is done using top-level elements:

  • <context-param>

For example, to disable the limiter filter:

<context-param>
    <param-name>oxf.orbeon-limiter-filter.enabled</param-name>
    <param-value>false</param-value>
</context-param>

For more, see:

Uploading empty files

Starting with 2023.1, uploaded files that are empty are rejected out-of-the-box. Should you need to accept such files in your forms, you can set a property to allow them.

PreviousOrbeon Forms 2023.1.1NextOrbeon Forms 2022.1.6

Last updated