Workflows: A new tool in the toolbox

Since 2011 we have had access to a content moderation tool in Drupal 7 in the form of Workbench Moderation. This module introduced the concept of Draft ➡ Review ➡ Published workflows, with different user roles having specific permissions to move from one state to the next.

Unfortunately, the underlying Drupal core revision API was not designed to deal with this, and there were some pretty crazy workarounds.

Content moderation has long been a key feature request for Drupal, and so effort was made to port Workbench Moderation across to Drupal 8. 

Content Moderation drove a lot of cleanup in Drupal core APIs, including proper support for forward revisions, and adding revision support to other content entities besides Content Types, such as Custom Blocks. More are on the way.

In Drupal 8.3, the Workflows module was split out of Content Moderation. Why you may ask? Well, because the Workflows module provides the state machine engine that Content Moderation relies on.

What is a State Machine?

A state machine defines a set of states and rules on how you can transition between those states.

In our simple example of a door, it can only be opened, closed or locked. However, you can't go directly from locked to open, you need to unlock it first.

Content Moderation Workflow Configuration

Content Moderation provides a set of Workflow states and transitions by default.

If we were to put this together in a state machine diagram, it would look like the following:

From the above diagram, it becomes clear what the allowed transitions are between states.

So now Workflows has been configured with our Content Moderation states and transitions, what is left for Content Moderation to do?

What Does Content Moderation Do?

It turns out quite a lot. Remember, that Workflows only provides the state machine. It in no way prescribes how you should manage the current state of a particular entity.

Content Moderation provides:

• Default Workflows configuration
• A fairly complex WorkflowType plugin which works with the Revision API.
• Storage for individual states on content entities
• Configuration of which entity bundles (Content types, etc.) should have Content Moderation
• A number of admin forms for configuring the workflows and how they apply
• Permissions

Building an Issue Tracker

We want to build a very simple issue tracker for our example. The state machine diagram is the following:

That's the simple bits out of the way. Now, in order to build an issue tracker, we will need to replicate the rest what Content Moderation does!

Fortunately there is a module that can do most of the heavy lifting for us.

Workflows Field

“This module provides a field which allows you to store states on any content entity and ensure the states change according to transitions defined by the core workflows module.” 

Perfect! Let's download and install it.

Next we want to add a new Workflow. We can assign it a label of Issue Status and you'll see that we have a new Workflows Field option in the Workflow Type dropdown.

We can then configure the desire Workflows states and transitions.

Thats the our Workflows configured. Now we need to create a new Issue content type to attach our workflow to. It's assumed you know how to create a content type already. If not, check out the User Guide.

Next, we need to add our Workflows Field to our Issue content type. Follow the usual steps to add a field, and in the drop down choose Workflows as the field type, and our previously created Issue Status workflow.

Test it out!

Now we can test our our workflow by creating a new Issue from the Content page. If everything was configured correctly, we should see a new field on the edit form for Status.

Given the transitions we defined in our workflow, we should only be allowed to see certain values in the drop-down, depending on the current state.

What next?

That's it for setting up and configuring a custom workflow using Workflows Field. Some next steps would be:

• Add permissions for certain users (there's an issue for that #2904573 )
• Add email notifications

How would you use the new Workflows API?

Let me know in the comments!