D8 Module: Workbench Moderation

Each day, between migrations and new projects, more and more features are becoming available for Drupal 8, the Drupal community's latest major release. In this series, the Acquia Developer Center is profiling some prominent, useful, and interesting projects--modules, themes, distros, and more--available for Drupal 8. This week: Workbench Moderation.

I spoke with Joe Purcell, Technical Analyst and Senior Web Developer with Digital Bridge Solutions; Ken Rickard, Director of Professional Services at Palantir.net; and Larry Garfield Director of Runtimes, Integrations, Engines, and Services at Platform.sh about Workbench Moderation (aka WBM). Joe and Larry are both recent alumni of Palantir.net, where Workbench Moderation was originally created by a team of "Palantiri" at DrupalCon San Francisco in 2009. Larry told me, "WBM has gone through many hands while at Palantir, and is in essence maintained by the company as a whole." The Drupal 8 port was carried out in the spring of 2016 as a part of Acquia's D8 Module Acceleration Program.

What does the Workbench Moderation Module do?

Workbench Moderation is a key component in the Workbench suite of modules--Workbench, Workbench Access, and Workbench Moderation. As Ken Rickard puts it, "Workbench makes complex tasks simple and provides a common user experience that makes Drupal easier to use."

Larry describes a common situation, "At Palantir.net, we often got requests from academic clients for 'approval workflows'. Usually clients would describe highly complex ideal workflows, but after some discussion, they realized all they really needed was save-as-draft and someone-else-approves. Workbench Moderation was built to easily handle both of those use cases, which it turns out is the 85% use case."

Ken adds, "We tracked the common workflow issues we were being asked to solve, and collaborated on an approach that we could apply to all future projects."

So Workbench was developed for Drupal 7 to address a set of common editorial problems:

• An editorial workspace customized for each editor, which shows what work needs to be done next.
• A draft-revision-published workflow.
• Review states that require permission to publish content.
• The ability to create a new "forward revision" waiting for approval while retaining the published version.
• An extensible, consistent workflow system.
• Access controls that grant access to specific sections of a website using a hierarchy that maps to an organization chart.

Workbench Moderation enables "forward revisions" on content; each revision gets marked in a particular state. These states are often simply "Draft", "Needs Review", and "Approved/Published", but WBM is completely configurable. You can add "Needs Legal Signoff" or any other state to the approval workflow. Via configuration and permissions you can also control who is able to move the forward revision from one state to another. This lets you reflect the roles of authors, editors, moderators, or your legal department. Revision states can also be set to cause an entity to become the new default revision, and to make it published or not, thereby allowing for an "archived" state.

"In Drupal 7, it only worked for nodes," Larry explained to me, "For Drupal 8, it works on (almost) any content entity that supports revisions and bundles. In core that's Nodes and Block Content, but it can work with others, too."

As of mid-2016, roughly 29,300 sites report using the base Workbench Module, 6,300 Workbench Access, and 24,000 Workbench Moderation (including 1,100 Drupal 8 sites).

Read the Workbench Module project page on Drupal.org for more information on the Workbench suite of modules and how they work together.

An important tool for site administrators

Workbench Moderation is a site administrator's friend. Larry Garfield walked me through some different "levels" of Workbench Moderation use cases from simple to advanced:

• Simple: "WBM covers the low-to-middle end of content moderation needs pretty much out-of-the-box. In its simplest configuration, it provides "save as draft" type functionality very easily. In my experience, the default configuration is usable for most sites without any further modification."
• Level up: "By giving different user roles access to move content to different states, the common ‘contributors can post articles, but only editors can approve them' use case is set up and covered in about 10 minutes."
• Bonus round - Do it later: "When combined with the new Scheduled Updates Module, both publishing and un-publishing can be scheduled to happen automatically at some point in the future."
• Boss level: "WBM works on a single entity at a time. That means it does not cover publishing a large set of content all at once. However, it does integrate with the new Workspace Module to allow the Workspace itself to be moderated as a whole," (Joe Purcell also told me about his work on this feature), "Marking a Workspace published in WBM triggers the Workspace to be published all at once. For very advanced use cases, I'd recommend this process."

Example: Build a support ticketing system

WBM lets you model any state-based, sequential workflow you need. Joe Purcell helped me understand this power and flexibility of Workbench Moderation with the following example. Here he describes creating a complex ticketing system that includes custom moderation states and transitions between them.

Joe, "This is just example off the top of my head. The point is you can now create interesting workflows in a few minutes that once would have required weeks of custom development to implement."

• Write a custom module to inspect new tickets to determine if their state should go to Tier 1, Tier 2, or Tier 3 support.
• Set Tier 1 support staff to be able to escalate to Tier 2 (and Tier 2 to Tier 3), or send the ticket out of support to a completely separate department by switching the state to say "Client Relations" for perhaps giving them a discount or the like.
• Allow Tier 3 support to be able to send the ticket over to the development team by setting it to a particular state, and perhaps you have a custom module that reads that state and instead of moving it out of Tier 3 it gets automatically linked to and synced with a ticket in the Production Team's ticketing system.

Introduction to Workbench for Drupal 8 - Palantir.net screencast by Ken Rickard

Same functionality, simpler implementation in Drupal 8

Ken Rickard: "Drupal 8 has not significantly changed Workbench; the nature of the functionality for site users administrators is identical. Some changes to the architecture were required by Drupal 8, but Workbench Moderation was in fact easier to write in Drupal 8 because of changes to how core saves node revisions (a patch we worked on during the development cycle). Workbench proper is mainly a collection of Views, made easier since Views is part of Drupal 8 core."

From the developer's perspective, Larry Garfield continues, "Drupal 7 didn't allow for forward revisions, so Workbench Moderation and modules like it needed to do all sorts of ugly contortions to make it work. The Drupal 8 version is vastly simpler. Drupal 7 required hundreds of lines of code to dance around core's inability to handle forward revisions, database transactions, and other hard-coded assumptions. All of that complication is gone in Drupal 8."

"WBM for D8 also leverages core's APIs more directly, because they're now there to be leveraged. For instance, in Drupal 7 the defined states, transitions, and tracking of what entity revision was in what state was all one-off, manual code. In Drupal 8, states and transitions are simply config entities and entity revisions simply have an entity-reference field to point to their appropriate state. One of the WBM developers, Steve Persch, helped improve the core Entity API to allow forward revisions to happen. That vastly simplified the Drupal 8 version, as well as making the core Entity API better."

A few words from my guests

Joe Purcell: "The last few weeks I have been focusing on Workbench Moderation and spending some time working with other module developers to achieve a high level concept that allows being able to create workspaces (buckets of content) that can be moderated and published."

Ken Rickard: "I've been working on Workbench and Workbench Access as part of learning Drupal 8, and we're implementing them on client projects now. Patrick Weston, one of Palantir's developers, has already written a node reference extension to Workbench Access for that client project. Those modules are in alpha state, and we've probably spent 100+ hours on them so far."

Larry Garfield: "As the primary author of WBM for D8, I took great care to make the code as ‘functional-OOP' as possible. There's extremely little in the .module file, even hooks are shunted off to services. Almost every method in the code base is an idempotent pure function. It's not perfect, but I'm happy with how clean the code base ended up being. It's also a good example of how to enhance entities through the new Entity API, by adding information and handlers to their annotation block via code."

Thank you!

Palantir.net supported and contributed to upgrading Workbench to Drupal 8. "The Drupal 8 development was fairly straightforward, but did require a ground-up rewrite," according to Ken Rickard. "Workbench Moderation was part of the Module Acceleration Program and funded by Acquia, with major code contributions from Lee Rowlands of PreviousNext. The full port took about three months."

Thanks for work on the Drupal 8 ports to all of the following and anyone whom I've failed to mention here!

• Palantir.net
  • Larry Garfield (crell)
  • Joe Purcell (josephdpurcell)
  • Bec White (becw)
  • Patrick Weston (patrickfweston)
  • Robin Barre (robeano)
  • Ashley Cyborski
  • Ken Rickard (agentrickard)
• Community
  • Lee Rowlands (larowlan)
  • James Kennedy (JamesK)
  • Adam (acbramley)