Perfecting Permissions: Editorial Workflow

Does your organization require content review before the content gets published? We’ll build a common editorial workflow that allows an author to create and edit his or her own work and submit it for editorial review. Author and editor can collaborate until it’s ready to be passed along for final approval and publication.

Cathy Contributor Avatar

Cathy Contributor

Cathy has been assigned the Contributor role so that she will be able to create and edit her own content.
Eli Editor Avatar

Eli Editor

Eli has been assigned the Editor role so that in addition to being able to do anything a contributor can do, he will be able to edit the work of others and advance content for publication.
Peggy Publisher Avatar

Peggy Publisher

Peggy has been assigned the Publisher role. This is the only role that will be able to make content live on the site. Publishers can do everything that editors and contributors can do.

Last updated 13 March 2012 - Open Source software is constantly evolving. Visit http://training.opensourcery.com/recipes for the most current version of this recipe.

1. Ingredients

Test kitchen recipes are based on our sandbox setup, which includes pre-installed modules used every time. See http://training.opensourcery.com/sandbox/setup to configure your own environment to match these instructions.

The sandboxes for this recipe contain additional configuration strictly to make testing and teaching easier. Three Bartik subthemes are color-coded and the Theme Key module is used to assign the color-coded themes based on the user role so that the role of the user logged into the site is very clear. The steps for this additional configuration are available at http://training.opensourcery.com/recipes/moderation-sandbox

1.1. Staple

  1. http://drupal.org/project/ctools - Enable Chaos tools
  2. http://drupal.org/project/views - Enable Views and Views UI
  3. http://drupal.org/project/advanced_help - Enable Advanced Help
  4. http://drupal.org/project/workbench - Enable Workbench
  5. http://drupal.org/project/workbench_moderation - Use the development version. Enable Workbench Moderation
  6. http://drupal.org/project/diff - Enable Diff

Drush users:

drush dl ctools views workbench workbench_moderation-7.x-1.x-dev diff
drush en ctools views views_ui workbench workbench_moderation diff -y

2. Users and permissions

People > Permissions

We’re working with three pre-created users, each of which is assigned to one of the three pre-created roles that will be used in the workflow. Creating users and roles is routine, but permissions are one of the trickiest things to get right, so that’s where we’ll begin.

2.1. Node permissions

Before setting up the second layer of permissions provided by Workbench Moderation, we’ll set the basic node permissions. These settings are based on the premise that no site content is ever deleted. During development, you might choose to allow the deletion of content.

Permission Contributor Editor Publisher
View own unpublished content [√] [√] [√]
View content revisions [√] [√] [√]
Revert content revisions [ ] [√] [√]
Delete content revisions [ ] [ ] [ ]
Article: Create new content [√] [√] [√]
Article: Edit own content [√] [√] [√]
Article: Edit any content [ ] [√] [√]
Article: Delete own content [ ] [ ] [ ]
Article: Delete any content [ ] [ ] [ ]
Basic page: Create new content [√] [√] [√]
Basic page: Edit own content [√] [√] [√]
Basic page: Edit any content [ ] [√] [√]
Basic page: Delete own content [ ] [ ] [ ]
Basic page: Delete any content [ ] [ ] [ ]

3. Test

Tedious as it seems, it’s a good idea to test that permissions are working as expected before you introduce a new layer of access. It also allows you to see what happens to existing content when you enable moderation.

We’re going to set up in two separate browsers, one for Cathy Contributor and one for Eli Editor so that we can watch as content progresses through the workflow.

3.1. Create an article as Eli Editor

Add content > Article

/sites/default/files/recipes/user_icons/editor.png
  1. In the first browser, logged in as admin, masquerade as Eli Editor.
  2. Create a new article titled “Eli Before Workflow”

3.2. Create an article as Cathy Contributor

Add content > Article

/sites/default/files/recipes/user_icons/contributor.png
  1. In the first browser, logged in as admin, masquerade as Cathy Contributor.
  2. Create a new article titled “Cathy Before Workflow”
  3. Verify that Cathy cannot edit Eli’s article.

3.3. Check Peggy Publisher

Add content

/sites/default/files/recipes/user_icons/publisher.png
  1. Verify that Peggy has links to add articles and pages.
  2. Verify that she can edit Eli’s article.

4. Configure workbench moderation

4.1. Review configuration

Configuration > Workbench: Workbench Moderation

/sites/default/files/recipes/moderation/workflow_simple.png

We will start by using the default states provided by Workbench Moderation and later add new ones. These states are adequate for the simple workflow pictured here. When we add a third role for review prior to publication, then we’ll need to make adjustments.

4.2. Enable the workflow for content types

Structure > Content types > Article: edit

Although we don’t cover this today, it is possible to moderate content on a per-content-type basis. This gets complex very quickly! See http://drupal.org/node/1206854#comment-5241230 for how to enable this.
  1. Publishing options
  2. [ ] Published <-Uncheck this
  3. [√] Promoted to front page <- Leave checked
  4. [ ] Sticky at top of lists <- Leave unchecked
  5. [√] Create a new revision <- Check this!
  6. [√] Enable moderation of revisions <- Can only be checked once the item above is checked. Check this).
  7. Default moderation state: Draft
  8. Save content type
  9. Repeat for the Basic page content type, although don’t promote pages to the front page)

4.3. Set the Workbench Moderation permissions

People > Permissions

Core

There isn’t much to see on the toolbar until we enable Workbench, which we’ll do now to give a place for the link to My Workbench to appear. It’s likely, too, that one or more of these roles will have additional administrative privileges that will make the toolbar useful.

Permission Contributor Editor Publisher
Toolbar [√] [√] [√]

At the bottom of the Permissions page:

Workbench

Permission Contributor Editor Publisher
Administer Workbench settings [ ] [ ] [ ]
Access My Workbench [√] [√] [√]

Workbench Moderation

Permission Contributor Editor Publisher
View all unpublished content [ ] [√] [√]
Administer Workbench Moderation [ ] [ ] [ ]
Bypass moderation restrictions [ ] [ ] [ ]
View moderation history [√] [√] [√]
View the moderation messages on a node [√] [√] [√]
Use “My Drafts” workbench tab [√] [√] [√]
Use “Needs Review” workbench tab [ ] [√] [√]
Moderate all content from Draft to Needs Review * [√] [√] [√]
Moderate all content from Needs Review to Draft [ ] [√] [√]
Moderate all content from Needs Review to Published [ ] [√] [√]

* You must grant this permission to the Contributor. It is limited in scope by the specific node permissions for each content type. In our case, the Contributor role is only allowed to edit its own Articles and Basic Pages, so a user with that role can only move their own content from Draft to Needs review. Cathy Contributor won’t be able to moderate other peoples’ work.

4.4. Check your permissions

Configuration > Workbench: Workbench Moderation > Check permissions (tab)

Workbench has a great feature to help ensure you’ve set up your transitions properly. Test both to be sure that each role can do what you want and also that no roles can do things they’re not supposed to.

5. Watch Contributor > Editor Moderation in Action

5.1. Create an article as Cathy Contributor

Add content > Article

/sites/default/files/recipes/user_icons/contributor.png
  1. In the first browser, logged in as admin, masquerade as Cathy Contributor.
  2. Create a new article titled Contributor FAQ
  3. Note the message that the draft will be placed in moderation.

5.2. View Eli Editor’s Workbench

My Workbench > Needs Review (tab)

/sites/default/files/recipes/user_icons/editor.png

To save yourself the tedium of logging in and out or even masquerading back and forth, we recommend you install a second browser on your system, if you don’t already have one.

  1. In the second browser, logged in as admin, masquerade as Eli Editor.
  2. View My Workbench > Needs Review (tab)
  3. You shouldn’t see anything yet.

5.3. Move Cathy’s work to Needs Review

Workbench > My Drafts

/sites/default/files/recipes/user_icons/contributor.png

Cathy Contributor can move her work from Draft to Needs Review in three places:

  • On the View draft tab of the node, just as soon as she’s saved it
  • On the Moderate tab, where the entire revision history is available
  • From the My Drafts page

Her work will will enter the workflow when she moves it to the Needs Review state.

  1. Move the article we created, Contributor FAQ, into the Needs Review state.
  1. Note that it disappears from Drafts and reappears on the My content page in My Edits. If Cathy bookmarks the page, she can still edit this while it’s in the Needs review state, good for fixing that last typo.

5.4. Publish Cathy’s article

My Workbench > Needs Review (tab)

/sites/default/files/recipes/user_icons/editor.png
  1. Reload Eli Editor’s Needs Review tab.
  2. Locate Cathy’s new article.
  3. Publish it.

5.5. As Cathy, review the published work

My Workbench:

/sites/default/files/recipes/user_icons/contributor.png
  1. Take a look at Cathy’s main workbench page.
  2. Edit the Contributor FAQ
  3. Note that the officially-approved content stays published while this draft goes into moderation.

5.6. Experiment

  1. Try routing the article between Cathy and Eli in ways your organization might use workflow.
  2. Try creating content as Eli.
  3. Switch back to the admin account when you’re done.
What if Eli would like to return the article to Cathy because it needs work? He can send it back by setting it to Draft, but out of the box, it’s difficult to add a message to the page. We’ll fix that as best we can in the section Adjust the views. There is a feature request to make it easier to add comments at http://drupal.org/node/1257650.

6. View the differences between revisions

We’re working with the development version of Workbench Moderation in order to demonstrate how to highlight differences between two revisions. The dev version incorporates output from the diff module, which was installed at the beginning on the recipe.

/sites/default/files/recipes/moderation/diff.png

  1. Diff <- Click the word

  2. Select a radio button in each column

  3. Show Diff

    You can follow plans for an improved user interface in the 2.x version at http://drupal.org/node/1404642.

7. Expanding the Workflow

7.1. Add a new state

Configuration > Workbench: Workbench Moderation

/sites/default/files/recipes/moderation/workflow.png

To add the publisher into the mix, we need a state for content that has been approved by the editor and needs a final review by the publisher.

On the main screen, add a state:

  1. Name: Needs Final Review

  2. Description: Ready for publication

  3. Arrange them in order using the grabber

    • Draft
    • Needs Review
    • Needs Final Review
    • Published
  1. Save

When you save, you’ll see the following warning:

Depending on the changes you have made it may be necessary to reconfigure Views that leverage Workbench Moderation such as workbench_moderation.

The section Adjust the views will address the customizations necessary to take advantage of our new state.

7.2. Enable the transitions

Configuration > Workbench: Workbench Moderation: Transitions (tab)

Next we define the transitions:

Allow us to give editors permission to advance content to publishers.

  1. Needs Review > Needs Final Review
  2. Save

Allow us to give publishers the ability to send the content back to the editors.

  1. Needs Final Review > Needs Review
  2. Save

Allow us to give the publisher permission to publish.

  1. Needs Final Review > Published
  2. Save

7.3. Assign transition permissions

People > Permissions

Set permissions for the new states as follows.

Workbench Moderation We’ll remove the ability for editors and publishers to move content directly from Needs Review to Published and will grant appropriate permissions to the new transitions.

Permission Contributor Editor Publisher
Moderate all content from Needs Review to Published [ ] [ ] [ ]
Moderate all content from Needs Review to Needs Final Review [ ] [√] [√]
Moderate all content from Needs Final Review to Needs Review [ ] [ ] [√]
Moderate all content from Needs Final Review to Published [ ] [ ] [√]

8. Adjust the views

You can find detailed information about working with Workbench Moderation’s views at http://drupal.org/node/1171066, including directions for how to save views as code. Doing so allows you to deploy them from a staging site to a production server more easily and track them in version control systems, protecting all your configuration effort.

8.1. Add an administration page for publishers

Structure > Views > workbench_moderation: edit

8.1.1. Displays

This is a critically important step. Be sure you’re working with the display you think you are!

  1. Click Needs Review Page <- even if it’s already selected I never skip this step.

8.1.2. Needs Review Page details

  1. Click the arrow next to ‘view needs review page’
  2. Choose ‘clone needs review page’
  3. Display Name: Needs Review Page <- click the words
  4. Name: Needs Final Review Page
  5. Apply

8.1.3. Title

  1. Click Needs Review
  2. For: this page (override)
  3. Needs Final Review
  4. Apply (this display)

8.1.4. Filter Criteria

  1. Click Workbench Moderation State: Needs Review
  2. For: This page (override)
  3. [ ] Needs Review <- uncheck this
  4. [√] Needs Final Review <- check this instead
  5. Apply (this display)

8.1.5. Page Settings

Path:

  1. Click admin/workbench/r...
  2. admin/workbench/needs-final
  3. Apply

Access:

  1. Click Permissions
  2. For: This page (override)
  3. (*) Role
  4. Apply (this display)
  5. [√] publisher
  6. Apply (this display)

8.1.6. Fields

The only way to leave a log message is to edit the node, but it can be difficult to find an edit link until content is published, so we’ll add one to all the displays of this view.

8.1.7. Advanced: No Results Behavior

  1. Global: Text area <- Click the words
  2. For: This page (override)
  3. Change “Needs Review” in the text area so it says “Needs Final Review”
  4. Apply (this display)
  5. Save the view

9. Watch Editor/Publisher Moderation in Action

9.1. Create an article as Eli Editor

Add content > Article

/sites/default/files/recipes/user_icons/editor.png
  1. In the first browser, logged in as admin, masquerade as Eli Editor.
  2. Create a new article
  3. Title: Editorial Policies
  4. Body: Just because you can move your work without review by another editor may not mean you should.
  5. Save
  6. Move it Needs Review
  7. Move it to Needs Final Review

9.2. View Peggy Publisher’s Workbench

My Workbench > Needs Final Review (tab)

/sites/default/files/recipes/user_icons/publisher.png
  1. In the second browser, logged in as admin, masquerade as Peggy Publisher.
  2. View My Workbench > Needs Final Review (tab)
  3. Publish Eli’s Editorial Policies article.

10. Design your own workflow

Extend your understanding by working on one of the following:

  1. Allow the publisher to unpublish content.
  2. Alter the workflow to fit your organization
  3. Add features to the workbench views.

11. Get involved!

Workbench Moderation developer stevector says: There is a lot of refactoring work going into the 2.x branch. This work is mostly discussed at http://groups.drupal.org/node/198188 Among other things, the 2.x branch will address the question of log messages for node changes vs. log messages for state changes. Please encourage people to join the discussion in that g.d.o thread if there are changes or features they would like to see implemented.