Rules
A business rules engine that allows site administrators to define conditionally executed actions based on occurring events (ECA-rules).
rules
Install
composer require 'drupal/rules:^4.0'
Overview
The Rules module provides a powerful and flexible framework for automating actions on your Drupal site based on events that occur. Using an Event-Condition-Action (ECA) pattern, site administrators can create sophisticated business logic without writing code.
Rules operates through two main concepts: Reaction Rules which trigger automatically when specific events occur (like saving content, user login, or cron runs), and Components which are reusable rule sets that can be called from other rules or invoked programmatically.
The module provides an extensive plugin system with numerous built-in events (entity CRUD, user actions, system events), conditions (data comparison, entity checks, user role verification), and actions (send email, modify entities, show messages, redirect pages). Developers can extend these with custom plugins.
Rules features a sophisticated context and data selection system using typed data, allowing complex data manipulation through selectors like 'node.uid.entity.name.value'. The module includes comprehensive debugging capabilities with on-screen logging and system log integration.
Features
- Event-driven automation with reaction rules that trigger on Drupal events (entity save, delete, user login/logout, cron, page view)
- Conditional logic with AND/OR containers, negation support, and complex nested conditions
- Extensive action library including email sending, entity CRUD operations, user management, page redirects, and system messages
- Reusable rule components that can be invoked from other rules or programmatically
- Data selector system for accessing and manipulating nested entity data using typed data paths
- Built-in context providers for current date, current path, and site information
- Debug logging with configurable verbosity and optional system log integration
- Import/export functionality for rules via configuration management
- Drush commands for managing rules from the command line
- Bundle-specific event filtering for entity events
- Extensible plugin architecture for custom events, conditions, and actions
- Auto-save functionality that batches entity saves for performance
Use Cases
Send welcome email on user registration
Create a reaction rule triggered by 'After saving a new entity' filtered to User entities. Add an action 'Send email' with the new user's email in the 'To' field, a welcome subject, and personalized message body using tokens like [user:display-name].
Notify administrators when content is published
Create a reaction rule triggered by 'After updating an entity' for Node entities. Add a condition 'Node is published' and optionally filter by content type. Add 'Send email to users of role' action targeting the 'administrator' role.
Automatic user role assignment based on profile field
Create a reaction rule for 'After updating an entity' on User entities. Add a condition checking a profile field value (e.g., verified status). Add 'Add user role' action to grant the appropriate role when conditions are met.
Redirect users after login based on role
Create a reaction rule triggered by 'User has logged in'. Add conditions checking 'User has role' for different roles. Use 'Page redirect' action to send administrators to the dashboard and regular users to their profile.
Unpublish content containing specific keywords
Create a reaction rule for 'Before saving an entity' on Node entities. Add a 'Text comparison' condition checking if the body field contains prohibited words. Add 'Unpublish content' action and 'Show message' to notify the author.
Scheduled content actions via cron
Create a reaction rule triggered by 'Cron maintenance tasks are performed'. Use 'Fetch entities by field' to find content matching criteria (e.g., expired date). Loop through results and perform actions like unpublishing or sending notifications.
Create reusable notification component
Create a Rules component that accepts a user and message as context. Configure actions to send email and show on-screen message. Reference this component from multiple reaction rules to maintain consistent notification behavior.
Ban IP addresses after failed login attempts
Create a reaction rule triggered by 'System log entry is created'. Add condition checking the log message for failed login patterns. Use 'Ban IP address' action (requires Ban module) to block repeat offenders.
Tips
- Start with debug logging enabled when developing new rules to understand execution flow
- Use the Drush commands to quickly list available events, conditions, and actions
- Create reusable components for common action sequences to maintain consistency
- Use bundle-specific events (e.g., 'After saving a node of type Article') for better performance than filtering with conditions
- The data selector autocomplete is invaluable - press Tab to explore available paths
- Consider the order of conditions: put quick-to-evaluate conditions first to short-circuit expensive checks
- Use 'Force saving immediately' sparingly - batched saves at rule end are more efficient
- Export rules via Configuration Management to version control your business logic
- Test rules thoroughly in a development environment before deploying to production
Technical Details
Admin Pages 5
/admin/config/workflow/rules
Lists all configured reaction rules with their associated events, status (enabled/disabled), and provides operations to add, edit, delete, enable, or disable rules. Includes quick links to import and export rules via configuration management.
/admin/config/workflow/rules/components
Lists all reusable rule components. Components are rule sets that can be invoked from other rules or called programmatically. They can define input context requirements and provide output context.
/admin/config/workflow/rules/settings
Configure global settings for the Rules module including system logging verbosity and debug logging options for development.
/admin/config/workflow/rules/reactions/add
Form to create a new reaction rule. Requires selecting at least one triggering event.
/admin/config/workflow/rules/reactions/edit/{rules_reaction_rule}
Comprehensive rule editing interface with event management, condition building with AND/OR logic, and action configuration. Supports nested conditions and multiple actions with drag-and-drop ordering.
Permissions 5
Hooks 3
hook_rules_action_info_alter
Alter the definition of Rules action plugins.
hook_rules_condition_info_alter
Alter the definition of Rules condition plugins.
hook_rules_event_info_alter
Alter the definition of Rules event plugins.
Drush Commands 10
drush rules:list
Lists all active and inactive rules for your site. Can filter by type.
drush rules:enable
Enables a disabled Reaction Rule.
drush rules:disable
Disables an enabled Reaction Rule.
drush rules:delete
Permanently deletes a rule or component.
drush rules:export
Exports a single rule configuration in YAML format.
drush rules:revert
Reverts a rule to its original module-provided state.
drush rules:events
Shows a list of all available Rules events grouped by category.
drush rules:conditions
Shows a list of all available Rules conditions grouped by category.
drush rules:actions
Shows a list of all available Rules actions grouped by category.
drush rules:expressions
Shows a list of all available Rules expression types.
Troubleshooting 6
Enable debug logging at /admin/config/workflow/rules/settings and check the debug output. Verify the rule is enabled, the event is correctly configured, and all conditions are being met. Check the system log for any error messages.
Verify your site's mail system is properly configured. Check the system log for mail errors. Ensure the 'To' field contains valid email addresses. Test with the core Contact module to verify mail is working.
Use the autocomplete feature in the data selector field to explore available data paths. Ensure the context provides the expected entity type. Check that fields exist on the entity bundle you're working with.
Enable debug logging to see condition evaluation results. Verify the data selector returns expected values. Check for type mismatches (string vs integer comparisons). Test with negated conditions to verify evaluation.
Use bundle-specific events instead of generic entity events. Combine similar rules where possible. Avoid expensive operations in frequently-triggered events. Consider using cron-triggered rules for non-time-critical tasks.
Use Configuration Management or the Drush export command. Ensure all dependent configurations (referenced entities, etc.) are also exported. Check file permissions in the config sync directory.
Security Notes 6
- The 'Bypass Rules access control' permission is restricted and should only be granted to highly trusted administrators
- Email actions can be used for spam if rules are not properly secured - limit rule administration permissions
- Page redirect actions could be used for phishing - review redirect rules carefully
- Data set actions can modify any entity data - audit rules that use this action
- Rules executing on user-triggered events can be exploited for denial of service if not rate-limited
- Always validate that PHP filter module is disabled if it exists - never use PHP code in Rules