Revisioning with state-based content access control

This tutorial demonstrates how you can extend the basic Revisioning workflow with state-based content access through the Workflow module. The additional goal we're setting ourselves is:

Enforce segragation of authors and moderators, so that authors can't modify revisions after submission (to the moderators) and moderators can't touch revisions still being worked on by authors.

Begin this tutorial after you've completed either the basic Revisioning workflow tutorial or the tutorial on Revisioning with categorised content (till at least step 7).

To realise our additional requirement, we'll create a simple workflow of three states: "in draft" (i.e with the author), "in review" (i.e. with the moderator) and "live" (i.e. publicly visible). Then we add permissions allowing certain roles to transition states as well as content access grants based on the above states.
As a bonus we'll also add some triggers to support automatic notification of authors and moderators as content transitions between states.
Let's start.

1. Login to your drupal site as administrator.
2. Install the Workflow (includes Workflow Access, which you must enable) and Token modules. Activate the Trigger module (part of core). In our context there's little need to install the Views module; it gives you an additional menu item “Workflow summary”, but Module Grant's Accessible content shows the same information plus more.
3. Create a workflow. Go to Administer>>Site building>>Workflow>>Add workflow, type a workflow name and add three states, “in draft”, “in review” and “live”.
4. Select the content types to which your workflow will apply. If you want moderators to be able to deal with all content types create a single workflow. if you don't want roles that deal with one content type, say page, to see content that is being handled exclusively by another role, say blogs, then it's usually best to create separate, but near-identical, workflows, one per content type.
5. Press the workflow's Edit link (/admin/build/workflow/edit/1) to define which roles may invoke which workflow state transitions. You may want to start with this:

   creation->in-draft (i.e. create initial revision): allow the pre-defined role of “author”
   in-draft-> in-review (i.e. submit for moderation): allow the Author role(s) (e.g. Sports and Arts Authors, if you've just come from the revisioning with content categories tutorial)
   in-review->in-draft (decline author's submission): allow Moderator
   in-review->live (optionally edit, then publish): allow Moderator
   live->in-draft (create new revision of live content): allow Author roles

   In a revisioning workflow, content (a node) normally doesn’t get unpublished. Rather different revisions, old or newly submitted, are made current, while the node as a whole remains published. The live->in-draft state transition doesn't mean that content is taken off the site, it merely makes a piece of content available for modification “behind the scenes” by the appropriate role(s). All the time the “live” (current) revision remains unchanged and visible to the public, until another revision is made current by the moderator. Keep in mind that the “in draft” and “in review” states pertain to new (i.e. pending) revisions, rather than the publicly visible copy. “live” means there is no pending revision to be reviewed. Maybe better names for the states are “with author”, “with moderator” and “with public”.

6. Scrolling down the page, you may want to tick the boxes labeled Show a comment field in the workflow section of the editing form and Show a comment field in the workflow section of the workflow tab form. This comment field may be used, for instance, by a moderator to enter the reason why they declined submitted content, passing it back to the author by putting it “in draft”.
7. Further down, in the Workflow tab permissions section tick Sports and Arts authors and Moderators. These permissions allow roles to invoke state-transitions via the Workflow tab. State transitions may be entered via the content editing form, but if the role has no access to edit the content in the state that it is in (see next point), the Workflow tab becomes the only way a user can invoke a change of state.
8. The thing to note about the Access control section, all the way at the bottom of the page is that these grants have node granularity. As the current revision of the node needs to be viewable to the public regardless of the workflow state it is in, you'll want to grant “view” to anonymous user, as well as Authors and Moderators (or alternatively authenticated users) for all states. Also grant “edit” to the Sports and Arts authors when content is "in draft". For the “in review” state grant "edit" to the moderator role(s) only. Add “delete” where appropriate. To force authors to transition state before they edit content, do not allow "edit" to any role for content that is in the "live" state. Press Save.
   Important: uncheck all "edit ... content" permissions in the "node module" section on the User management >> Permissions page as these will supersede the workflow access controls you've just put in place. Why?
9. You're pretty much there. Still logged in as administrator, press Accessible content and observe that the content summary now has a column for the node's workflow State. Content created prior to the installation of the Workflow module will be flagged as in No state and therefore may not be accessible to anyone but the administrator. The Workflow post install module has a special function that you execute (once) as an administrator after installation of the Workflow module. It puts all old content in a valid workflow state so that it becomes accessible to Authors and Moderators as part of the workflow.

You now have a workflow with clearly segregated “in draft” and “in review” states. As you (as an author) create content, you'll find that moderators don't have access to revisions while still being worked on by authors. It isn't until an author clicks "in review" on the editing form that it becomes accessible to the moderator. From that moment authors can't modify the revision while it's still in moderation. Once a revision has been promoted to “live” an author can again grab that piece of content at any time by transitioning it to “in-draft” (via the Workflow tab). They can repeatedly edit and save content, but it always takes a moderator (or administrator) to review it and make it visible to the public.

A final tweak is for the integration and synchronisation between the Revisioning module, which does most of the heavy lifting, and the Workflow module, which is used primarily for its state-based access control. At the moment, publication (via the Revisioning module) and transitioning to the “live/with-public” state (via Workflow) are separate steps that aren't synchronised. The moderator executes these as separate clicks. To roll these steps into one we can first take away a moderator's permission to (manually) publish: User management>>Permissions (section “revisioning module”): untick “publish revisions”. Then, taking advantage of the Trigger module, go to Site building>>Triggers>>Workflow to configure a “publish the most recent pending revision” action to occur automatically every time the workflow state goes from “in review” to “live”. Now the moderator can only publish by moving content into the “live” state and this transition automatically makes the pending revision current via the action triggered.

As was shown in the basic Revisioning workflow tutorial, by employing triggers we can action state-change notifications, for instance an automatically generated email when a moderator declines an author’s submission as he puts the revision back “in draft”. Create the email action on Site configuration>>Actions, then set the trigger on the desired state transition via Site building>>Triggers>>Workflow.
Note: you may need this Workflow module patch to make the sending of emails work.