Workflows: A new tool in the toolbox
Share:
At DrupalSouth 2017, I presented a session on the new Workflows module, which just went stable in Drupal 8.4.0. Workflows was split out from content moderation as a separate module, and can be used independently to create custom workflows. In this presentation, I gave a demonstration of how to create a basic workflow for an issue tracker.
by
Kim Pepper
/ 29 November 2017
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.
A door state machine
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.
Content Moderation StatesContent Moderation Transitions
If we were to put this together in a state machine diagram, it would look like the following:
Content Moderation State Machine
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:
Issue Tracker State Machine
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.
Add new workflow
We can then configure the desire Workflows states and transitions.
Issue StatesIssue 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.
Add workflows fieldTest 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.
Issue status form
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.
Testing workflow constraintsWhat 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!
Tagged
Posted by
Kim Pepper
Technical Director
Dated 29 November 2017
Add new comment