Overview:
- What’s new in Umbraco Forms 8.13/9.5/10.1?
- Focus on Workflows
- Folder-Based Form Picker
- Prevalue Captions
- User Group Permission Tweaks
- Backoffice Date Formats
- Rich Text Field Type
- Other Updates
- Notice on breaking changes
- How to test
- How to get your hands on the release candidates
- When is the public release?
The releases are available for solutions based on both CMS versions 8, 9, and 10 and are mostly functionally equivalent. As such if you are using the product in Umbraco 8, you can update to the release candidate for Forms 8.13. With Umbraco 9, Forms 9.5 should be used. And if you've started a project with Umbraco 10, then 10.1 is available as a release candidate as an upgrade.
As with previous releases, we are issuing them first as release candidates so you can evaluate what’s included and ideally try them out on your existing solutions. Of course, if you do find any issues, or simply have comments for further improvement on the new features, we welcome any feedback.
How to get access to the new versions and where to submit any comments and report issues, are discussed at the bottom of the post.
Let’s have a look at what you can expect in this latest release 👀
What’s new in Umbraco Forms 8.13/9.5/10.1?
Focus on Workflows
The main set of features included in this release consists of improvements to workflows.
Workflows are pieces of functionality you can associate with a form, which run sequentially after the entry is submitted and/or approved. Umbraco Forms comes with a number of workflows out of the box and is extensible to allow you to create your own.
Workflow Audit Trail
If a workflow encounters an unexpected error or a problem with configuration, it will usually throw an exception or record some details to the Umbraco log. It will do so silently though, so the person submitting the form, who is unlikely to be in a position to resolve any issue, isn't informed. This is arguably a good thing from the perspective of customer experience but it can be tricky from an editor or administrator view to understand if any workflows encountered a problem.
To surface this information we've added a workflow audit trail to the backoffice screens where entries are viewed.
Firstly, in the list of entries for a form, a summary is presented that shows how many unique workflows were executed, and how many were successful:
For each entry, in the backoffice, a table can be viewed that shows each of the workflows and the success, or otherwise, of the operation.
Workflow Retry
Having reviewed the audit and discovering a workflow hasn't run, it would be nice to be able to do something about it. Fortunately, now you can.
For any workflows that did not complete successfully, a "Retry" link is available to trigger the workflow again. This is useful for example if there was a temporary infrastructure issue that perhaps prevented an email from going out. You would be able to retrigger the workflow once the issue is resolved.
Customizing Default Workflows
When a new, empty form is created, by default a workflow is added that sends an email containing the form submission to the address of the editor that creates the form. This can be a useful function and serves to make editors aware of the workflow functionality, but it may not be necessary for all setups.
Previously this logic was hard-coded, but we've now moved it into a behavior defined by an interface which means there's a seam for customization for the needs of a particular solution. If you require different functionality, then creating a custom implementation of this interface and swapping out the default one, will allow this. Documentation for this feature is here.
As part of that customization, you may also want to make certain workflows mandatory. This is possible now too, and if set, an editor won't be able to remove the workflow from the form. See details in the documentation.
Conditions for Workflows
Umbraco Forms has support for conditional fields when constructing forms, which allows certain fields to be shown or hidden based on the status of other fields. For example, you can show a text box when a user selects "Other" from a drop-down list. Conditions are also available for whole field sets and the buttons on multi-page forms used for navigating forward and back.
With this release, we've extended the same functionality to workflows. By applying a condition to a workflow, it can be set to run or be ignored depending on the values submitted by the user with the form entry.
Redirect from Workflows
When creating a form an editor has the option to either display a message or redirect to another Umbraco page following the form submission. We had a requirement though for an integration with a payment provider, that needed to redirect from a custom workflow to an external URL (that hosted a payment page).
Redirecting from a custom workflow can be carried out by issuing a redirect statement on the response object, but it's a rather blunt technique, short-circuiting the normal operation of workflows. For example, any workflows configured to run after the custom one would be skipped.
Instead, we've provided a method where a value can be set on the HttpContext's Items dictionary, that will be used to redirect once the form processing and all workflows are complete. Documentation for this feature can be found here.
Folder-Based Form Picker
In a recent release of Umbraco Forms, we added the ability for editors to organize forms into folders. We then subsequently utilized that feature in the permissions model, so certain editors can be restricted to only be able to manage and select forms from within a folder.
With this release, we've implemented what will hopefully be the final requirement related to this feature, which is to extend the form picker to allow selection of forms via the folder structure. This should be a useful enhancement for editors, particularly for installations with many forms available for selection.
Prevalue Captions
Various form fields, such as drop-down lists and radio buttons, require the provision of options for the user to pick from. These are known as prevalues and up until now have been implemented as a list of strings. In some cases though, it would be preferred to present one value to the person completing the form to pick from, but store a different one with the entry.
We've added support for this with this release, so each prevalue can have a value and caption set. The caption is optional and replaced by the value when not set, so the existing behavior is retained for any forms that are already created.-
For prevalues added directly to a form, the settings overlay where this information is entered has been updated to allow for the provision of a caption:
In order to share lists of prevalues between several forms, prevalue sources can be created, and, where possible, we've extended all the ones provided by Forms to support this:
- When importing prevalues from a text file, a vertical bar (|) delimiter can be added to each line to separate the value from the caption. If there is no delimiter, each line is used as the value as before.
- When reading prevalues from a SQL database, a column for the caption can be defined.
- When using Umbraco nodes as a prevalue source, a new setting allows you to select the node's Id or Key to use as the value, instead of the Name (which is the default, to adhere to existing behavior).
- The datatype prevalue source hasn't changed (as only a single value is available here).
The built-in workflow for sending email using a Razor template has been updated to display captions when configured.
For the export to Excel feature, we weren't sure whether it was better to have the submitted values or prevalue captions output to the file. To make the output more readable for a human creating a report, it would be better to display captions. But if the exported file is used in an integration with another system, likely the raw values are more useful (and reliable - as it's possible for the captions to be changed after the form was submitted). To resolve the dilemma we decided to create a second export option, so users can pick the one that makes the most sense for their needs.
User Group Permission Tweaks
We had a couple of issues raised related to the recent update of Forms to support permissions based on user groups.
Firstly we fixed an issue that was incorrectly including user groups without access to the forms section in the aggregation of folders available for a user.
Secondly, we added two "special" values that can be applied within or instead of the comma-separated list of user groups that are by default given access to newly created forms..
- A value of "all" will give access to the form to all user groups.
- A value of "form-creator" will give access to all the user groups that the user who created the form is part of.
The documentation detailing these options and the logic for evaluating access to forms has been updated and can be viewed here.
Backoffice Date Formats
This amendment related to this update is in reality quite small, but needs a bit of background explanation! We've made a couple of changes to resolve an issue with multi-lingual setups and date fields
When Umbraco Forms stores data for a record, as well as storing the values submitted for each field into a dedicated table for each type (string, date, etc.), it also saves a second copy of the record in a JSON structure, which more suitable for fast look-up and display in the backoffice. Date values are serialized using the culture used by the front-end website when the form entry is stored.
When displaying the data in the backoffice, the date value needs to be parsed back into an actual date object for formatting. This can cause a problem if the backoffice user is using a different language, and hence culture setting, than that used when the value was stored.
From this release, the culture used when storing the form entry is recorded, thus we can ensure the correct value is used when parsing the date. This resolves the problem moving forward.
However, this doesn't help for historically stored records. To at least partially mitigate the problem, when you have editors using different languages to a single language presented on the website front-end, a configuration setting can now be applied to match the culture code used on the website and ensure the date fields in the backoffice are correctly presented.
In other words, if you have a website globalization culture code setting of "en-US" (and a date format of m/d/y), but an editor may be using "en-GB" (which formats dates as of d/m/y), by setting the value of this configuration key to "en-US" you can ensure that the culture when parsing dates for presentation in the backoffice will match that used when the value was stored.
Documentation for the configuration setting is available here.
Rich Text Field Type
Sometimes it's useful to present some read-only information to users completing forms. Currently, though Forms doesn't have a field type that supports formatted text, or links, handy for linking to terms and conditions or privacy policy pages.
With Forms 8, a community package developed by Matthew Wise could be used to implement this feature. Following a conversation at Codegarden, Matthew told us he would be happy if we took this into the core product for version 9 onward. Hence, with his blessing, we've adapted and included this with the upcoming release. Thanks very much, Matthew!
By default, the toolbars and other settings associated with the rich text data type installed with Umbraco are used, but this can be amended in configuration, as documented here.
Other Updates for Umbraco Forms
The other updates included in the release are as follows:
- When creating custom field types or workflows in Umbraco 10, they need to be registered. We've added some friendlier extensions to support this, aligning with those used in the CMS, that you can read about here.
- Added details of page where form was submitted to Excel download.
- Added indication of options for "magic strings" when adding fields and workflows to forms.
- Ensured order of fields retrieved for a record from the database matches the field order defined on the form.
- The trigger for client-side conditions checked can now be configured between "change" (the default) and "input". Documentation for this setting is here.
- Note that this update required a change to the default theme's Script.cshtml file. Hence if you are using custom themes, please make sure to review and update if you wish to use this configuration option.
- Fixed issue with displaying entries where a member's Id was stored as a Guid via a custom membership provider.
- Fixed issue with console request for client validation script source map.
- Fixed issue with reCAPTCHA V3 field type.
- Fixed a missing translation.
- All updates in the patch releases for the previous minors are included.
Notice on Breaking Changes
Please note that this release has required a minor breaking change in a few public classes. Usually, we try of course to avoid these, but in this case, it was felt introducing the features for all the recent Forms versions and not waiting for a future major release outweighs the downside of it. We don't expect many or hopefully even any users to be affected.
The method PreValues on the FiieldViewModel type has been changed from a collection of strings to a collection of a PrevalueViewModel object that has a Value and Caption property.
We've also made updates to the default theme to render the captions for field types that support prevalues. If you have created any custom themes, please review the default theme and ensure you make similar changes to make use of the new feature.
In order to fix an issue with display and editing of values, we've found a need to ensure the property representing the fields a record entry used in the back-office is changed from a list of values to a structure containing the field Ids and values. Specifically, EntrySearchResult.Fields has changed type IEnumerable<object?> to IEnumerable<EntrySearchResult.FieldData>. The only likely affected by this is anyone handling the EntrySearchResultFetchingNotification notification or developing custom export types.
How to test
You can either create a new installation using one or both of these packages that are available from the links below or upgrade an existing project. Both scenarios can provide valuable feedback. If upgrading, you may find you need to bump your client-dependency version.
If you find anything in the release candidates that are not working as you’d expect, we’d be grateful for feedback on the Github issue trackers for Forms. You’re welcome to add comments to the features and fixes listed linked above or to submit new bug reports (click New Issue and select Bug Report), please prefix the issue with 8.13RC, 9.5RC, or 10.1RC.
How to get your hands on the release candidates
For Forms, release notes can be found on the our.umbraco.com download page where there’s also a download available for Umbraco 8. The release candidates are also available from the appropriate NuGet feed:
When is the public release?
We’re aiming for a full public release on Tuesday, 9th August 2022, when the packages will be available for new and existing projects on Umbraco Cloud, via Nuget, and/or the download page.
A big H5YR 🙌 to everyone who has contributed to these releases by highlighting pain points, reporting issues, providing feedback, and suggesting solutions. And thanks to everyone willing to lend a hand in testing it out.
Bug reports are best handled on the issue tracker and as always, we welcome you to submit product feedback and questions to product@umbraco.com.
