In this article, we will cover the steps required to install Umbraco Workflow on your website.

Prerequisites

• Microsoft Visual Studio

Video Tutorial

Umbraco Workflow Installation

There are different ways to install Umbraco Workflow:

• .Net CLI Installation

• Visual Studio Installation

.Net CLI Installation

To install the Umbraco Workflow package (Umbraco.Workflow), follow these steps:

1. Run the following command to add a package reference to your Umbraco project:

dotnet add package Umbraco.Workflow

1. Restart the web application using the following command:

dotnet run

Visual Studio Installation

To install via Visual Studio, follow these steps:

1. Open your project in Visual Studio.

2. Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution....

3. Browse for Umbraco.Workflow.

4. Select the appropriate version from the Version drop-down depending on the Umbraco version you are using.

5. Click Install.
6. Once the package is installed, open the .csproj file to make sure the package reference is added:

<ItemGroup>
<PackageReference Include="Umbraco.Workflow" Version="14.x.x" />
</ItemGroup>

Using Umbraco Workflow

Once the installation is completed, you will see the following in the Umbraco Backoffice:

A Workflow Dashboard

A Workflow section

This page covers specific upgrade documentation for when migrating to Umbraco Workflow version 14.

Version Specific Upgrade Notes History

Version 14 of Umbraco Workflow has a minimum dependency on Umbraco CMS core of 14.1.0. It runs on .NET 8.

Breaking changes

Version 14 contains a number of breaking changes, primarily due to the new backoffice introduced in Umbraco 14. The details are listed here:

Behaviour

• A new management API has been introduced at umbraco/workflow/management/api

Dependencies

• Umbraco CMS dependency was updated to 14.1.0

Code

Workflow 14 includes a non-trivial number of breaking code changes, primarily related to namespace changes. The majority of these related to removing the Implement namespace for services, and moving appropriate models to Umbraco.Workflow.Core.ViewModels or Umbraco.Workflow.Core.Interfaces.

• The serialization library has been changed from Newtonsoft.Json to System.Text.Json.

• Approval group identifiers changes from int to Guid.

• Workflow instance author identifier changes from int to Guid.

• Workflow task indentifiers for approving user, assigned user and actioning user change from int to Guid.

• Services return Attempt<TResult> or Attempt<TResult, TStatus>, in line with similar changes in the CMS.

Legacy version specific upgrade notes

This article shows how to manually upgrade Umbraco Workflow to run the latest version. Umbraco Workflow displays a prompt in the Workflow section when a new version is available.

Get the latest version of Umbraco Workflow

To get the latest version of Umbraco Workflow, you can upgrade using either of the two options:

NuGet

• NuGet installs the latest version of the package when you use the dotnet add package Umbraco.Workflow command unless you specify a package version:

  dotnet add package Umbraco.Workflow --version <VERSION>

• Run dotnet restore to install the package.

Visual Studio

• Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution... in Visual Studio, to upgrade Umbraco Workflow:

• Select Umbraco.Workflow.

• Select the latest version from the Version drop-down and click Install.
• Open the .csproj file to make sure the package reference is updated:

Umbraco Workflow allows the creation of multi-stage approval workflows when writing and publishing content. Umbraco Workflow extends Umbraco's out-of-the-box publishing model with multi-stage and configurable approval workflows. A workflow process comprises multiple steps and multiple users assigned to the group responsible for providing approval at each step.

Quick Links

Umbraco Workflow is a licensed product that does not require a purchase. New installations default to a trial license while the paid license is available for purchase.

Purchasing an Umbraco Workflow License

You can look at the pricing, plans, and features on the page. If you want to buy an Umbraco Workflow license, use . Existing Plumber license holders who wish to upgrade to Umbraco Workflow should contact us using the contact from on the .

Installing your license

Once you have received your license code it needs to be installed on your site.

1. Open the root directory for your project files.

2. Locate and open the appSettings.json file.

3. Add your Umbraco Workflow license key to Umbraco:Licenses:Umbraco.Workflow:

Verify the license installation

You can verify that your license is successfully installed by logging into your project's backoffice and navigating to the settings section. Here you will see a licenses dashboard which should display the status of your license.

When and how to configure an UmbracoApplicationUrl

The website domain used for validating the license is determined from your Umbraco instance. To ensure the correct one is used, you can configure the UmbracoApplicationUrl.

If you are running on a single domain for both your frontend and backend environments, it's not necessary to configure a UmbracoApplicationUrl.

If you have different domains for your frontend and backend, then it's advised that you configure an UmbracoApplicationUrl set to your backoffice URL. This helps the licensing engine know which URL should be used for validation checks. Without this configuration setting, the licensing engine will try and work out the domain to validate from the HTTP request object. This can lead to errors when switching between domains.

An UmbracoApplicationUrl can be configured in your appSettings.json file like so:

Configuring UmbracoApplicationUrl on Umbraco Cloud

If you are hosting on Umbraco Cloud you will find the configuration described above won't be reflected in your environment. The reason for this is that Umbraco Cloud sets this value as an environment variable set to the Cloud project domain (<your project>.umbraco.io). This overrides what is set via the appSettings.json file.

There are two options in this case:

• Either the domains for each of your Cloud environments can be added to your license.

• Or, for more control and to ensure this value is set correctly for other reasons, you can apply the configuration via code.

For example, in your Program.cs file:

In practice, you will probably want to make this a bit more sophisticated. You can read the value from another configuration key, removing the need to hard-code it and have it set as appropriate in different environments. You can also move this code into a composer or an extension method if you prefer not to clutter up the Program.cs file.

Using a Trial License

The trial license introduces some restrictions around advanced features but is otherwise a full-featured workflow platform. The paid license is valid for one top-level domain and all its subdomains.

To impersonate the full license on a local site, set EnableTestLicense to true in the appSettings.json file:

Validating a license without an outgoing Internet connection

Some Umbraco installations will have a highly locked down production environment, with firewall rules that prevent outgoing HTTP requests. This will interfere with the normal process of license validation.

On start-up, and periodically whilst Umbraco is running, the license component used by Umbraco Workflow will make an HTTP POST request to https://license-validation.umbraco.com/api/ValidateLicense.

If it's possible to do so, the firewall rules should be adjusted to allow this request.

If such a change is not feasible, there is another approach you can use.

You will need to have a server, or serverless function, that is running and can make a request to the online license validation service. That needs to run on a daily schedule, making a request and relaying it onto the restricted Umbraco environment.

To set this up, firstly ensure you have a reference to Umbraco.Licenses version 13.1 or higher. If the version of Workflow you are using depends on an earlier version, you can add a direct package reference for Umbraco.Licenses.

Then configure a random string as an authorization key in configuration. This is used as protection to ensure only valid requests are handled. You can also disable the normal regular license checks - as there is no point in these running if they will be blocked:

Your Internet enabled server should make a request of the following form to the online license validation service:

The response should be relayed exactly via an HTTP request to your restricted Umbraco environment:

A header with a key of X-AUTH-KEY and value of the authorization key you have configured should be provided.

This will trigger the same processes that occur when the normal scheduled validation completes ensuring your product is considered licensed.

This documentation platform covers only major versions of the Umbraco Workflow since Umbraco 9+. If you are using Umbraco Plumber, you will need to go elsewhere.

The documentation for Umbraco 7 and 8 lives on .

In this section, we have summarized the changes to Umbraco Workflow released in each version. Each version is presented with a link to the showing a list of issues resolved in the release. We also link to the individual issues themselves from the detail.

If there are any breaking changes or other issues to be aware of when upgrading they are also noted here.

Release History

This section contains the release notes for Umbraco Workflow 14 including all changes for this version.

14.1.2 (November 14th 2024)

• Adds abstraction over UmbContentWorkspaceContext.readOnlyState to consistently implement readonly document workspaces.

• Fixes invariant culture handling when unlocking a scheduled document.

14.1.1 (November 7th 2024)

• Fixes a bug causing migrations from Workflow 13 to fail on SQL Server.

• Fixes the above exposed a secondary issue where the migration from integer to GUID identifiers was incomplete. This resulted in incorrect relationships between approval groups and tasks in historic Workflow data, and incorrect information displaying the backoffice.

• Adds SQL query performance improvements.

• Adds loading indicator to Workflow tables in the backoffice.

(October 23rd 2024 )

• Adds support for readonly mode when a document is pending workflow approval. Along with the scheduled content lock, this feature requires Umbraco 14.3.0, which is now the minumum version dependency for Umbraco Workflow v14.

• Adds support for Arabic.

• Improves UI in workflow detail overlay. Reduces the number of elements and shifts appropriate data points into tag elements.

• Ensure converting integers to strings uses the invariant culture to avoid unexpected formatting

• Fixes issues related to requesting approval on newly created variant content
• UI updates in workflow detail modal

• Fixes an issue where changes to approval group membership were not correctly persisted

• Compatibility with Umbraco 14

Legacy release notes

Umbraco Workflow is backwards compatible with Plumber data. However, with a new default namespace constituting a major breaking change any existing customization or extension needs to be updated.

To migrate from an Umbraco installation with an existing Plumber installation to Umbraco Workflow, follow these steps:

Every new workflow stores multiple records in the database - one for the workflow instance and one for each task in the workflow. In a multi-lingual site, depending on how you use Workflow, there may also be records generated for each culture variation. These records are used to build the workflow history views in the Umbraco backoffice.

Depending on your requirements, this information may not be required or may only be useful for a short period of time.

Umbraco Workflow 11.1.0 introduces a history cleanup feature similar to those already available in Umbraco CMS and Umbraco Forms.

How it works

The History Cleanup feature is disabled by default. Applying the default history cleanup policy will:

• Delete history older than 28 days. See the KeepHistoryForDays setting.

• Only delete history where the workflow status is Approved, Cancelled, CancelledByThirdParty, or Errored. See the StatusesToDelete setting.

The feature can be enabled in the appSettings.json:

{
  "Umbraco": {
    "Workflow": {
      "HistoryCleanupPolicy": {
        "EnableCleanup": true,
        // Below settings are optional
        "FirstRunTime": string; the time to first run the scheduled cleanup task, in crontab format
        "Period": string; how often to run the task, in timespan format
        "KeepHistoryForDays": int; delete history after this many days
        "StatusesToDelete": refer to StatusesToDelete configuration below
        "CleanupRules": refer to Configuration examples below
      }
    }
  }
}

Overriding global settings

For sites with stricter or more complex requirements, it is possible to override the global settings for individual content nodes and Document Types. This is also managed through appSettings.json configuration. Configuration rules defined in application settings are prioritized over any rules set via the backoffice. It allows the developers to restrict clean up of critical history, while allowing site administrators flexibility to manage non-critical history.

Configuration examples

The below example will apply the following policies:

• History cleanup is enabled globally.

• History items with Approved or Cancelled status are deleted after 90 days.

• Workflow history for node dcf18a51-6919-4cf8-89d1-36b94ce4d963 will never be deleted.

• Workflow history for node 31523089-f648-4883-9087-ef9a0b83129f will be deleted after 10 days for the statuses defined in the global StatusesToDelete property.

• Workflow history for all nodes using the ContentPage Document Type will never be deleted.

• Workflow history with Cancelled status for all nodes using the NewsItem Document Type will be deleted after 100 days (see also StatusesToDelete configuration).

{
  "Umbraco": {
    "Workflow": {
      "HistoryCleanupPolicy": {
        "EnableCleanup": true,
        "KeepHistoryForDays": 90,
        "StatusesToDelete": {
          "Approved": true,
          "Cancelled": true,
          "CancelledByThirdParty": false,
          "Errored": false
        }
        "CleanupRules": {
          "dcf18a51-6919-4cf8-89d1-36b94ce4d963": {
            "EnableCleanup": false         
          }, 
          "31523089-f648-4883-9087-ef9a0b83129f": {
            "KeepHistoryForDays": 10
          },
          "ContentPage": {
            "EnableCleanup": false
          },
          "NewsItem": {
            "KeepHistoryForDays": 100,
            "StatusesToDelete": {
              "Approved": false,
              "Cancelled": true,
              "CancelledByThirdParty": false,
              "Errored": false
            }
          }
        }
      }
    }
  }
}

When calculating node and Document Type policies, the Document Type rules will not be processed if the current workflow instance matches a node rule. Using the above configuration as an example, consider both nodes in the CleanupRules dictionary are using the Document Type ContentPage. In this case, the Document Type rules will not be applied as the node rules are prioritized.

If a value is omitted from the node or Document Type policy, the global value will be used instead. In the above example, the node policy for 31523089-f648-4883-9087-ef9a0b83129f uses the StatusesToDelete value from the global policy that is deleting Approved or Cancelled workflow history.

StatusesToDelete configuration

StatusesToDelete uses a dictionary built from the WorkflowStatus enum type. The default configuration is:

  "HistoryCleanupPolicy": { 
    "StatusesToDelete": {
      "Approved": true,
      "Cancelled": true,
      "CancelledByThirdParty": true,
      "Errored": true,
      "PendingApproval": false,
      "Rejected": false,
      "NotRequired": false,
      "Resubmitted": false
    }
  }

It is possible for a cleanup rule (or the global configuration) to declare a StatusesToDelete property without the full set of status keys. This will not modify the default values.

For example, adding "Approved": false will remove Approved from the deletable statuses, but all other default values will remain. Therefore, to delete approved workflows only, the configuration would look like below, where the default values have been negated:

  "HistoryCleanupPolicy": { 
    "EnableCleanup": true,
    "StatusesToDelete": {
      "Approved": true,
      "Cancelled": false,
      "CancelledByThirdParty": false,
      "Errored": false
    }
  }

Backoffice configuration

Backoffice users with access to the Workflow section will have permission to modify history cleanup rules, while all backoffice users have read-only access.

Rules for content items and their Document Type are set from the History tab of the Workflow content app. The History view in the Workflow section provides a read-only overview of all the history cleanup rules and global configuration.

Content items with no custom cleanup rules defined will display the global defaults.

Umbraco Workflow has its default Dashboards. By default, when you install Umbraco Workflow, you receive two Dashboards: the User Dashboard and the Admin Dashboard. Additionally, Umbraco Workflow replaces the default Umbraco button set in the editor drawer.

Dashboards

Umbraco Workflow adds two Dashboards to your Umbraco project:

• User Dashboard - This Workflow Dashboard is added in the Content section. It displays the tasks requiring approval from the user, current user’s submissions, and stale content (content that needs to be reviewed).
• Admin Dashboard - This Workflow Dashboard is the default view in the Workflow section. It displays a chart of recent workflow activity, chart of content review activity, licensing details, and any relevant upgrade-related messages. You can also view the workflow and content review activity chart for the specified range of days.

Buttons

When a workflow is active on the current node, the Publish button is replaced, linking to the workflow content app.

When no workflow is active, the button state is determined by the current user's permissions.

Umbraco Workflow overrides Umbraco's User/Group publishing permissions. If the user has permission to update the node, they will be able to initiate a workflow process on that node. Umbraco Workflow shifts Umbraco from a centrally administered publishing model (controlled by a site administrator) to a distributed model. In this model, editors publish content based on their responsibilities assigned during the workflows.

In cases, where the content is already in a workflow, a notification is displayed at the top of the editor. Depending on the Workflow Settings, you can enable/disable editing access on a content node in a workflow.

For nodes where the workflow has been disabled, the default Umbraco options are displayed.

Umbraco Workflow adds a Content App to all content nodes in the Content section where a workflow is enabled. The Workflow content app includes three sub-sections:

• Active Workflow

• Configuration

• History

Active Workflow

The Active workflow sub-section provides an interface for managing workflows for the current content node.

When the current node is pending workflow approval, the Active workflow sub-section displays detailed information such as:

• Option to approve, reject, or cancel pending workflow tasks.

• View change description and track differences across pending and completed workflows.

• View the group responsible for approving the pending workflow.

• View pending language variant(s) workflow.

• View the workflow activity (eg. pending approval/task approvals/rejects) for the current workflow process.

You can access Active Workflows from two places - the Content section and the Workflow section (depending on your user permission). Workflow Administrators (those users with access to the Workflow section) can access workflows assigned to a different group. In the Workflow History, these are noted as being performed by the admin.

Approve, Reject, or Cancel pending workflow tasks

Approve Workflow Tasks

To approve a Workflow task, click on the Approve button in the Action section.

Reject Workflow Tasks

To reject a Workflow task, click on the Reject button in the Action section. Depending on the approval stage, the reviewer can decide where to send the rejected task.

For first-stage approvals, the rejected task is sent back to the original editor/author. For second-stage approvals and above, the reviewer can send the rejected task either to the original editor or any other previous workflow group.

Cancel pending Workflow Tasks

To cancel a pending Workflow task, click on the Cancel button in the Action section.

Configuration

The Configuration sub-section provides an interface for configuring the content approval flow for the current node. It also displays any Inherited or Document type approval flows applied to the current content node.

In multi-lingual sites, each variant can have its own approval flow. By default, new variants inherit the configuration set on the default language.

For example, German variants can be approved by the German speakers group, while English variants are approved by the English speakers group.

Content Approval Flow

You can add different groups for different stages of content approval flow. Content Approval flow groups can be reordered via drag and drop. You can also apply the approval flow either for publish and unpublish workflows or only publish workflow.

Approval Flow Types

Approval Flows are available in three types: Content approval flow, Inherited approval flow, and Document type approval flow.

A given content node may have all three approval flow types applied but only one will be applied as per the following order of priority:

Review the current Permissions for Approval Groups in the Approval Groups section for Node-based approvals and Document type approvals only. For more information see the Roles section in the Approval Groups article.

Document type approval flows may contain conditional stages, such as including Translators in the workflow only when the Description property has changed. For more information on settings conditions in Document type approval flows, see the Document type approval flows section in the Workflow Settings article.

Configuration cannot be modified when a content node is in a workflow process.

Content reviews

Content reviews is a tool that allows content editors to keep their content up-to-date. For more information, see the Content reviews section.

History

The History sub-section provides a chronological audit trail of workflow activity for the current node. It displays a table containing the following information:

• Type of Publish

• Who the workflow is requested by

• The date the workflow was requested

• Comments

You can also Filter the records based on the information listed above. Additionally, you can adjust the total number of records displayed on a page.

The Detail button at the end of the record displays an overlay with content similar to the Active workflow sub-section.

The Workflow section provides an administrator view Workflow Dashboard. It displays a chart of recent workflow activity, chart of content review activity, licensing details, and any relevant upgrade-related messages. You can also view the workflow and content review activity chart for the specified range of days.

The Active Workflows view in the Workflow section provides an administrator view of the active Workflows. It displays a table containing the following details:

• Page name/Node with the Language variant.

• Type of Publish.

• Date the workflow was requested on.

• Comment describing the changes.

You can also Filter the records based on the Node, Requested by, Created date, Completed date, Page Language, Workflow Type, and Workflow Status.

Additionally, you can adjust the total number of records displayed on a page.

The Detail button at the end of the record displays an overlay with content similar to the Active workflow sub-section.

When requesting workflow approval for content changes, editors must provide additional information detailing the change.

To submit the content changes, click the Request publish button in the editor footer.

The button opens the request approval overlay:

Depending on the Document Type and Workflow settings, the overlay will provide inputs for:

It is possible to schedule both Publish on and Unpublish on dates in a Publish workflow. Once content has been unpublished, a new workflow process is required to republish the content.

Variant Workflows

If the document varies by culture, the editor must select one or more variants to submit for approval.

When a document is invariant, the variants selector is not displayed, and the approval flow follows the default permissions inheritance pattern.

The editor will not be able to select variants where:

• They do not have permission to edit the language, or

• The variant is already in a workflow.

When submitting multiple variants, a workflow process is started for each variant, using the default permissions inheritance pattern. Newly created variants are automatically assigned the configuration from the default language.

Alternatively, all variants can be submitted in an invariant workflow, where they will be approved in a single workflow process. Invariant workflows use the permissions set on the default language. Editors must have permission to edit all the current node's variants to be able to initiate an invariant workflow.

The invariant workflow will publish all variants, regardless of their node state, that are not already in workflows. This means that previously unpublished variants will be republished when using invariant workflows. In most cases, it is preferable to select the individual variants.

Content Validation and Pending Changes

When submitting for approval, Workflow will automatically save variants with pending changes.

Validation errors are reported in the UI using Umbraco's validation messages.

Umbraco Workflow uses Notifications to allow you to hook into the processes for the backoffice. For example, you might want to execute some code every time an approval group is updated. Notifications allow you to do that. For more information on how Umbraco implements Notifications, see the Using Notifications article.

Notifications

All notifications reside in the Umbraco.Workflow.Core.Notifications namespace and are postfixed with Notification.

Typically, available notifications exist in pairs, with a "before" and "after" notification. For example, the SettingsService class publishes both a WorkflowSettingsSavingNotification and a WorkflowSettingsSavedNotification when settings are modified.

Which one you want to use depends on what you want to achieve. If you want to cancel the action, you will use the "before" notification and use the CancelOperation method on the notification to cancel it. If you want to execute some code after the settings have been updated, then you would use the "after" notification.

ContentReviewService Notifications

ConfigService Notifications

NotificationsService Notifications

GroupService Notifications

WorkflowProcess Notifications

SettingsService Notifications

When working with Umbraco Workflow, you can handle the workflow settings directly in the Backoffice from the Workflow section. You can configure the following from the Workflow Settings section:

• General settings

• New node approval flow

• Document Type approval flows

• Exclude nodes

• Notification Settings

• Email templates

General Settings

You can configure the General Settings from the Settings menu in the Workflow section. The following settings are available:

• Flow type - Determines the approval flow progress. These options manage how the Change Author is included in the workflow:

  • Explicit - All steps of the workflow must be completed and all users will be notified of tasks (including the Change Author).

  • Implicit - All steps where the original Change Author is not a member of the group must be completed. Steps where the original Change Author is a member of the approving group will be completed automatically and noted in the workflow history as not required.

  • Exclude - Similar to Explicit. All steps must be completed but the original Change Author is not included in the notifications or shown in the dashboard tasks.

• Approval threshold - Sets the global approval threshold to One, Most or All:

  • One - Pending task requires approval from any member of the assigned approval group. This is the default behavior for all installations (trial and licensed).

  • Most - Pending task requires an absolute majority of group members. For example, a group with three members requires two approvals and a group with four members requires three approvals.

  • All - Pending task requires approval from all group members.

• Rejection resets approvals - When true, and the approval threshold is Most or All, rejecting a task resets the previous approvals for the workflow stage.

• Allow configuring approval threshold - Enables setting the approval threshold for any stage of a workflow (on a content node or Document Type).

• Lock active content - Determines how the content in a workflow should be managed. Set to true or false depending on whether the approval group responsible for the active workflow step should make modifications to the content. Content is locked after the first approval in the workflow - until then, the content can be edited as normal.

• Administrators can edit - Set to true to allow administrators to edit content at any stage of the workflow, ensuring flexibility and control over the content approval process.

• Mandatory comments - Set to true to require comments when approving workflows. Comments are always required when submitting changes for approval, and are always optional for admin users.

• Allow attachments - Provide an attachment (such as a supporting document or enable referencing a media item) when initiating a workflow. This feature is useful when a workflow requires supporting documentation.

• Allow scheduling - Provides an option to select a scheduled date when initiating a workflow.

• Use workflow for unpublish - Determines if unpublish actions require workflow approval. Set to true to display the Action option when submitting the content for approval.

• Extend permissions - Determines if Umbraco Workflow should extend or replace the users' save and publish permissions. The default behavior is to replace the users' permissions.

New node approval flow

All new nodes use this workflow for initial publishing. You can add, edit, or remove an approval group to/from the workflow.

To add an approval group to the workflow:

1. Go to the Workflow section.

2. Go to the General tab in the Settings menu.

3. Click Choose in the New node approval flow section.
4. Select an approval group to add to the workflow.
5. Click Submit.

6. Click Save.

When you click on the approval group, you are presented with different configuration options for that group. For more information on the approval group settings, see the Settings section in the Approval Groups article.

To remove an approval group, click Remove.

Document type approval flows

Configure default workflows that should be applied to all content nodes of the selected Document Type. This feature requires a license.

To add a Document type approval flow:

1. Go to the Workflow section.

2. Go to the General tab in the Settings menu.

3. Click Add document type in the Document type approval flows section.
4. Select a Document Type from the drop-down list.

5. Select a Language from the drop-down list.

6. Click Choose in the Approval groups.

7. Click Submit.

8. Click Add condition to add a condition to the workflow process.
9. Click Submit.

10. Click Save.

To edit a Document type approval flow:

1. Go to the Workflow section.

2. Go to the General tab in the Settings menu.

3. Click the content node in the Document type approval flows section.
4. Add, Edit, or Remove approval groups from the current workflow.

5. Click Add condition to add or edit a condition to the workflow process.
6. Click Submit.

7. Click Save.

Exclude nodes

Nodes and their descendants selected here are excluded from the workflow process and will be published as per the configured Umbraco user permissions. This feature requires a license.

To exclude a node from the workflow process:

1. Go to the Workflow section.

2. Go to the General tab in the Settings menu.

3. Click Choose in the Exclude nodes section.
4. Select the Content node from the Content tree.
5. Click Choose.

6. Click Save.

Notifications Settings

Umbraco Workflow uses Notifications to allow you to configure email notifications for all workflow activities for the backoffice.

From the Settings view in the Workflow section, the Notifications tab provides access to the following:

• Send notifications: If you wish to send email notifications to approval groups, you can enable it here. If your users are active in the backoffice, email notifications might not be required.

• Workflow email: Provide a sender address for email notifications. This is a mandatory field.

• Reminder delay (days): Set a delay in days for sending reminder emails for outstanding workflow processes. Set to 0 to disable reminder emails.

• Edit site URL: The URL for the editing environment (including schema - http[s]). This is a mandatory field.

• Site URL: The URL for the public website (including schema - http[s]). This is a mandatory field.

• Email templates: Configure which users receive emails for which workflow actions and modify the templates for those emails.

Notifications Overview

Notification emails use HTML templates which render information from the HtmlEmailModel type which lives in the Umbraco.Workflow.Core.Models.Email namespace. While it is possible to modify the email templates from the backoffice, we recommend making changes via an Integrated Development Environment (IDE) of your choice.

The HtmlEmailModel contains the following fields:

The HtmlEmailBase contains the following fields:

Umbraco Workflow provides Settings for determining who receives emails at which stages of a workflow. While these are set to default values during installation, it is recommended to update your Notifications Settings to better suit your installation needs. Emails can be sent to:

• All: All the participants in all workflow stages (previous and current).

• Admin: The admin user.

• Author: The user who initiated the workflow.

• Group: All members of the group assigned to the current task.

By default, all emails are sent to the Group. This might not always be an ideal situation. For example: cancelled workflows would be best sent to the Author only, likewise with rejected.

It might be useful to notify All the participants of completed workflows but even this may be excessive. Depending on your website, you can adjust the best configuration.

Reminders Overview

Umbraco Workflow uses a reminder email system to prompt editors to complete the pending workflows. Reminders are sent using Umbraco's internal task scheduler, every 24 hours after an initial delay. For example, setting the Reminder delay (days) value to 2 in the Workflow Settings section will allow pending workflows to sit for 2 days. After that reminder emails will be sent every 24 hours to all members of the group assigned to the pending workflow task.

The emails use a similar model to the notification emails, also inheriting from HtmlEmailBase. In addition to the inherited fields, HtmlReminderEmailModel includes:

Email Templates

All email templates are fully localized where translations exist. You can edit the email templates in the Backoffice or in your IDE. By default, Umbraco Workflow's email templates are available in the default language.

Creating an Email Template

If you wish to have one or more email templates for different languages, you will need to place all the email templates into the ~/Views/Partials/workflow/email/ folder.

To add templates for other languages:

1. Go to the ~/Views/Partials/workflow/email folder.

2. Copy the required template and paste it into the same folder.

3. Append the culture code to the file name prefixed with an underscore.

For example:

• Default approval request template: ~/Views/Partials/workflow/email/ApprovalRequest.cshtml

• Danish approval request template: ~/Views/Partials/workflow/email/ApprovalRequest_da-DK.cshtml

Sample Email Template

Below is an example of the ApprovalRequest.cshtml email template from the ~/Views/Partials/workflow/email/ folder:

@model Umbraco.Workflow.Core.Models.Email.HtmlEmailModel

@*
    Refer to the documentation for Email templates for a full rundown on the available fields
    or (better option), edit the template in Visual Studio where Intellisense will save you
*@

<!DOCTYPE html>

<html>
<head>
    <!-- will be used as the email subject line -->
    <title>Workflow: Approval request</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
</head>
<body>
    <div>
        <h1>Hello @Model.To.Name,</h1>
        <p>Please review the following page for @Model.Type.ToLower() approval:</p>
        <ul>
            <li>
                <a href="@(Model.CurrentTask?.BackofficeUrl)">@(Model.CurrentTask?.Node?.Name)</a>
            </li>
        </ul>
    </div>
</body>
</html>

Content reviews is a tool that allows content editors to keep their content up-to-date. Content reviews adds a new dashboard to the Workflow section. By default, Content reviews are disabled and can be enabled from Content reviews Settings in the Workflow section.

Video overview

Content Reviews Dashboard

The Content reviews Dashboard provides an overview of the expired content. The dashboard displays a table containing the following details:

• Page name/Node with the Language variant

• Next review due date

• Last reviewed date

• Review period in days

• Review group

Clicking on Mark as reviewed allows the review group member to mark the content as reviewed. Optionally, the review group member can also set the next review date on the content node. The next review date must fall inside the review period set in the Content Reviews Settings.

You can also Filter the records based on the Document Type, Review Group, Next review due date, Last reviewed date, and Expired review Status.

Additionally, you can adjust the total number of records displayed on a page.

Content Reviews Settings

The Content reviews Settings tab provides a range of settings for configuring email notifications, review period days, reminder days, and so on. Using Content reviews, all content has a default review period.

General Settings

You can configure the General Settings from the Content reviews tab in the Workflow section. The following settings are available:

• Enable content reviews - Enable this setting if you wish to remind users to review their content. By default, this option is disabled.

• Send notifications - Enable this setting to send email notification to approval groups when content requires review.

• Treat saving as a review? - Enable this setting to reset the review date when content is saved. Saving a content node recalculates the review date, using the review period assigned to the content node, its Document Type, or the default Review period value. If disabled, content must be explicitly reviewed via the review banner displayed on the content item.

• Review period (days) - The default number of days between content reviews.

• Reminder threshold (days) - Determines how many days prior to the review date the Workflow should notify editors of required reviews. By default, the number of days is set to 1.

Content Review Permissions

You can configure specific review groups to review designated content nodes or Document Types. The review group responsible for reviewing content is determined by the workflow configuration. This means a site with workflow already configured can leverage the existing permissions model for assigning content review responsibilities. By default, content reviews are assigned to the approval group defined in the first stage of the workflow.

Content review permissions can be set at the node or Document Type level, both of which take precedence over any existing Workflow permissions. Permissions are assigned to user roles or groups within each workflow stage. For example:

• Internal Reviewers: Users assigned to roles like Editors or Content Managers may have permissions to review content during the Internal Review stage. They ensure content quality, compliance with standards, and provide feedback for improvements before the content is published.

• External Reviewers: External reviewers are users who are invited to participate in the content review process but do not have Backoffice access. Their main role is to provide feedback or suggest changes based on their expertise or stake in the content being published. This feedback is not managed by Workflow.

The current permissions for a content node are displayed in the Workflow content app on the Configuration tab.

Content Item and Document Type Reviews

You can configure content reviews for individual content nodes or for all nodes of a given Document Type. For both Content Item and Document Type Reviews, the following settings are available:

• Language - Allows you to specify which language version of the content is being reviewed.

• Exclude from review - Enable this setting to ignore the specific content node (or all content nodes of this Document Type) when determining nodes to review.

• Review period (days) - The review period in days between required reviews.

• Review group - The group responsible for reviewing the content node. Can contain more than one group.

• External reviewers - Assign email addresses for reviewers without CMS access. Feedback from external reviewers is not managed by Workflow.

Content Item Reviews

To add a content item review, follow these steps:

1. Go to the Workflow section.

2. Go to the Settings tab in the Content reviews menu.

3. Click Add in the Content item reviews section.
4. Select Content node to add to the Content item reviews section.
5. Select Choose.

6. Select the Language from the drop-down.

7. [Optional] Enable Exclude from Review if you wish to exclude this content node from content review. If you enable this setting, skip to step 12.

8. Enter the Review period in days.

9. Click Choose to add the Review Group.

10. Select an approval group.

11. Select Submit.

12. [Optional] Enter a user in the External reviewers field. For example: john.doe@workflow.com.
13. Click Submit.

14. Click Save.

To Edit a content item review, click on the Content item and update the settings as per your requirement.

To remove a content item review, click Remove.

Document Type Reviews

To add a Document Type review, follow these steps:

1. Go to the Workflow section.

2. Go to the Settings tab in Content reviews.

3. Click Add in the Document-type reviews section.
4. Select Content type to add to the Document-type reviews section.
5. Select Choose

6. Select the Language from the drop-down.

7. [Optional] Enable Exclude from Review if you wish to exclude this Document-type from content review. If you enable this setting, skip to step 12.

8. Enter the Review period in days.

9. Click Choose to add the Review Group.

10. Select an approval group.

11. Click Submit.

12. [Optional] Enter a user in the External reviewers field. For example: john.doe@workflow.com.
13. Click Submit.

14. Click Save Settings.

To Edit a Document-type review, click Edit and update the settings as per your requirement.

To remove a Document-type review, click Remove.

Content Review Notifications

Content review notifications use the email template available at ~/Views/Partials/WorkflowEmails/ContentReviews.cshtml, which can be customized as required. For example to add a corporate branding or send customized messages.

To add templates for other languages:

1. Go to the ~/Views/Partials/WorkflowEmails/ folder.

2. Copy the required template and paste it into the same folder.

3. Append the culture code to the file name prefixed with an underscore.

For example:

• Default approval request template: ~/Views/Partials/WorkflowEmails/ContentReviews.cshtml

• Danish approval request template: ~/Views/Partials/WorkflowEmails/ContentReviews_da-DK.cshtml

The Approval groups view in the Workflow section lists the active groups name, group members, their permissions, and a quick link to email the group.

To add an approval group, follow these steps:

1. Go to the Workflow section.

2. Click on Approval groups.

3. Click Create.

4. Enter a Name for the Approval Group. For example: Danish Editors.

5. Enter the Group Email address in the Settings section to which the notifications will be sent.

6. Select the Group Language from the drop-down list in the Settings section.

7. Click Save.

You can search for a specific group using the Search bar. Select a group from the list to edit its Settings, Roles, Members, and view the group's History.

Approval Groups Settings

The Settings tab consists of the following fields:

• Group Email: Workflow notifications are sent to a generic inbox (a group's email address) rather than the individual group members.

• Group Language: Select a language variant for the email.

• Workflow Activity: Provides a chart displaying an overview of the workflow activity such as approved, cancelled, rejected, or pending approvals for the current group.

Members

The Members tab manages the membership for the given user group. Add members to approval groups to determine which member will be responsible for approving content changes. Group Members can be explicitly added to the group or can inherit group membership from an existing Umbraco group. Ideally, group members are set explicitly to ensure changes made to Umbraco groups do not cause unexpected changes to workflow permissions.

To add a Group member, follow these steps:

1. Go to the Workflow section.

2. Click on Approval groups.

3. Select a group from the list to edit its Members.

4. Go to the Members tab.

5. Click Choose in the Group members section.

6. Select the Users you want to add to the approval group.
7. Click Submit.

8. Click Save.

To remove a Group member, click Remove.

To inherit an existing Umbraco group membership, follow these steps:

1. Go to the Workflow section.

2. Click on Approval groups.

3. Select a group from the list to edit its Members.

4. Go to the Members tab.

5. Click Choose in the Inherited group membership section.

6. Select the User groups you want to add to the approval group.
7. Click Submit.

8. Click Save.

To remove a Group membership, click Remove.

Roles

The Roles tab provides an overview of the current workflow roles for the Group:

• Node-based approvals: This workflow applies only to the specified node.

• Document-type approvals: This workflow applies to all the nodes of a given Document Type.

History

The History tab provides an overview of the workflow activity for the current group. It displays a table containing the following details:

• Page name with the Language variant

• Type of Publish

• Workflow requested by

• Date the workflow was requested on

• Comment describing the changes

You can also Filter the records based on the Document Type, Requested by, Created date, Completed date, Page Language, Workflow Type, and Workflow Status. Additionally, you can adjust the total number of records displayed on a page.

The Umbraco Workflow DataGenerator tool is an extension package for quickly generating Umbraco users and Workflow approval groups and permissions.

The generator gets you up and running for testing or product evaluation without having to manually create any Workflow configuration.

Installation

To install the Umbraco Workflow DataGenerator package (Umbraco.Workflow.DataGenerator), follow these steps:

1. Update appSettings.development.json to enable the Workflow test license. This removes limits on group creation, and enables all features:

1. Run the following command to add the required package references to your Umbraco project:

1. Restart the web application using the following command:

Getting started

The package adds an additional view in the Workflow settings, which provides controls for the data generation task.

The available settings are explained below.

• Number of approval groups - determines how many Workflow approval groups will be created. Defaults to two.

• Number of users - determines how many Umbraco users will be created. Defaults to two.

• Number of groups per workflow - determines how the created groups are allocated into the generated workflows. Defaults to 0, which allocates a random number of groups to each workflow.

• Number of users per group - determines how the created users are allocated into the generated workflow approval groups. Defaults to 0, which allocates a random number of users to each approval group.

When the generator task completes, you will be prompted to take a Workflow tour. The tours can be resumed at any time from the Data generation view.

Groups and users are created with arbitrary names, feel free to rename these to suit.

Reset

Once Workflow configuration has been updated, the environment must be reset before regenerating. Resetting cancels all active workflows and deletes all workflow configuration. Umbraco users are not deleted, but will be reused in future data generation actions.

Umbraco Workflow's default behavior requires one member of an approval group to approve a pending task to advance it through the workflow.

The approval thresholds feature introduces configuration options to set the required number of approvals for a given workflow stage.

The threshold options are:

The workflow detail UI displays the following:

• The status of the current task.

• Approval status for members of the current group.

• Progress towards meeting the threshold for the current approval stage.

• Future tasks and the assigned group and its users.

Approving a task as an administrator immediately satisfies the approval threshold for the task, and will advance to the next workflow stage.

When a task is rejected in a workflow stage where the approval threshold is Most or All, existing approvals can be managed via configuration:

• Existing approvals can be reset, resetting progress toward the approval threshold. In this case, all users in the approval group will be able to approve the resubmitted content.

• Existing approvals can be kept. In this case, users in the approval group who have already approved the task will not be able to approve the resubmitted content.

Related settings and configuration

Approval thresholds are managed via settings in the Workflow section or in the appsettings.json file. Node-specific thresholds are set directly on the workflow configuration in the Workflow content app.

Settings

Configuration

The approval threshold for an individual workflow stage can be set using the control below the stage name. Setting the stage threshold requires the Configuring approval threshold setting to be true.

With Umbraco Workflow, it is possible to customize the functionality with different configuration values.

Editing configuration values

All configuration for Umbraco Workflow is held in the appSettings.json file found at the root of your Umbraco website. If the configuration has been customized to use another source, then the same keys and values discussed in this article can be applied there.

The convention for Umbraco configuration is to have package-based options stored as a child structure. The child structure is added below the Umbraco element and as a sibling of the CMS. Workflow configuration follows this pattern, i.e.:

All Workflow configuration is optional and will fallback to defaults, if not set. The following structure represents the full set of configuration options along with the default values:

Workflow Configuration

ReminderNotificationPeriod

A string that represents the period between checking for, and sending, reminder notifications for overdue workflows. This setting is used in conjunction with ReminderDelay to determine if a workflow is overdue. The default value is eight hours. The permitted value is a TimeSpan-parseable string, for example, 0.00.01:00 for one minute.

ActionNotificationPeriod

A string that represents the period between checking for and sending action notifications for active workflows. The default value is five minutes. The permitted value is a TimeSpan-parseable string, for example, 0.00.01:00 for one minute.

EnableTestLicense

A bool value used to enable or disable the test license. When true, and running Umbraco in development mode, all licensed features are available on local domains.

EmailTemplatePath

A string value representing the path to the email notification templates.

DateFormats

An instance of DateTimeSettings allowing customization of date string formats. The DateTimeSettings class contains properties for long and short date and time strings, plus a long date variation with no minutes.

Colors

An instance of ColorSettings allowing customization of colors used in email notifications. Allows setting alternate values for red, orange, and green use to highlight workflow status in emails.

SettingsCustomization

All Workflow settings can be customized in the appSettings.json file. Settings can be read-only or hidden entirely in the BackOffice. Optionally you can set the values here.

The SettingsCustomization object has two child properties:

• General

• ContentReviews

Both are dictionaries of SettingsCustomizationDetail objects. The value is set to the following structure that contains three settings:

• IsHidden - When true, the corresponding property is not displayed in the backoffice UI

• IsReadOnly - When true, the corresponding property is displayed in the backoffice UI but is not editable

• Value - Sets the value for the corresponding property. This value takes priority over existing values set via the backoffice

All available SettingsCustomization options are illustrated below along with their respective values:

General

FlowType (int)

Sets the workflow type to one of Explicit (0), Implicit (1), or Exclude (2):

ApprovalThreshold (int, requires a license)

Sets the default approval threshold to one of One (0), Most (1), or All (2):

ConfigureApprovalThreshold (bool, requires a license)

When true, allows configuring the approval threshold on individual workflow stages.

RejectionResetsApprovals (bool, requires a license)

When true, and ApprovalThreshold is Most or All, rejecting a task resets progress towards the approval threshold for the current workflow stage.

LockIfActive (bool)

When true, prevents editing content where the node is in an active workflow. When false, content can be edited at any stage of a workflow.

ScheduledContentLock (int)

Sets the scheduled content lock to one of None (0), Workflow (1), or All (2):

MandatoryComments (bool)

When true (default), comments are required when approving a workflow task. When false, comments are optional when approving a workflow task. Comments are always required when submitting changes for approval.

AllowAttachments (bool)

When true, displays an optional media picker when initiating a workflow. The selected media item can be used to provide further context or explanation of the content changes.

AllowScheduling (bool)

When true, displays optional controls for scheduling publish/unpublish when initiating a workflow. The scheduling uses Umbraco's existing content scheduling functionality.

RequireUnpublish (bool)

When true, content must be approved via a workflow when unpublishing. When false, user with appropriate permission can unpublish content without workflow approval.

ExtendPermissions (bool)

When true, Workflow adds additional buttons to the editor footer (Request publish and Request unpublish, if the latter is required). When false, Workflow replaces the existing editor footer buttons.

SendNotifications (bool)

When true, Workflow will send email notifications in response to workflow changes. When false, no emails are sent.

Email (string)

The from address for email notifications.

ReminderDelay (int)

The number of days after which to start sending reminder emails for incomplete workflows.

EditUrl (string)

The URL at which editors access the BackOffice eg https://edit.mysite.com. Used for generating links to nodes in email notifications. Must be fully qualified and not include the /umbraco path.

SiteUrl (string)

The URL at which users access the live site eg https://mysite.com. Used for generating links in email notifications. Must be fully qualified.

NewNodeApprovalFlow (complex type)

When set, this flow is used for all new nodes on the first approval request. Subsequent workflows use the permissions set on the node (or content type, or inherited from an ancestor node). This is a complex type and ideally would not be set via configuration.

DocumentTypeApprovalFlow (complex type, requires a license)

Sets workflow permissions for Document Types (that is: all items of BlogItem type use the same workflow). The Document Type flow is used when a content node has no explicit permissions set. This is a complex type and ideally should not be set via configuration.

ExcludeNodes (complex type, requires a license)

Allows excluding segments of the content tree from the workflow model. This is a complex type and ideally would not be set via configuration.

ContentReviews

EnableContentReviews (bool)

When true, the content review engine will monitor publication dates to determine content review requirements.

ReviewPeriod (int)

Sets the number of days between mandatory reviews. This is a global value that can be overridden at the node or content type level.

ReminderThreshold (int)

Sets the date on which to send notification emails, prior to the review date elapsing. For example, if the ReviewPeriod is 20 and the ReminderThreshold is 3, notifications will be sent in 17 days or 3 days before the review date.

SendNotifications (bool)

When true, Workflow will send email notifications to approval groups, with a digest of expiring and expired content.

PublishIsReview (bool)

When true, publishing a node is treated as a review, and will generate a new review date. When false, content must be explicitly reviewed via the review banner rendered at the top of the editor.

For example: To set the site URL, hide it in the backoffice, and set the content review period but keep the property read-only. The configuration would look like this:

Your Integrated Development Environment (IDE) will provide intellisense for the available settings but does not provide the valid value types. Settings are validated on startup and Umbraco will throw an exception if a known setting is provided with an invalid value.

The Umbraco Workflow History provides a chronological audit trail of workflow activity for all the nodes.

It displays a table containing the following details:

• Page name/Node with the Language variant.

• Type of Publish.

• Editor/Original author requesting the workflow.

• Date the workflow was requested on.

• Comment describing the changes.

You can also Filter the records based on the Document Type, Requested by, Created date, Completed date, Page Language, Workflow Type, and Workflow Status.

Additionally, you can adjust the total number of records displayed on a page.

The Detail button at the end of the record displays an overlay with content similar to the Active workflow sub-section.

Advanced Search further expands Workflow's functionality outside its original content-approval focus, adding a new dashboard for performing deep searches of your website content.

The Advanced Search dashboard is added in the content section for all users.

Advanced Search allows searching any number of content types, optionally filtered to a subset of variants. The search can be performed across all indexed fields, a subset of fields, or all fields using a particular Data Type or Property Editor.

You can do an approximate Search using Lucene's default similarity measurement algorithm.

Search Types

The search types are described below:

• All properties: Searches for a single value across all indexed fields for the selected content types.

• Some properties: Searches the selected properties. A different search term can be provided for each selected property.

• Single property: Searches for a single value in the selected property.

• Data Type: Searches for a single value in all fields where the indexed property uses the selected Data Type (for example, all Textstring type).

• Property Editor: Searches for a single value in all fields where the indexed property uses the selected Property Editor (for example, all types using the Umbraco.TextBox editor).

Optional Fields

Searches can be further refined by restricting results to particular editors, created, or updated date ranges.

The additional fields are all optional.

Search results

Results are displayed in a familiar format, linking to nodes in an infinite editors, which allows users to retain their search results.

Search results include published, unpublished and trashed content, and are filtered according to the current user's content start node(s).