Workflow
workflow
Defines a field type with Workflows containing customizable state transitions for Drupal entities.
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.
Install
composer require 'drupal/workflow:^2.2'
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.
Dependencies
Related Projects
Full Views integration including workflow state field, filter, and argument handlers. Provides a default 'Workflow Entity history' view for displaying transition history. The workflow_transition_history base table is available for custom views.
Complete migration support from Drupal 7 Workflow module. Includes migration plugins for workflows, states, config transitions, transition history, and scheduled transitions.
Via the Workflow Access submodule, integrates with Drupal's node_access system to control content permissions based on workflow states.
Provides action plugins compatible with Views Bulk Operations and core Actions for bulk state changes.
Deep integration with Drupal's Field API. Workflow is implemented as a field type that can be added to any fieldable entity.
The Workflow Access submodule implements hook_node_access_explain() to provide debugging information in Devel Node Access.
Admin Pages
| Title | Path | Description |
|---|---|---|
| Workflows | /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. |
| Add workflow | /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. |
| Edit workflow | /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. |
| Workflow States | /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. |
| Workflow Transitions | /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. |
| Transition labels | /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. |
| Access settings | /admin/config/workflow/workflow/access |
Global settings for the Workflow Access submodule. Configures the node access priority used when calculating access grants. |
| Workflow Access Roles | /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. |
| Cleanup | /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
| Permission | Description |
|---|---|
|
Administer all Workflow configurations and settings. This is a restricted permission. |
|
View, edit and delete all transitions regardless of permission restrictions. This is a restricted permission. Generated per workflow type. |
|
Role is enabled to create state transitions. Determines transition-specific permission on the workflow admin page. Generated per workflow type. |
|
Role is enabled to schedule state transitions. Generated per workflow type. |
|
Role is enabled to view the Workflow state transition history tab on own entity. Generated per workflow type. |
|
Role is enabled to view the Workflow state transition history tab on any entity. Generated per workflow type. |
|
Role is enabled to view a Workflow state transition block/widget and add a state transition on the entity page. Generated per workflow type. |
|
Edit the comment of own executed state transitions. This is a restricted permission. Generated per workflow type. |
|
Edit the comment of any executed state transitions. This is a restricted permission. Generated per workflow type. |
|
Allow user to revert own last executed state transition on entity. This is a restricted permission. Generated per workflow type. |
|
Allow user to revert any last executed state transition on entity. This is a restricted permission. Generated per workflow type. |
Hooks
| Hook | Description |
|---|---|
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
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
- 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.