Orbeon Forms 2023.1
Last updated
Last updated
Sunday, December 31, 2023
Today we released Orbeon Forms 2023.1! This release is absolutely packed with new features and bug-fixes!
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.
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
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.
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
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.
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.
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.
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)
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.
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.
The Formulas console allows you to view formulas errors that occur when testing a form.
For more information, see the documentation.
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.
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.
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.
The "Dynamic Dropdown with Search" supports open selection.
For more information, see the documentation.
You can now restrict showing a field in the Summary page by one or more user roles.
For more information, see the documentation.
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.
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.
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.
Orbeon Forms now standardizes on SHA-256.
Note that this was also backported to Orbeon Forms 2022.1.3 and newer.
See the documentation.
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.
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).
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 and blog post.
The new "Autocomplete attribute" dropdown allows specifying an HTML autocomplete value.
See the documentation.
Thanks to external contributors:
There are now Catalan language resources for Form Runner.
The Norwegian Form Runner resources have also been updated.
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)
Client-side APIs
The Wizard supports navigating to a specific section via URL (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)
You can now directly download a form definition XHTML from Form Builder (doc)
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)
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
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.
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.
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.
embedForm()
returns a JavaScript Promise
object representing the form. The object supports functions documented in The FormRunnerForm
object.
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)
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
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.
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:
We do not recommend disabling this in general. Instead, always use strong randomly-generated passwords.
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:
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, PUT
ting 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 PUT
ting data.
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.
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:
For more, see:
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.