Umbraco Workflow Release Candidate

Overview

• What’s new in Umbraco Workflow 11?
• Content reviews
• Optional settings
• Task rejection options
• Notifications, notifications, notifications
• A new licensing model
• Other updates
• How to test
• How to get your hands on the Release Candidate
• When is the public release?

Update (November 22, 2022): Official Umbraco Workflow documentation is now live.

While the introduction of Umbraco Workflow is the next step in Plumber’s evolution, it also means we hit a fork in the road. Plumber will continue to exist for Umbraco 8, 9 and 10, but won’t see any new features, and will only receive updates for security issues or significant bugs. 

All future efforts are focused on Umbraco Workflow, for Umbraco 11 and above, and given all the other benefits that come with the latest version of the CMS, you’d be silly not to upgrade, right?

To ensure the first Umbraco Workflow release is as stable and friendly as possible, we’re publishing a release candidate for you to explore and evaluate. Any feedback on the new features is absolutely welcome.

How to get started with Umbraco Workflow and how to provide feedback are explained at the end of this post.

Enough with the housekeeping, let’s have a look at what’s coming in Umbraco Workflow 11.

What’s new in Umbraco Workflow 11?

Content reviews

The major feature added in Workflow 11 is the introduction of a content review engine. This feature runs in parallel to the workflow engine, providing a mechanism for encouraging content editors to keep their content up-to-date.

The core functionality works as follows:

• All content has a default review period - ie the content must be reviewed every n days
• Individual content items can have their own review period
• All content of a particular document type can have their own review period
• The group responsible for reviewing content is derived from the workflow configuration, but can be overridden per content item or document type
• Prior to the review date elapsing, the assigned group is notified
• A member of the group can mark the content as reviewed and optionally set the next review date
• Optionally, saving changes to a content item can be treated as a review

Content reviews are opt-in, and disabled by default.

Content reviews adds a new dashboard to the Workflow backoffice section, providing an overview of all expired content, and a range of settings for configuring who reviews which pages (or document types), and how frequently.

Group assignment follows a similar inheritance pattern as workflow configuration - checking the node, its content type, and finally any inherited configuration (from content review and workflow configuration). This means a site with workflow already configured can leverage that permissions model for assigning content review responsibilities.

Optional settings

Taking inspiration from the work done in Forms 10.2, Workflow 11 adds the ability to hide or disable, via configuration, all settings displayed in the Workflow backoffice section.

Why? Because while deep, granular control is brilliant for customizing Workflow to exactly meet your requirements, it has previously meant surfacing controls which should only be set once, or at least only modified by a developer who understands the impact of changing the property value.

Rather than making the decision for you as to which controls should be available in the backoffice, we’ve made everything configurable.

By default, nothing changes. All settings are visible and editable, even if that means potentially unexpected side effects. By updating your appsettings.json file, you can choose to set any property to readonly, or hide it entirely. Even better, it’s possible to set default values for any property.

Two dictionaries exist for settings configuration - General and ContentReviews - where the entry keys match the property aliases, and the value contains three settings:

• IsHidden: if set to true, hides the property in the backoffice
• IsReadOnly: if set to true, sets the property to readonly in the backoffice
• Value: if set, provides the value for the setting, overwriting any value previously set from the backoffice. The provided value is validated to ensure it matches the required type for the particular property.

For example, to prevent edits when a node is in a workflow, but still display the setting in the backoffice, and disable content reviews via save and hide the setting, the configuration would look like the below:

All the available settings and their valid value types will be available in the Workflow documentation prior to the public release.

Task rejection options

By popular demand (at least, one person asked for it ☺️), Workflow 11 updates the task rejection functionality to allow reviewers to select where the rejected task is sent.

In previous versions, rejecting a task has always sent the workflow back to the original editor, but that never considered the scenario where a node could be edited later in the workflow, so would see the original editor blamed for a change that may not have been theirs.

For first-stage approvals, the rejected task can only be sent back to the original editor, so in these cases, the behavior is unchanged. When rejecting a task in later workflow stages, reviewers can select either the original editor or any previous workflow group.

It’s a small change, but a big improvement, providing editors with even more control over their content, and a more efficient review process.

Notifications, notifications, notifications

Workflow now uses the same pattern as the CMS for raising notifications, allowing developers to extend the core workflow behavior with their own custom code.

All Workflow notifications live in the Umbraco.Workflow.Core.Notifications namespace, and are suffixed with "Notification".

Like is done in the CMS, Workflow notifications typically come in pairs - a "before" and an "after". The "before" notification (in most cases) is cancellable via the CancelOperation method.

Rather than detailing the 40-plus available notifications, refer to the documentation for working with Notifications.

A new licensing model

Functionally very little changes - a valid Workflow license unlocks the full suite of features - but the implementation and configuration is cleaner and simpler. On purchasing a Workflow license, you’ll receive a 20-character license key to add to the appsettings.json file in your website, like so:

License validation only runs on single or scheduling publisher servers - please ensure you have nominated the server role by registering an instance of IServerRoleAccessor with CurrentServerRole set to either Single or SchedulingPublisher. Refer to the server role election documentation for examples.

Visit the  Workflow product page for more information.

Other updates

• A new setting for optionally hiding the scheduled date field when submitting a new workflow
• Embracing the Options pattern and providing more configurable options for status colors and date/time string formatting (documentation is being polished and will be available prior to the public release)
• Fixes a bug where submitting a new node for publish approval failed if the node was unsaved and a child of a list view
• Fixes a bug where canceling publish due to a pending workflow with a scheduled release date set the workflow to an error state
• More UI polish
• More localization (interested in helping with localization? Please, get in touch via the issue tracker)

How to test

Lines of code are a terrible metric, but for some context as to the scope of this release, there are almost 10,000 changes across almost 900 files. The majority of those are minor, but every change is a potential breeding ground for bugs, which is why we need your help with testing.

If you find anything in the Workflow RC that isn’t working as expected, please provide feedback on the GitHub issue tracker for Workflow.

If you’re new to Workflow/Plumber, the existing documentation for Plumber is largely still accurate, aside from the changes and new features mentioned earlier.
Update (November 22, 2022): Official Umbraco Workflow documentation is now live.

You can also check out the video below that gives an overview of Umbraco Workflow.

Migrating from Plumber to Workflow

Umbraco Workflow should be considered a new product. It is backwards compatible with Plumber data, but with a new default namespace constituting a major breaking change any existing customization or extension will need to be updated.

If you’re upgrading an Umbraco 10 install with an existing Plumber install, make sure to uninstall Plumber (including the App_Plugins/Plumber folder) before installing Workflow. All your existing workflow data and settings are safe and will be available on your upgraded site.

Otherwise, install the latest Umbraco 11 RC, then install Workflow 11 RC.

If you’re upgrading a site running on SQLite (please, say it ain’t so - SQL Server is still the recommended production database), there are additional manual steps as the required database changes can’t be sensibly managed in an automated migration:

• Uninstall Plumber (remove /App_Plugins/Plumber too)
• Upgrade to Umbraco 11
• Take a copy of the Value column from WorkflowSettings table
• Delete the WorkflowSettings table
• Update WorkflowTaskInstance table to allow null values in the GroupId column
• Install Umbraco Workflow 11
• Build
• After installation migrations complete, update WorkflowSettings to restore the previous data to the Value column

How to get your hands on the Release Candidate

The release candidate is available from the usual Nuget feed.

When is the public release?

We’re aiming for a public release on Wednesday, December 7, 2022, hot on the heels of Umbraco 11.