Umbraco workflow management and Plumber

Umbraco offers a simple out-of-the-box publishing approval system, but it lacks a central way to administer the process and is limited to only two steps: seek approval and publish. Fortunately, the Plumber Umbraco package is here to help!

Out of the box Umbraco

Out of the box Umbraco has some basic workflow management and publishing approval functionality; it is however, very limited and can be time consuming for users to set up.

This approval system/workflow is achieved by setting permissions on user groups so that some users have permissions to publish and others are restricted to only “Send to Publish.” By default, Umbraco has an Editors user group that has full permissions to change and publish pages, and a Writers group that only has permission to modify a page before sending it for publishing approval.

When set up in this way, the basic routes to publishing for these two user groups are as follows:

One major limitation with this out of the box approval process is that users must themselves sign up for notifications on all pages (Umbraco nodes) that they want to receive receive publish request notifications for. Notification settings do cascade to child pages, but cannot be undone or overridden by child pages. For example, turning on “Send To Publish” notifications on the Home (root) node means that you cannot turn them off for any content underneath.

Enabling notifications for the out of the box publish requests is done by right-clicking on the content node, selecting “Notifications” and turning on the “Send To Publish” notifications:

It would be much more favorable to be able to configure approval notifications based on content type as well as inheritance. Better would be if administrators could set this all up for all users and manage it in a central place. Even better again would be if admins can configure more than two stages of approval (HINT… Plumber can do all these things!)

Plumber

Benefits and features of Plumber

Plumber is a free Umbraco package created by Nathan Woulfe that allows a multi stage approval process and workflow to be set up and configured by site admins. Its key features are:

• Users see a dashboard displaying all items that are currently in a workflow and require action (regular users see items related to them, admins see all items).
• Configuring of multi-stage approval processes e.g. a writer changes a page, it goes to an initial approver and then a second approver before publishing.
• The ability to reject as well as approve changes, with the original editor receiving notification about the rejection.
• “Approval groups” allow multiple users to receive notifications about, and be able to approve, publish requests.
• Configuration of the process and approval groups is done in one place by site admins.

With some basic configuration, a multi-stage approval workflow can be quickly setup and applied to the content pages of your choice.

Installation and configuration

Install the package using the developer area of the back office, either by searching for “Plumber” on the package page or by downloading it from the apps area of the Umbraco site. The Workflow icon will then appear in the back office (for users with admin permissions).

This area of the back office allows you to set up approval groups and see some metrics about your workflows.

Once approval groups have been created in the back-office they can be assigned to document types here or assigned to content pages (and their children) via the content tree. Right clicking on a page/node and clicking on “Workflow configuration” shows the Plumber options for that item:

Customizing Plumber

The Plumber source code can be forked or downloaded from Github and then modified, built and reinstalled to Umbraco. To rebuild and install the package from the source code:

1. Navigate to the root of the Plumber project.
2. Run the LocalBuild.bat script in the \BuildPackage folder.
3. A new package zip will be generated in the \BuildPackage\artifacts folder.
4. Install this new zip using the “Install Local” button in the Umbraco back office at Developer > Packages > Install Local.

The Plumber backoffice area can be customized by editing the relevant Angular Javascript and HTML files. In our case we wanted to add an additional email field so that all approval group notifications could be CCd to a non-Umbraco user. To do this we first added the field to the HTML file that renders the approval group options in the back-office:

Workflow/App_Plugins/Workflow/Backoffice/workflow/edit-group.html

<umb-control-group label="@workflow_workflowCCGroupEmailLabel" description="@workflow_workflowCCGroupEmail">

<input type="email" class="umb-editor" ng-model="vm.group.ccGroupEmail" name="ccGroupEmail" />
</umb-control-group>

Then the new field also needs to be added to the matching to the language definition file, so that the backoffice HTML can render the field label and description:

Workflow/App_Plugins/Workflow/Lang/en-US.xml

<key alias="workflowCCGroupEmail">Notifications will be cc'd to this address, it will not override any other email recipients (optional)</key>

<key alias="workflowCCGroupEmailLabel">CC Email</key>

The new field also needs to be added to the vw.group object in the controller:

Workflow/App_Plugins/Workflow/Backoffice/controllers/
groups.edit.controller.js

this.group = {
	groupId: -1,
	name: '',
	description: '',
	alias: '',
	groupEmail: '',
	ccGroupEmail: '', // new field
	users: [],
	usersSummary: ''
};

In order to save the contents of this new field to the database, we also need to add it to the User Group Poco, with the DB column name and Json property name attributes:

Workflow/Models/Pocos/UserGroupPoco.cs

[Column("CCGroupEmail")]
[NullSetting(NullSetting = NullSettings.Null)]
[JsonProperty("ccGroupEmail")]
public string CCGroupEmail { get; set; }

Important: Plumber runs some setup code that takes care of database table creation when it is first installed, therefore adding a new property to the UserGroup object does not automatically create a new column in the database. The code in question is found in:

Plumber\Workflow\Startup\CreateTables.cs

if (!helper.TableExist(Constants.UserGroupsTable))
{
	helper.CreateTable<UserGroupPoco>(false);
}

There are two options for creating this new column: drop the “WorkflowUserGroups” table and reinstall Plumber or manually create the CCGroupEmail column in the database.

In summary, the Plumber extension offers an easy solution for those looking to improve Umbraco’s content editing experience, by adding full content workflow and approval functionality. It’s open-source and can be easily modified to create customized approval steps and notifications; and has an active community and author that are responsive to questions.

Links

Plumber on GitHub

Plumber docs page

Plumber page in Umbraco Apps directory