Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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:
Go to the Workflow section.
Click on Approval groups.
Click Create.
Enter a Name for the Approval Group. For example: Danish Editors.
Enter the Group Email address in the Settings section to which the notifications will be sent.
Select the Group Language from the drop-down list in the Settings section.
Click Save.
You can create a total of 5 groups on unlicensed installations. The paid license removes this restriction.
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.
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.
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:
Go to the Workflow section.
Click on Approval groups.
Select a group from the list to edit its Members.
Go to the Members tab.
Click Choose in the Group members section.
Select the Users you want to add to the approval group.
Click Submit.
Click Save.
To remove a Group member, click Remove.
To inherit an existing Umbraco group membership, follow these steps:
Go to the Workflow section.
Click on Approval groups.
Select a group from the list to edit its Members.
Go to the Members tab.
Click Choose in the Inherited group membership section.
Select the User groups you want to add to the approval group.
Click Submit.
Click Save.
To remove a Group membership, click Remove.
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.
You can set these Roles in the Workflow Settings section. For more information, see the Workflow Settings article.
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 Detail button at the end of the record displays an overlay with content similar to the Active workflow sub-section.
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.
Umbraco 11 Documentation
Umbraco 8 Documentation
Documentation on how to work with Umbraco Workflow in just a few steps
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.
Learn more or purchase Umbraco Workflow to get all the features and support.
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.
If you are migrating from Plumber to Umbraco Workflow, see the Migrate from Plumber to Workflow article.
To get the latest version of Umbraco Workflow, you can upgrade using either of the two options:
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.
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:
Get an overview of the changes and fixes in each version of Umbraco Workflow.
In this section, we have summarized the changes to Umbraco Workflow that were released in each version. Each version is presented with a link to the Workflow issue tracker 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.
Check the Version Specific Upgrade Notes article for breaking changes when upgrading to a new major version.
This section contains the release notes for Umbraco Workflow 15 including all changes for this version.
Compatibility with Umbraco 15
Replaces entity action wrappers with umbExtensionRegistry.appendCondition()
Adds abstraction over UmbContentWorkspaceContext.readOnlyState to consistently implement readonly document workspaces.
Fixes invariant culture handling when unlocking a scheduled document.
Compatibility with Umbraco 15-rc3
Compatibility with Umbraco 15-rc2
Compatibility with Umbraco 15-rc1
You can find the release notes for versions out of support in the Legacy documentation on Github
In this article, we will cover the steps required to install Umbraco Workflow on your website.
There are different ways to install Umbraco Workflow:
To install the Umbraco Workflow package (Umbraco.Workflow), follow these steps:
Run the following command to add a package reference to your Umbraco project:
Restart the web application using the following command:
To install via Visual Studio, follow these steps:
Open your project in Visual Studio.
Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution....
Browse for Umbraco.Workflow.
Select the appropriate version from the Version drop-down depending on the Umbraco version you are using.
Click Install.
Once the package is installed, open the .csproj file to make sure the package reference is added:
To test-drive Umbraco Workflow consider installing the Umbraco.Workflow.DataGenerator package.
Once the installation is completed, you will see the following in the Umbraco Backoffice:
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.
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.
Once you have received your license code it needs to be installed on your site.
Open the root directory for your project files.
Locate and open the appSettings.json file.
Add your Umbraco Workflow license key to Umbraco:Licenses:Umbraco.Workflow:
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.
UmbracoApplicationUrlThe 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:
See the Fixed Application URL documentation for more details about this setting.
UmbracoApplicationUrl on Umbraco CloudIf 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.
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:
The test license is restricted to sites running in a development environment with a debugger attached. Hit F5 in Visual Studio, in Debug mode to enable the test license.
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.
Version specific documentation for upgrading to new major versions of Umbraco Workflow.
This page covers specific upgrade documentation for when migrating to Umbraco Workflow version 14.
If you are upgrading to a new minor or patch version, you can find information about the breaking changes in the Release Notes article.
Version 14 of Umbraco Workflow has a minimum dependency on Umbraco CMS core of 14.1.0. It runs on .NET 8.
Version 14 contains a number of breaking changes, primarily due to the new backoffice introduced in Umbraco 14. The details are listed here:
A new management API has been introduced at umbraco/workflow/management/api
Umbraco CMS dependency was updated to 14.1.0
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.
You can find the version specific upgrade notes for versions out of support in the Legacy documentation on Github.
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:
Uninstall Plumber and remove the /App_Plugins/Plumber folder.
Upgrade your project to Umbraco 11.
Install Umbraco Workflow 11. See the Installing Umbraco Workflow article.
Build the application.
SQL is the preferred database provider for production websites.
Uninstall Plumber and remove the /App_Plugins/Plumber folder.
Upgrade your project to Umbraco 11.
Make a copy of the Value column from the WorkflowSettings table.
Delete the WorkflowSettings table.
Update WorkflowTaskInstance table to allow null values in the GroupId column.
Install Umbraco Workflow 11. See the Installing Umbraco Workflow article.
Build the application.
Update the WorkflowSettings table to restore the previous data to the Value column.
All your existing workflow data and settings are not affected and will be available on your upgraded site.
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.
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.
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.
Learn how to submit content changes for Workflow approval
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.
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.
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 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:
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:
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.
To approve a Workflow task, click on the Approve button in the Action section.
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.
To cancel a pending Workflow task, click on the Cancel button in the Action section.
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.
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 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 is a tool that allows content editors to keep their content up-to-date. For more information, see the Content reviews section.
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.
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.
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.
| Notification | Members | Description |
|---|---|---|
| Notification | Members | Description |
|---|---|---|
| Fields | Description | Visibility Conditions |
|---|---|---|
| Flow Type | Description | Priority |
|---|---|---|
| Notification | Members | Description |
|---|---|---|
| Notification | Members | Description |
|---|---|---|
| Notification | Members | Description |
|---|---|---|
| Notification | Members | Description |
|---|---|---|
Describe the changes
A field for adding comments to describe the changes made to the content.
Always visible.
Action
Allows to choose the workflow type - either Publish or Unpublish.
Visible only when Use Workflow for unpublish is set to true. To enable this setting, go to Workflow > Settings > Use Workflow for unpublish.
Attachment
Upload media or files attachment.
Visible only when Allow attachments is set to true.
Publish on
A date picker for scheduling the content's publishing date.
Editable only when Allow scheduling is set to true and the workflow type is Publish. It is not possible to schedule a Publish on date in an Unpublish workflow.
Unpublish on
A date picker for scheduling the content's unpublishing date.
Visible only when Allow scheduling is set to true.
Variants
Allows selection of language variants to publish.
Visible only for variant content.
Content approval flow
Set directly on a content node via the Configuration section in the Workflow tab.
Highest
Document type approval flow
Set in the Settings section. Applies to all content nodes of the selected Document Type unless overridden by a Content approval flow set directly on the node. Requires a license.
Secondary
Inherited approval flow
Used when a content node has no Content approval flow set, nor a flow applied to its Document Type. Umbraco Workflow will traverse the content tree upwards to find a Content approval flow.
Lowest
WorkflowContentReviewsConfigSavingNotification
IEnumerable SavedEntities
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when ContentReviewService.SaveContentReviewConfig is called in the API. SavedEntities: Gets the collection of IWorkflowConfig objects being saved.
WorkflowContentReviewsConfigSavedNotification
IEnumerable SavedEntities
EventMessages Messages
IDictionary<string,object> State
Published when ContentReviewService.SaveContentReviewConfig is called in the API after the entities have been saved. SavedEntities: Gets the collection of saved IWorkflowConfig objects.
WorkflowContentReviewsEmailNotificationsSendingNotification
Dictionary<UserGroupPoco, List<ContentReviewConfigPoco>> Target
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when ContentReviewReminderEmailer.SendReviewReminders is called in the API before email notifications are sent. Target: Gets a dictionary containing information about the nodes requiring review, and the assigned review groups.
WorkflowContentReviewsEmailNotificationsSentNotification
Dictionary<UserGroupPoco, List<ContentReviewConfigPoco>> Target
EventMessages Messages
IDictionary<string,object> State
Published when ContentReviewReminderEmailer.SendReviewReminders is called in the API after email notifications are sent. Target: Gets a dictionary containing information about the nodes requiring review, and the assigned review groups.
WorkflowContentReviewsReviewingNotification
ContentReviewNodePoco Target
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when ContentReviewService.MarkAsReviewed is called in the API before the node review status is updated. Target: Get an object with information about the node being reviewed.
WorkflowContentReviewsReviewedNotification
ContentReviewNodePoco Target
EventMessages Messages
IDictionary<string,object> State
Published when ContentReviewService.MarkAsReviewed is called in the API after the node review status is updated. Target: Get an object with information about the reviewed node.
WorkflowContentTypeConfigDeletingNotification
IEnumerable<IWorkflowConfig> DeletedEntities
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when ConfigService.DeleteContentTypeConfig is called in the API before the config items are deleted. DeletedEntities: Gets the collection of IWorkflowConfig objects being deleted.
WorkflowContentTypeConfigDeletedNotification
IEnumerable<IWorkflowConfig> DeletedEntities
EventMessages Messages
IDictionary<string,object> State
Published when ConfigService.DeleteContentTypeConfig is called in the API after the config items are deleted. DeletedEntities: Gets the collection of deleted IWorkflowConfig objects. Note these items are no longer in the database and exist only in memory.
WorkflowContentTypeConfigSavingNotification
IEnumerable<IWorkflowConfig> SavedEntities
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when ConfigService.UpdateContentTypeConfig is called in the API. SavedEntities: Gets the collection of IWorkflowConfig objects being saved.
WorkflowContentTypeConfigSavedNotification
IEnumerable<IWorkflowConfig> SavedEntities
EventMessages Messages
IDictionary<string,object> State
Published when ConfigService.UpdateContentTypeConfig is called in the API after the entities have been saved. SavedEntities: Gets the collection of saved IWorkflowConfig objects.
WorkflowNodeConfigDeletingNotification
IEnumerable<IWorkflowConfig> DeletedEntities
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when ConfigService.DeleteNodeConfig is called in the API before the config items are deleted. DeletedEntities: Gets the collection of IWorkflowConfig objects being deleted.
WorkflowNodeConfigDeletedNotification
IEnumerable<IWorkflowConfig> DeletedEntities
EventMessages Messages
IDictionary<string,object> State
Published when ConfigService.DeleteNodeConfig is called in the API after the config items are deleted. DeletedEntities: Gets the collection of deleted IWorkflowConfig objects. Note these items are no longer in the database and exist only in memory.
WorkflowNodeConfigSavingNotification
IEnumerable<IWorkflowConfig> SavedEntities
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when ConfigService.UpdateNodeConfig is called in the API. SavedEntities: Gets the collection of IWorkflowConfig objects being saved.
WorkflowNodeConfigSavedNotification
IEnumerable<IWorkflowConfig> SavedEntities
EventMessages Messages
IDictionary<string,object> State
Published when ConfigService.UpdateNodeConfig is called in the API after the entities have been saved. SavedEntities: Gets the collection of saved IWorkflowConfig objects.
WorkflowEmailNotificationsSendingNotification
IEnumerable<IWorkflowInstance> Target
EmailType EmailType
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when NotificationsService.SendEmailNotifications is called in the API before email notifications are generated and sent. Target: Gets the object describing the workflow instance used to build the email messages EmailType: Gets the enum value describing the email type
WorkflowEmailNotificationsSentNotification
IHtmlEmailModel Target
List<EmailUserModel> Recipients
EmailType EmailType
EventMessages Messages
IDictionary<string,object> State
Published when WorkflowReminderEmailer.Send is called in the API after email notifications are sent. Target: Gets the object describing the email Recipients: Gets the collection of email recipients EmailType: Gets the enum value describing the email type
WorkflowEmailRemindersSendingNotification
IEnumerable<IWorkflowInstance> Target
EmailType EmailType
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when NotificationsService.SendEmailReminders is called in the API before email notifications are generated and sent.
Target: Gets the collection of objects describing the workflow instances used to build the email messages
EmailType: Gets the enum value describing the email type. Will always be EmailType.Reminder
WorkflowEmailRemindersSentNotification
IEnumerable<IWorkflowInstance> Target
List&EmailTaskListModel> Tasks
EmailType EmailType
EventMessages Messages
IDictionary<string,object> State
Published when WorkflowReminderEmailer.Send is called in the API after email notifications are sent.
Target: Gets the collection of objects describing the workflow instances used to build the email messages
Tasks: Gets the collection of objects describing the overdue workflows for each notified user
EmailType: Gets the enum value describing the email type. Will always be EmailType.Reminder
WorkflowGroupCreatingNotification
IWorkflowGroup SavedEntities
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when GroupService.CreateUserGroupAsync is called in the API before the entity is created. CreatedEntity: Gets the created IWorkflowGroup object.
WorkflowGroupCreatedNotification
IWorkflowGroup SavedEntities
EventMessages Messages
IDictionary<string,object> State
Published when GroupService.CreateUserGroupAsync is called in the API after the entity has been created. CreatedEntity: Gets the created IWorkflowGroup object.
WorkflowGroupDeletingNotification
IEnumerable<IWorkflowGroup> DeletedEntities
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when GroupService.DeleteUserGroupAsync is called in the API before the group is deleted. DeletedEntities: Gets the collection of IWorkflowGroup objects being deleted.
WorkflowGroupDeletedNotification
IEnumerable<IWorkflowGroup> DeletedEntities
EventMessages Messages
IDictionary<string,object> State
Published when GroupService.DeleteUserGroupAsync is called in the API after the group is deleted. DeletedEntities: Gets the collection of deleted IWorkflowGroup objects.
WorkflowGroupSavingNotification
IEnumerable<IWorkflowGroup> SavedEntities
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when GroupService.UpdateUserGroupAsync is called in the API before the group is updated. SavedEntities: Gets the collection of IWorkflowGroup objects being saved.
WorkflowGroupSavedNotification
IEnumerable<IWorkflowGroup> SavedEntities
EventMessages Messages
IDictionary<string,object> State
Published when GroupService.UpdateUserGroupAsync is called in the API after the group is updated. SavedEntities: Gets the collection of saved IWorkflowGroup objects.
WorkflowInstanceApprovingNotification
IWorkflowInstance Target
WorkflowAction Action
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when WorkflowProcess.ActionWorkflow is called in the API before the workflow stage is approved. Target: Gets the IWorkflowInstance object being approved. Action: Gets the WorkflowAction being executed. Will be WorkflowAction.Approve.
WorkflowInstanceApprovedNotification
IWorkflowInstance Target
WorkflowAction Action
EventMessages Messages
IDictionary<string,object> State
Published when WorkflowProcess.ActionWorkflow is called in the API after the workflow stage is approved. Target: Gets the approved IWorkflowInstance object. Action: Gets the WorkflowAction being executed. Will be WorkflowAction.Approve.
WorkflowInstanceCancellingNotification
IWorkflowInstance Target
WorkflowAction Action
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when WorkflowProcess.ActionWorkflow is called in the API before the workflow stage is cancelled. Target: Gets the IWorkflowInstance object being cancelled. Action: Gets the WorkflowAction being executed. Will be WorkflowAction.Cancel.
WorkflowInstanceCancelledNotification
IWorkflowInstance Target
WorkflowAction Action
EventMessages Messages
IDictionary<string,object> State
Published when WorkflowProcess.ActionWorkflow is called in the API after the workflow stage is cancelled. Target: Gets the cancelled IWorkflowInstance object. Action: Gets the WorkflowAction being executed. Will be WorkflowAction.Cancel.
WorkflowInstanceCompletedNotification
IWorkflowInstance Target
WorkflowType WorkflowType
EventMessages Messages
IDictionary<string,object> State
Published when WorkflowProcess.HandleCompleteNow or WorkflowProcess.HandleCompleteLater is called in the API after the workflow is completed. Target: Gets the completed IWorkflowInstance object. WorkflowType: Gets the WorkflowType enum value representing the workflow type. Will be either Publish or Unpublish.
WorkflowInstanceCreatingNotification
IWorkflowInstance CreatedEntity
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when WorkflowProcess.InitiateWorkflow is called in the API before the workflow is initiated. CreatedEntity: Gets the IWorkflowInstance object being created.
WorkflowInstanceCreatedNotification
IWorkflowInstance CreatedEntity
EventMessages Messages
IDictionary<string,object> State
Published when WorkflowProcess.InitiateWorkflow is called in the API after the workflow is initiated. CreatedEntity: Gets the created IWorkflowInstance object.
WorkflowInstanceRejectingNotification
IWorkflowInstance Target
WorkflowAction Action
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when WorkflowProcess.ActionWorkflow is called in the API before the workflow stage is rejected. Target: Gets the IWorkflowInstance object being rejected. Action: Gets the WorkflowAction being executed. Will be WorkflowAction.Reject.
WorkflowInstanceRejectedNotification
IWorkflowInstance Target
WorkflowAction Action
EventMessages Messages
IDictionary<string,object> State
Published when WorkflowProcess.ActionWorkflow is called in the API after the workflow stage is rejected. Target: Gets the rejected IWorkflowInstance object. Action: Gets the WorkflowAction being executed. Will be WorkflowAction.Reject.
WorkflowInstanceResubmittingNotification
IWorkflowInstance Target
WorkflowAction Action
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when WorkflowProcess.ResubmitWorkflow is called in the API before the workflow stage is resubmitted. Target: Gets the IWorkflowInstance object being resubmitted. Action: Gets the WorkflowAction being executed. Will be WorkflowAction.Resubmit.
WorkflowInstanceResubmittedNotification
IWorkflowInstance Target
WorkflowAction Action
EventMessages Messages
IDictionary<string,object> State
Published when WorkflowProcess.ResubmitWorkflow is called in the API after the workflow stage is resubmitted. Target: Gets the resubmitted IWorkflowInstance object. Action: Gets the WorkflowAction being executed. Will be WorkflowAction.Resubmit.
WorkflowInstanceUpdatingNotification
IWorkflowInstance Target
WorkflowAction Action
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Base notification class for Approving, Cancelling, Creating, Rejecting, Resubmitting. Can be used in place of these, using the Action value to identify the executed workflow action. Published when WorkflowProcess.ResubmitWorkflow is called in the API before the workflow is updated. Target: Gets the IWorkflowInstance object being updated. Action: Gets the WorkflowAction being executed.
WorkflowInstanceUpdatedNotification
IWorkflowInstance Target
WorkflowAction Action
EventMessages Messages
IDictionary<string,object> State
Base notification class for Approved, Cancelled, Created, Rejected, Resubmitted. Can be used in place of these, using the Action value to identify the executed workflow action. Published when WorkflowProcess.ResubmitWorkflow is called in the API after the workflow stage is updated. Target: Gets the updated IWorkflowInstance objects. Action: Gets the WorkflowAction being executed.
WorkflowResubmitTaskCreatingNotification
IWorkflowInstance CreatedEntity
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when WorkflowProcess.ResubmitWorkflow is called in the API before the workflow task is persisted. CreatedEntity: Gets the IWorkflowTask object being created.
WorkflowResubmitTaskCreatedNotification
IWorkflowInstance CreatedEntity
EventMessages Messages
IDictionary<string,object> State
Published when WorkflowProcess.ResubmitWorkflow is called in the API after the workflow task is persisted. CreatedEntity: Gets the created IWorkflowTask.
WorkflowTaskCreatingNotification
IWorkflowInstance CreatedEntity
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when WorkflowTaskManager.CreateApprovalTask is called in the API before the workflow task is persisted. CreatedEntity: Gets the IWorkflowTask object being created.
WorkflowTaskCreatedNotification
IWorkflowInstance CreatedEntity
EventMessages Messages
IDictionary<string,object> State
Published when WorkflowTaskManager.CreateApprovalTask is called in the API after the workflow task is persisted. CreatedEntity: Gets the created IWorkflowTask.
WorkflowTaskUpdatingNotification
IWorkflowInstance Target
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when WorkflowTaskManager.ResubmitWorkflow is called in the API before the workflow task is updated. CreatedEntity: Gets the IWorkflowTask object being updated.
WorkflowTaskUpdatedNotification
IWorkflowInstance Target
EventMessages Messages
IDictionary<string,object> State
Published when WorkflowTaskManager.ResubmitWorkflow is called in the API after the workflow task is updated. CreatedEntity: Gets the updated IWorkflowTask.
WorkflowSettingsSavingNotification
IEnumerable<ISettings> SavedEntities
EventMessages Messages
IDictionary<string,object> State
bool Cancel
Published when SettingsService.UpdateSettings is called in the API before the settings are saved. SavedEntities: Gets the collection of ISettings objects being saved.
WorkflowSettingsSavedNotification
IEnumerable<ISettings> SavedEntities
EventMessages Messages
IDictionary<string,object> State
Published when SettingsService.UpdateSettings SavedEntities: Gets the collection of saved ISettings objects.
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.
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.
The workflow History exists in addition to Umbraco's audit trail information. It will always show the identity of the user who completes the workflow.
Umbraco Workflow 11.1.0 introduces a history cleanup feature similar to those already available in Umbraco CMS and Umbraco Forms.
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:
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.
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).
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 uses a dictionary built from the WorkflowStatus enum type. The default configuration is:
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:
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.
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.
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
Selecting a content node takes you to the content node in the Content section where you can see the Content review banner. The Content review banner is displayed only when the node has passed its review date. Also, the review banner is displayed only to users assigned as reviewers for the node. For more information, see the Content Reviews Permissions section
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.
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.
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.
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.
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.
When reviews are enabled or any changes to content review settings are saved, Workflow determines the review status. It assesses all the content needing review and provides this data in the Content reviews Dashboard. For large sites, or on the first run, this may take a few seconds to complete.
To add a content item review, follow these steps:
Go to the Workflow section.
Go to the Settings tab in the Content reviews menu.
Click Add in the Content item reviews section.
Select Content node to add to the Content item reviews section.
Select Choose.
Select the Language from the drop-down.
[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.
Enter the Review period in days.
Click Choose to add the Review Group.
Select an approval group.
Select Submit.
[Optional] Enter a user in the External reviewers field. For example: john.doe@workflow.com.
Click Submit.
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.
To add a Document Type review, follow these steps:
Go to the Workflow section.
Go to the Settings tab in Content reviews.
Click Add in the Document-type reviews section.
Select Content type to add to the Document-type reviews section.
Select Choose
Select the Language from the drop-down.
[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.
Enter the Review period in days.
Click Choose to add the Review Group.
Select an approval group.
Click Submit.
[Optional] Enter a user in the External reviewers field. For example: john.doe@workflow.com.
Click Submit.
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 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:
Go to the ~/Views/Partials/WorkflowEmails/ folder.
Copy the required template and paste it into the same folder.
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
Get an overview of various options for customizing the configuration of your Umbraco Workflow installation.
With Umbraco Workflow, it is possible to customize the functionality with different 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:
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.
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.
A string value representing the path to the email notification templates.
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.
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.
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:
These are complex types and are not recommended to have values set from Configuration. Instead, these values can be set from the BackOffice to hidden or read-only to prevent further changes.
Sets the workflow type to one of Explicit (0), Implicit (1), or Exclude (2):
Sets the default approval threshold to one of One (0), Most (1), or All (2):
When true, allows configuring the approval threshold on individual workflow stages.
When true, and ApprovalThreshold is Most or All, rejecting a task resets progress towards the approval threshold for the current workflow stage.
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.
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.
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.
When true, displays optional controls for scheduling publish/unpublish when initiating a workflow. The scheduling uses Umbraco's existing content scheduling functionality.
When true, content must be approved via a workflow when unpublishing. When false, user with appropriate permission can unpublish content without workflow approval.
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.
When true, Workflow will send email notifications in response to workflow changes. When false, no emails are sent.
The from address for email notifications.
The number of days after which to start sending reminder emails for incomplete workflows.
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.
The URL at which users access the live site eg https://mysite.com. Used for generating links in email notifications. Must be fully qualified.
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.
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.
Allows excluding segments of the content tree from the workflow model. This is a complex type and ideally would not be set via configuration.
When true, the content review engine will monitor publication dates to determine content review requirements.
Sets the number of days between mandatory reviews. This is a global value that can be overridden at the node or content type level.
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.
When true, Workflow will send email notifications to approval groups, with a digest of expiring and expired content.
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.
It is possible to include settings outside of those referenced by Workflow. These can be useful for providing values for use in extensions and customizations. These settings are not validated on startup so can have any value.
Use thresholds to configure how many approvals a workflow in Umbraco Workflow requires to be considered complete.
This feature requires a license - learn more about Workflow's licensing model
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:
| Option | Description |
|---|---|
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.
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.
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).
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 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.
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.
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).
Searches can be further refined by restricting results to particular editors, created, or updated date ranges.
The additional fields are all optional.
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).
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.
The package must only be installed into an empty Umbraco application.
To install the Umbraco Workflow DataGenerator package (Umbraco.Workflow.DataGenerator), follow these steps:
Update appSettings.development.json to enable the Workflow test license. This removes limits on group creation, and enables all features:
Run the following command to add the required package references to your Umbraco project:
Restart the web application using the following command:
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.
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.
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:
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.
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:
Go to the Workflow section.
Go to the General tab in the Settings menu.
Click Choose in the New node approval flow section.
Select an approval group to add to the workflow.
Click Submit.
Click Save.
To remove an approval group, click Remove.
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:
Go to the Workflow section.
Go to the General tab in the Settings menu.
Click Add document type in the Document type approval flows section.
Select a Document Type from the drop-down list.
Select a Language from the drop-down list.
Click Choose in the Approval groups.
Click Submit.
Click Add condition to add a condition to the workflow process.
Click Submit.
Click Save.
To edit a Document type approval flow:
Go to the Workflow section.
Go to the General tab in the Settings menu.
Click the content node in the Document type approval flows section.
Add, Edit, or Remove approval groups from the current workflow.
Click Add condition to add or edit a condition to the workflow process.
Click Submit.
Click Save.
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:
Go to the Workflow section.
Go to the General tab in the Settings menu.
Click Choose in the Exclude nodes section.
Select the Content node from the Content tree.
Click Choose.
Click Save.
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.
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.
Duplicate users are removed from email notifications.
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.
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:
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.
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:
Go to the ~/Views/Partials/workflow/email folder.
Copy the required template and paste it into the same folder.
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
Below is an example of the ApprovalRequest.cshtml email template from the ~/Views/Partials/workflow/email/ folder:
| Value | Name | Description |
|---|---|---|
| Value | Name | Description |
|---|---|---|
| Setting | Default | Description |
|---|---|---|
The Detail button at the end of the record displays an overlay with content similar to the sub-section.
When the application restarts, it will automatically install .
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 section in the article.
: Configure which users receive emails for which workflow actions and modify the templates for those emails.
| Fields | Data Type | Description |
|---|
| Fields | Data Type | Description |
|---|
| Fields | Data Type | Description |
|---|
One (default)
Pending tasks require approval from any member of the assigned approval group.
Most
Pending tasks require approval from an absolute majority of group members. Example: A group with 3 members requires 2 approvals and a group with 4 members requires 3 approvals.
All
Pending tasks require approval from all group members.
Approval threshold
0 (One)
Sets the global approval threshold.
Rejection resets approvals
false
When true, and the approval threshold is Most or All, rejecting a task resets the previous approvals for the workflow stage.
Configure approval threshold
false
When true, enables setting the approval threshold for any stage of a workflow (on a content node or Document Type).
0 (default)
Explicit
Requires all steps be approved, including steps where the original change author is a group member.
1
Implicit
Auto-approves steps where the author is a member of the approving group.
2
Exclude
Behaves similarly to Explicit, but excludes the original author from any notifications (that is the author can not approve their own work).
0 (default)
One
Pending tasks require approval from any member of the assigned approval group.
1
Most
Pending tasks require approval from an absolute majority of group members. Example: A group with 3 members requires 2 approvals and a group with 4 members requires 3 approvals.
2
All
Pending tasks require approval from all group members.
WorkflowType | WorkflowType | An |
ScheduledDate | DateTime | If a scheduled date exists for the workflow, it is found here. |
Summary | IHtmlString | A pre-generated representation of the current workflow state. |
CurrentTask | WorkflowTaskViewModel | The view model data for the current workflow task. Contains a lot of useful data, best explored via Intellisense. |
Instance | WorkflowInstanceViewModel | The view model data for the current workflow. Best explored via Intellisense. |
SiteUrl | string | The public URL of your site. |
NodeName | string | The name of the node from the current workflow. |
Type | string | The workflow type including the scheduled date (if exists). |
EmailType | EmailType | An |
To | EmailUserModel | The model defining the receiver of the email. |
string | The user's email address or a group address (if a group email is being sent). |
Name | Name | The user's name. |
Language | string | The user's language. |
Id | int | The user's ID or group ID (when sending to a group email address). |
IsGroupEmail | bool | Is the email being sent to a generic group email address? |
OverdueTasks | IList | A list containing all the overdue tasks assigned to the current user. |
TaskCount | int | The count of overdue tasks assigned to the current user. |
