Workflow
Defines a field type with Workflows containing customizable state transitions for Drupal entities.
workflow
Install
composer require 'drupal/workflow:^2.2'
Overview
The Workflow module provides a powerful state machine implementation for Drupal entities. It allows site builders to define custom workflows with multiple states and configurable transitions between those states. Each workflow can be attached to any entity type (nodes, users, taxonomy terms, etc.) via a dedicated field type.
The module provides granular permission control, allowing administrators to define which roles can perform specific state transitions. Transitions can be executed immediately or scheduled for future execution via cron. A complete transition history is maintained for each entity, including timestamps, users, and optional comments.
The module supports multiple display options for the workflow widget (select list, radio buttons, action buttons, or dropdown button) and can be configured to show in a fieldset with various collapse options. Comments on transitions can be hidden, optional, or required.
Workflow integrates with Views for displaying transition history and supports Drupal's node access system through the Workflow Access submodule. Migration support is provided for upgrading from Drupal 7 Workflow configurations.
Features
- Define unlimited custom workflows with multiple states and transitions
- Attach workflows to any entity type via a dedicated field type
- Configure transition permissions per role with fine-grained control
- Schedule state transitions for future execution via cron
- Maintain complete transition history with timestamps, users, and comments
- Multiple widget display options: select list, radio buttons, action buttons, or dropdown button
- Configurable comment field (hidden, optional, or required)
- Views integration for displaying workflow history
- Node access control based on workflow states (via Workflow Access submodule)
- Event system for reacting to transitions (pre/post transition events)
- Migration support from Drupal 7 Workflow module
- Bulk operations support via Actions (change to next/given state)
- Block plugin for displaying workflow transition form
- Customizable transition labels
- Watchdog logging of state changes
Use Cases
Editorial Publishing Workflow
Create a workflow with states like Draft, Review, Approved, and Published. Configure transitions so authors can move content to Review, editors can approve or reject, and publishers can publish. Use the Workflow Access submodule to hide unpublished content from anonymous users.
Support Ticket Status Tracking
Implement a ticket workflow with states: New, In Progress, Waiting for Customer, Resolved, Closed. Configure the comment field as required so agents must document each status change. Use the transition history view to show the complete ticket timeline.
Document Approval Process
Set up an approval workflow with multiple approval stages. Use scheduling to auto-publish approved documents at specific times. Configure action buttons for a cleaner UI where each state appears as a distinct submit button.
Product Lifecycle Management
Create states for product stages: Concept, Development, Testing, Released, Deprecated, End of Life. Use workflow_permitted_state_transitions_alter hook to enforce business rules about which products can advance based on custom criteria.
User Content Moderation
Implement a moderation workflow where user-submitted content starts in Pending Review, can be Approved or Rejected by moderators. Use the Views integration to create a moderation queue showing all content pending review.
Multi-step Form Wizard Simulation
Use workflow states to track progress through a multi-part process where entities are edited over time. Each state represents a step completion, and the workflow ensures proper sequencing of the process.
Tips
- Use action buttons or dropbutton widget type for workflows with few states - it provides a cleaner, more intuitive interface than dropdowns.
- Enable watchdog logging during development to track state changes, but consider disabling in production for high-traffic sites.
- When using multiple workflows per entity bundle, use the Views-based history display instead of the built-in Workflow tab.
- The 'Author' pseudo-role in transition permissions allows content creators to perform specific transitions on their own content.
- Use hook_workflow_permitted_state_transitions_alter for complex permission logic that cannot be expressed through role-based configuration.
- Consider using the comment field as required for audit trail purposes, especially in compliance-sensitive environments.
- When migrating from D7, customize the migration YAML files to map your specific entity types and field configurations.
Technical Details
Admin Pages 9
/admin/config/workflow/workflow
Lists all defined workflows in the system. From this page, administrators can view existing workflows, access workflow configuration, manage states, transitions, and transition labels. Each workflow displays its ID, label, and status with operations for editing, deleting, and managing states/transitions.
/admin/config/workflow/workflow/add
Form for creating a new workflow. Allows defining the workflow name, machine name, and various settings including form display options, scheduling configuration, comment handling, and watchdog logging.
/admin/config/workflow/workflow/{workflow_type}
Form for editing an existing workflow's settings. Provides the same options as the add form for modifying workflow behavior.
/admin/config/workflow/workflow/{workflow_type}/states
Draggable list for managing workflow states. Allows adding new states, editing labels, activating/deactivating states, reordering via drag-and-drop, and reassigning content from deactivated states to other states.
/admin/config/workflow/workflow/{workflow_type}/transition_roles
Matrix form for configuring which role can perform which state transitions. Displays a grid with source states as rows and destination states as columns, with checkboxes for each role that can perform the transition.
/admin/config/workflow/workflow/{workflow_type}/transition_labels
Form for customizing the labels displayed for each transition. Allows overriding the default 'From State → To State' labels with custom text.
/admin/config/workflow/workflow/access
Global settings for the Workflow Access submodule. Configures the node access priority used when calculating access grants.
/admin/config/workflow/workflow/{workflow_type}/access
Form for configuring which roles can view, edit, or delete content in each workflow state. Only available when the Workflow Access submodule is enabled.
/admin/config/workflow/workflow/cleanup
Administrative tool for cleaning up orphaned and inactive workflow states. Lists states that no longer belong to an existing workflow and states that have been marked inactive. Only enable this submodule when needed for maintenance.
Permissions 11
Hooks 7
hook_workflow_operations
Allows modules to add extra operations to workflow entity list builders. Can add operations for workflows, states, or transitions.
hook_workflow
Allows reacting to workflow events including transition pre/post execution, revert operations, and permission checks. Can reside in module or module.workflow.inc file.
hook_workflow_comment_alter
Allows modules to modify the transition comment before it is saved.
hook_workflow_history_alter
Allows modules to add operations or modify workflow history display. In D8+, prefer using ListBuilder::getDefaultOperations and hook_workflow_operations.
hook_workflow_permitted_state_transitions_alter
Allows adding, removing, or modifying permitted state transitions. Invoked when building the list of available target states.
hook_form_workflow_transition_form_alter
Allows altering the workflow transition form. Useful for customizing the form based on entity type, bundle, or current state.
hook_field_widget_single_element_workflow_default_form_alter
Widget-specific hook for altering the workflow_default field widget form element.
Troubleshooting 6
Ensure the Workflow field is added to the entity bundle and the form display is configured to show the workflow_default widget. Check that the user has 'create {workflow} workflow_transition' permission.
Verify that transitions are configured on the Transitions tab for the workflow. Ensure the user's role has permission for at least one transition from the current state. Check if hook_workflow_permitted_state_transitions_alter is removing transitions.
Ensure cron is running regularly. The module executes scheduled transitions during cron runs. Check that the 'schedule {workflow} workflow_transition' permission is granted and scheduling is enabled in workflow settings.
After configuring access settings, you must rebuild node access permissions at /admin/reports/status/rebuild. Check that workflow_access_priority is set appropriately if using other access control modules.
Workflows cannot be deleted if any fields reference them. Remove all workflow fields that use this workflow first, then delete the workflow.
The creation state is automatically created and represents the initial state before any transition. It should not be shown to users as a target state. Configure your first real state and a transition from creation to that state.
Security Notes 5
- The 'administer workflow' permission is marked as restricted and should only be granted to trusted administrators.
- The 'bypass {workflow} workflow_transition access' permission allows users to ignore all transition restrictions - grant with extreme caution.
- Edit and revert transition permissions are restricted as they allow modification of audit trail history.
- When using Workflow Access, always rebuild node permissions after configuration changes to ensure proper access enforcement.
- Transition comments may contain sensitive information about why state changes occurred - consider who has access to view workflow history.