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 Umbraco Workflow page. If you want to buy an Umbraco Workflow license, use the contact form to get in touch. Existing Plumber license holders who wish to upgrade to Umbraco Workflow should contact us using the contact from on the Workflow product page.

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:

"Umbraco": {
  "Licenses": {
    "Umbraco.Workflow": "YOUR_LICENSE_KEY"
  }
}

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:

{
    "Umbraco": {
        "CMS": {
            "WebRouting": {
                "UmbracoApplicationUrl": "https://admin.my-custom-domain.com/"
            }
        }
    }
}

See the Fixed Application URL documentation for more details about this setting.

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 Startup.cs file, you can add the following to the ConfigureServices method:

services.Configure<WebRoutingSettings>(o => o.UmbracoApplicationUrl = "<your application URL>");

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 Startup.ConfigureServices method.

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.

You can find which features are included in the trial versus the paid license in the Umbraco Workflow page.

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

{
 “Umbraco”: {
   “Workflow”: {
     “EnableTestLicense”: true
   }
  }
}

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 10.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:

  "Umbraco": {
    "Licenses": {
      "Umbraco.Workflow": "<your license key>"
    },
    "LicensesOptions": {
      "EnableScheduledValidation": false,
      "ValidatedLicenseRelayAuthKey": "<your authorization key>"
    }

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

POST https://license-validation.umbraco.com/api/ValidateLicense
{
    "ProductId": "Umbraco.Workflow",
    "LicenseKey": "<your license key>",
    "Domain": "<your licensed domain>"
}

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

POST http://<your umbraco environment>/umbraco/licenses/validatedLicense/relay?productId=<product id>&licenseKey=<license key>

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 our.umbraco.com.

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

Prerequisites

Umbraco Workflow Installation

There are different ways to install Umbraco Workflow:

.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:

2. Add AddWorkflowEmailTemplateProvider() in the ConfigureServices method in the Startup.cs file:

   AddWorkflowEmailTemplateProvider() must be added before AddWebsite().

3. Restart the web application using the following command:

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:
7. Add AddWorkflowEmailTemplateProvider() in the ConfigureServices method in the Startup.cs file:

Using Umbraco Workflow

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

A Workflow Dashboard

A Workflow section

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 of multiple steps and multiple users assigned to the group responsible for providing approval at each step.

Quick Links

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 10 including all changes for this version.

(October 3 2024)

• Ensure scheduling information is displayed in workflow history

• Fixes an issue where dates were not correctly localised for scheduled workflows

• Fixes an issue where scheduled workflows did not apply the release/expire date if the content node was already scheduled

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

(September 12 2024)

• Fixes an issue where an awaited call does not trigger an AngularJS digest, causing the UI to hang.

• Fixes an issue where dates were not correctly localised in the Backoffice

• Fixes an issue related to sending notification emails in sites with a large number of Workflow groups

• BREAKING CHANGE resolving includes removing the DateTimeSettings class. This class allowed setting the preferred format for dates in the Backoffice. These settings were never applied, or were ignored when localising dates. Corresponding settings in app settings should be removed.

[10.3.9] (April 23rd 2024)

• Fixes an issue where SQL query generation exposed a potential injection vector. This fix was also released as a patch for Plumber v2 and v10.

• Fixes discrepancy between a JSON property attribute value and property name in WorkflowTaskCollectionViewModel, which resulted in unexpected JSON values.

• Fixes bug where workflow submission was not respecting user's language access permissions

• Updates internal license validation to handle licenses registered with 'UmbracoWorkflow' or 'Umbraco.Workflow'

• Introduces lazy constructor parameters to prevent database access when Workflow is installed as part of a new Umbraco install

• Adds Italian translations

• Corrects conditions for displaying alert banner in Workflow settings to ensure licensed settings are excluded from hidden or readonly calculations

• Fixes bug where new nodes were not requiring workflow approval due to inherited permissions not being applied

• Fixes bug where 'Lock active content' and 'Allow administrator edits' settings were not correctly applied

• Removes embedded licensing, replaced with Umbraco.Licenses

• Adds external reviewer option for content reviews

• UX improvements for initiating workflows

• Removes 'Applies to' option from node-level workflow configuration as it was superceded by the equivalent global setting

• Aligns embedded licensing UI with Umbraco.Licenses

• BREAKING CHANGE: ContentReviewReminderEmailer.SendReviewReminders.reviews parameter changes from Dictionary<UserGroupPoco, List<ContentReviewConfigPoco>> to Dictionary<IWorkflowGroup, List<ContentReviewConfigPoco>>, which in turn changes the type of the SentEntities property in WorkflowContentReviewsEmailNotificationsSendingNotification and WorkflowContentReviewsEmailNotificationsSentNotification. UserGroupPoco implements IWorkflowGroup, but contains properties not present on the interface. These can be accessed by casting to the implemented type.

• Additional localization cleanup and improvements

• Fixes possible divide-by-zero error in chart generation

• Ensure workflow activity chart only shows stats box when stats exist

• Ensure all Document Type properties are available when configuring conditional workflow stages

• Ensure license prompt is displayed only when install is unlicensed

• Fixes bug where default approval threshold wasn't set correctly when adding new workflow stages

• Fixes bug where users were not persisted as approval group members if they were assigned as part of group creation

• FEATURE => Introduces optional configuration for manadatory comments

• FEATURE => Modifies content lock to allow edits until first workflow action is completed

• Improve UI notification when publish fails on workflow completion

• Improve logged messages when publish fails on workflow completion

• Ensure canEdit flag is set correctly when Workflow application state changes

• Ensure cancelled workflows are never marked as actioned by admin when cancelled by the original change requestor, regardless of their admin status

• FEATURE => History cleanup and retention policies

• Ensure version number is included in package manifest

• Improve UI/UX in submit workflow component

• Remove async void signatures

• Extends valid local license environment names

• Ensure signalR hub is not re-initialised once running

Legacy release 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 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:

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.:

{
  ...
  "Umbraco": {
    "CMS": {
        ...
    },
    "Workflow": {
        ...
    }
  }
}

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

{
  "Workflow": {
    "ReminderNotificationPeriod": Timespan.FromHours(8),
    "EnableTestLicense": false,
    "EmailTemplatePath": "~/Views/Partials/WorkflowEmails",
    "SettingsCustomization”: {...}
  }

Workflow Configuration

ReminderNotificationPeriod

A TimeSpan representing 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.

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.

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:

{
  …
  "MySettingKey": {
    "IsHidden": false,
    "IsReadOnly": false,
    "Value": 42
  }
  …
}

• 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:

{
  "Workflow": {
    …
    "SettingsCustomization": {
      "General": {
        "FlowType": 0|1|2 matching the FlowType enum values,
        "ApprovalThreshold": 0|1|2 matching the ApprovalThreshold enum values,
        "ConfigureApprovalThreshold": bool,
        "RejectionResetsApprovals": bool,
        "LockIfActive": bool,
        "MandatoryComments": bool,
        "AllowAttachments": bool,
        "AllowScheduling": bool,
        "RequireUnpublish": bool,
        "ExtendPermissions": bool,
        "SendNotifications": bool,
        "Email": string,
        "ReminderDelay": int,
        "EditUrl": string,
        "SiteUrl": string,
        "NewNodeApprovalFlow": *,
        "DocumentTypeApprovalFlow": *,
        "ExcludeNodes": *,
      },
      "ContentReviews": {
        "EnableContentReviews": bool,
        "ReviewPeriod": int,
        "ReminderThreshold": int,
        "SendNotifications": bool,
        "PublishIsReview": bool
      }
    }
  }
}

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.

MandatoryComments (bool)

When true, 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, a 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:

{
  "Workflow": {
    "SettingsCustomization": {
      "General": {
        "SiteUrl": {
          "IsHidden": true,
          "Value": "https://www.myawesomesite.com"
        }
      },
      "ContentReviews": {
        "ReviewPeriod": {
          "IsReadOnly": true,
          "Value": 42
        }
      }
    }
  }
}

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.

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.

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:

• A comment describing the changes

• A selector for choosing the workflow type - either publish or unpublish

  • Only visible when Use Workflow for unpublish is set to true

• A selector for choosing the variants to publish

  • Only visible on variant content

• A media picker for choosing a media attachment

  • Only visible when Allow attachments is set to true

• A date picker for setting a scheduled publishing date

  • Only visible when Allow scheduling is set to true and the workflow type is Publish

• A date picker for setting a scheduled unpublishing date

  • Only visible when Allow scheduling is true

It is not possible to schedule a Publish on date in an Unpublish workflow.

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

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 workflow 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:

• Content approval flow: set directly on a content node via the Configuration section in the Workflow tab . This type will take priority over all others.

• Document type approval flow: set in the Settings section. This approval flow will apply to all content nodes of the selected Document Type unless the node has a Content approval flow set. This feature requires a license.

• Inherited approval flow: if a node has no Content approval flow set, nor a flow applied to its Document Type, Umbraco Workflow will traverse the content tree until it finds a node with a Content approval flow and will use this flow for the current change.

Review the current responsibilities for Approval Groups in the Roles tab of 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 can also include conditional stages i.e., only include Translators in the workflow 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.

• Status of the workflow.

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.

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

• 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

The settings below can be set from the Backoffice or via settings customization in the appsettings.json file (refer to Settings customization for implementation instructions).

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.

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 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 Group.

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

5. Enter a Description to remind you why the group exists.

6. Enter the group's Email address in the Settings section to which the notifications will be sent.

7. Select the Language from the drop-down list.

8. Enable offline approval to allow users in this group to approve changes without logging in to the backoffice.

9. Click Save Group.

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.

• Language: Select a language variant for the email.

Enable Offline Approval

You can optionally provide Groups permission to action workflow tasks without logging in to Umbraco. This feature requires a paid license. By Enabling Offline Approval, all email notifications sent to the group members will include a personalized link to a preview page.

The preview page exposes the current saved page with the options to approve or reject the change. It is not possible to edit the content from the offline approval view.

This feature is useful where the approval group membership is a single user who does not use Umbraco. For example, a manager may want to approve media releases before publishing but does not otherwise need access to Umbraco.

Offline approval requires a user to exist in the Backoffice and be assigned to a workflow group. They do not need to know how to use Umbraco or even know their login credentials.

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.

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 Add in the Group members section.

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

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 Add in the Inherited group membership section.

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

To remove a Group membership, click Remove.

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 workflow roles (Node-based approvals or Document type approvals)

• Workflow requested by

• Date the workflow was requested on

• Comment describing the changes

• Status of the workflow

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.

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.

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 Dashboard records based on the Node, Group Email, 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 Workflow section in the Content reviews menu. 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 which review group reviews which content nodes or Document Types. The group responsible for reviewing content is derived from the workflow configuration. This means a site with workflow already configured can leverage that permissions model for assigning content review responsibilities. By default, content reviews are assigned to the approval group in the first workflow approval stage.

Content review permissions can be set at the node or Document Type level, both of which take precedence over any existing Workflow permissions.

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:

• 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.

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 the Language from the drop-down in the Add Content item review settings pane.

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

7. Enter the Review period in days.

8. Click Add to add the Review Group.

9. Select an approval group.

10. Click Submit.
11. Click Submit.

12. Click Save Settings.

To Edit a content item review, click Edit 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 the Content reviews menu.

3. Click Add in the Document-type reviews section.
4. Select Content type to add to the Document-type reviews section.
5. Select the Language from the drop-down in the Add Document-type review settings pane.

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

7. Enter the Review period in days.

8. Click Add to add the Review Group.

9. Select an approval group.

10. Click Submit.
11. Click Submit.

12. 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 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.

• Status of the workflow.

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 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.

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 Workflow section in the Settings menu. 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.

• 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.

• 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 Add in the New node approval flow section.
4. Select an approval group to add to the workflow.
5. Click Submit.

6. Click Save Settings.

When you click on the Edit 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 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. Add workflow approval groups in the Current flow process.

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

9. Click Save Settings.

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 Edit next to the content node in the Document type approval flows section.
4. Select a Language from the drop-down list.

5. Add, Edit, or Remove approval groups from the current workflow.

6. Click Add condition to add a condition to the workflow process.
7. Click Submit.

8. Click Save Settings.

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 Add in the Exclude nodes section.
4. Select the Content node from the Content tree.
5. Click Submit.

6. Click Save Settings.

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/WorkflowEmails/ folder.

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/ApprovalRequest.cshtml

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

Sample Email Template

Below is an example of the ApprovalRequest.cshtml email template from the ~/Views/Partials/WorkflowEmails/ 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>
                @if (!string.IsNullOrEmpty(Model.CurrentTask.OfflineApprovalUrl))
                {
                    <span><a href="@Model.CurrentTask.OfflineApprovalUrl">Offline approval</a> is permitted for this change (no login required).</span>
                }
            </li>
        </ul>
    </div>
</body>
</html>