Drupal Revisions and Content Moderation — Managing Content Lifecycle

In this tutorial, you'll learn Drupal's revision system and content moderation workflow including viewing revision histories, comparing revisions, reverting to previous versions, managing moderation states and transitions, and scheduling content publication.

What You'll Learn

• How the revision system tracks every edit to content
• Viewing, comparing, and reverting to previous revisions
• Enabling and configuring the Content Moderation module
• Creating workflow states: Draft, Published, Archived
• Setting up transitions between moderation states
• Applying moderation workflows to content types
• Best practices for editorial workflows and revision management

Why It Matters

Content changes over time. Pages are updated, corrected, rewritten, and occasionally need to be rolled back. Revisions provide a complete audit trail of who changed what and when. Content moderation adds governance by ensuring content goes through an editorial workflow before publication. Together they provide accountability, safety, and quality control for content teams.

Real-World Use

A healthcare organization's content team follows this workflow: a subject matter expert creates a Draft of a new patient resource. A medical reviewer moves it to "Clinical Review" state. After approval, a Compliance officer moves it to "Legal Review." Once approved, an editor publishes it. If errors are found post-publication, the editor reverts to a previous revision. Every action is logged with timestamps and editor names.

Learning Path

flowchart LR
  A[Media] --> B[Revisions & Moderation]
  B --> C[Blocks]
  C --> D[Menus]
  D --> E[Layout Builder]
  E --> F[Next: Custom Modules]

Revision System Overview

When the Create new revision setting is enabled, every edit creates a new revision instead of overwriting the previous version.

# Content type revision settings
Content type: Article
Create new revision: true
Require revision log message: true

Each revision stores:

• Title: Content title at that point in time
• Body: Content body at that point
• All field values: Every field's value at that revision
• Author: User who created the revision
• Timestamp: When the revision was created
• Log message: Editor's description of changes made
• Revision ID (vid): Unique identifier for the revision

Viewing Revision History

Navigate to any content item's page and click the "Revisions" tab (or /node/{nid}/revisions).

Revision List Page

The revision list shows:

Revision  | Date               | Author     | Log message
----------------------------------------------------------------------
1.5       | 2026-06-27 14:30   | jdoe       | Updated statistics section
1.4       | 2026-06-26 10:15   | asmith     | Added new paragraph about policies
1.3       | 2026-06-25 16:00   | jdoe       | Fixed typos in introduction
1.2       | 2026-06-24 09:30   | bjohnson   | Initial draft of Q3 update
1.1       | 2026-06-20 11:00   | jdoe       | Created article

Revision Tabs

• View: View the revision's content
• Edit: Edit the revision
• Delete: Remove the revision (only available for non-current revisions)
• Revert: Revert to this revision

Comparing Revisions

Drupal provides a diff view showing changes between two revisions.

<?php

// Load two revisions for comparison
$node_storage = \Drupal::entityTypeManager()->getStorage('node');
$revision_1 = $node_storage->loadRevision(42);
$revision_2 = $node_storage->loadRevision(45);

// Get field differences
$diff = $revision_1->body->value !== $revision_2->body->value;

The diff interface shows:

- Old statistics from 2024 report
+ Updated statistics from 2025 report

Reverting to a Previous Revision

Reverting creates a new revision that restores content to a previous state.

# Revert to revision 42 via Drush
drush revision:revert node 42

# Or via PHP
$node_storage = \Drupal::entityTypeManager()->getStorage('node');
$revision = $node_storage->loadRevision(42);
$node_storage->save($revision);

# View revision history
drush php:eval "
  \$storage = \Drupal::entityTypeManager()->getStorage('node');
  \$vids = \$storage->revisionIds(\$storage->load(42));
  print_r(\$vids);
"

Content Moderation Module

The Content Moderation module provides a workflow system for content publication.

Enabling the Module

1. Navigate to Extend (Manage > Extend)
2. Enable "Content Moderation" module (requires Workflows module)
3. Click "Install"

Default Workflow

After enabling, navigate to Configuration > Workflows > Workflows (or /admin/config/workflow/workflows).

Default "Editorial" workflow:

Workflow: Editorial
Workflow states:
  - draft:
      label: Draft
      published: false
      default_revision: false
  - published:
      label: Published
      published: true
      default_revision: true
  - archived:
      label: Archived
      published: false
      default_revision: true

Workflow transitions:
  - create_new_draft:
      label: Create New Draft
      from: [draft, published]
      to: draft
  - publish:
      label: Publish
      from: [draft, reviewed]
      to: published
  - archive:
      label: Archive
      from: [published]
      to: archived

Custom Workflow States

Create custom states for your editorial Process:

Workflow: Medical Review
States:
  - draft:
      label: Draft
      published: false
  - clinical_review:
      label: Clinical Review
      published: false
  - legal_review:
      label: Legal Review
      published: false
  - ready_to_publish:
      label: Ready to Publish
      published: false
  - published:
      label: Published
      published: true
  - archived:
      label: Archived
      published: false

Setting Moderation for Content Types

After creating a workflow, assign it to content types:

1. Navigate to Structure > Content types > Edit (for each content type)
2. Under "Workflow" check "Enable content moderation"
3. Select the workflow (e.g., Editorial)
4. Save

# Content type configuration with moderation
Content type: Article
Enable content moderation: true
Workflow: Editorial

Revision Log Messages

Revision log messages explain what changed and why. They are required when "Require revision log message" is enabled.

# Good revision log messages
"Updated Q3 financial data with latest quarterly report figures"
"Added new section about remote work policy per HR request"
"Fixed broken link in resources section"
"Reverted to pre-review draft after stakeholder feedback"

<?php

// Set revision log message programmatically
$node->setRevisionLogMessage('Updated pricing table with 2026 rates');
$node->setRevisionUserId(\Drupal::currentUser()->id());
$node->setNewRevision(TRUE);
$node->save();

Scheduled Transitions

Scheduled transitions allow content to be published at a future date.

Using Scheduled Transitions Module

The contributed Scheduled Transitions module extends content moderation with scheduling.

# Scheduled transition configuration
Content: Article 42
Transition: Draft > Published
Scheduled date: 2026-07-01 09:00:00
Author: admin

Programmatic Scheduling

<?php

use Drupal\scheduled_transitions\Entity\ScheduledTransition;

// Create a scheduled transition
$scheduled_transition = ScheduledTransition::create([
  'entity_type' => 'node',
  'entity_id' => 42,
  'entity_revision_id' => 45,
  'workflow' => 'editorial',
  'moderation_state' => 'published',
  'scheduled_date' => new \DateTime('2026-07-01 09:00:00'),
]);
$scheduled_transition->save();

Moderation Best Practices

Workflow Design Principles

• Start simple: Begin with Draft > Published > Archived. Add states only when needed.
• Use descriptive state names: "Clinical Review" is clearer than "State 2".
• Limit transitions: Too many possible transitions confuse editors. Design clear paths.
• Train your team: Document the workflow and train content editors on the process.

Multi-stage Workflow Example

Workflow: Publishing Pipeline
States:
  draft: Draft (only author can edit)
  review: In Review (author + reviewer can edit)
  approved: Approved (read-only, waiting for publication)
  published: Published (visible to public)
  archived: Archived (hidden, read-only)
  expired: Expired (removed from archives)

Transitions:
  submit_for_review: Draft > Review
  approve: Review > Approved
  publish: Approved > Published
  unpublish: Published > Draft
  archive: Published > Archived
  expire: Archived > Expired
  revise: Archived > Draft

Content Moderation for Entity Types

Content moderation works with any entity type that supports revisions:

• Nodes: All content types
• Taxonomy terms: Terms with revision support
• Block content: Custom blocks
• Media: Media entities
• Custom entities: Any revisionable entity type

Common Mistakes

1. Enabling content moderation without revisions: Content moderation requires revisions. If revisions are not enabled for a content type, the moderation selection will not work correctly.
2. Creating overly complex workflows: A workflow with 10 states and 30 transitions confuses editors and slows content production. Start with 3-5 states.
3. Not configuring default revision state: The default revision state for new content should be "Draft" to prevent accidental publication. Set in the content type configuration.
4. Deleting revisions: Deleting old revisions removes the audit trail. If storage is a concern, use the Revision Deletion module for automated cleanup of old revisions.
5. Forgetting to assign transition permissions: Each transition in a workflow can have its own permissions. Ensure the appropriate roles have permission to execute required transitions.

Practice Questions

1. What information is stored in a Drupal revision? How does the revision system differ from simple overwriting?
2. Describe a three-stage editorial workflow with states and transitions that a news organization might use before publishing an article.
3. How would you revert content to a previous revision? What happens to the moderation state when you revert?
4. Challenge: Build a complete content moderation workflow for a publishing company. Create an "Editorial Pipeline" workflow with the following states: Idea, Assigned, In Progress, Copy Editing, Legal Review, Fact Checking, Ready to Publish, Published, Correction Needed, Archived. Define transitions between each state with appropriate permissions (reporters can submit to Copy Editing, editors can publish, etc.). Assign the workflow to an Article content type. Write a Drush command that lists all content currently in "Copy Editing" state with their revision history.

FAQ

Mini Project

Goal: Build a complete editorial workflow for a blog publishing team.

1. Create an "Editorial" workflow with these states:

   • Draft (unpublished, editable by author)
   • In Review (unpublished, editable by editors)
   • Approved (unpublished, read-only)
   • Published (published, visible)
   • Archived (unpublished, read-only)

2. Define transitions:

   • Draft > In Review (Submit for Review)
   • In Review > Approved (Approve)
   • In Review > Draft (Send Back)
   • Approved > Published (Publish)
   • Published > Draft (Unpublish)
   • Published > Archived (Archive)
   • Archived > Draft (Revise)

3. Assign the workflow to an Article content type

4. Enable revision tracking with required log messages

5. Create test content through each workflow stage

6. Compare two revisions using the diff view

7. Revert to a previous revision

8. Configure permissions for each transition for roles: Author, Editor, Publisher

What's Next

With content lifecycle management in place, learn about Blocks and Block Layout for placing dynamic content in theme regions. Then explore Menus and Navigation for building site navigation systems.