ECA: Event - Condition - Action
A powerful no-code rules engine for Drupal that allows building conditionally triggered action sets using events, conditions, and actions through a graphical BPMN modeller interface.
eca
Install
composer require 'drupal/eca:^3.0'
composer require 'drupal/eca:^2.1'
Overview
ECA (Event - Condition - Action) is a powerful, versatile, and user-friendly rules engine for Drupal. It empowers site administrators to orchestrate complex automated workflows without writing code. The core module is a processor that validates and executes event-condition-action plugins.
Integrated with the graphical user interface BPMN.iO, ECA provides a robust system for building conditionally triggered action sets. ECA gets triggered for every Drupal event, validates these events against configured models, and processes all matching models for the current event. Like Drupal Rules, ECA leverages existing components of Drupal core (events and actions) while providing its own plugin manager for conditions.
All three components (events, conditions, actions) are available as plugins that can easily be extended by other modules. ECA models are stored in configuration, enabling import and export via the admin UI, Drush, or configuration management.
Features
- Plugin managers for modellers, events, conditions, and actions with extensible architecture
- Integration with BPMN.iO graphical modeller for visual workflow design
- Full integration with all Drupal core actions and contrib module actions
- Extensive token support throughout all event, condition, and action configurations
- TypedData support for working with complex data structures
- Built-in recursion prevention to avoid infinite loops in workflow execution
- Caching support for improved performance on frequently triggered events
- State and key-value storage operations for persistent data across requests
- Queue operations for deferred and scheduled task execution
- Custom endpoint creation for dynamic route/URL handling
- Tagging system for event characterization and organization
- Models stored as configuration entities for easy export/import and version control
- Support for executing models as a specific user account
- Service account switching for privileged operations
- Cron event support with cron-style frequency notation
- Custom form rendering and manipulation through ECA actions
- Entity reference and options field selection customization
Use Cases
Automated Content Publishing Workflow
Create a workflow that automatically sends email notifications when content is submitted for review, assigns reviewers based on content type, and publishes content after approval. Use content entity events (presave, update) combined with user role conditions and email sending actions.
Dynamic Form Modifications
Modify forms based on user roles or field values. For example, hide certain form fields for anonymous users, add custom validation rules, or auto-populate fields based on other field values using Form API events and conditions.
Custom API Endpoints
Create custom REST-like endpoints without writing code using the Endpoint submodule. Define routes that return JSON data, process form submissions, or integrate with external services. Control access and build responses entirely through ECA models.
Scheduled Content Operations
Use cron events with frequency notation to perform scheduled tasks like sending digest emails, archiving old content, updating statistics, or synchronizing data with external systems.
Entity Access Control
Implement complex access control logic that goes beyond Drupal's standard permissions. Grant or revoke access to entities based on field values, user properties, time of day, or custom conditions.
User Registration Automation
Automate user registration workflows including welcome emails, role assignment based on registration data, profile completion reminders, and integration with external CRM systems.
Content Moderation Notifications
Send notifications to content authors and editors when content state changes, with customized messages based on the transition type and involved users.
Dynamic Menu Generation
Modify menu items based on user context, content availability, or external conditions using the Menu submodule.
Cache Management
Implement intelligent cache invalidation strategies that clear specific caches when related content changes, improving site performance while ensuring content freshness.
Queue-Based Processing
Offload heavy processing tasks to queues for background execution, preventing timeout issues and improving user experience for operations like batch imports or bulk updates.
Tips
- Start with the ECA Base and ECA Content submodules for most use cases, then add others as needed.
- Use the debug log level (7) during development to see detailed execution information.
- Test ECA models on a development environment before deploying to production.
- Export models as configuration and commit them to version control for proper deployment.
- Use meaningful labels for events, conditions, and actions in your models for better maintainability.
- Leverage the custom event system to modularize complex workflows across multiple ECA models.
- Use tokens consistently to pass data between actions in a workflow.
- Consider using queue operations for long-running tasks to prevent timeout issues.
- The ECA Guide at https://ecaguide.org provides comprehensive documentation, tutorials, and example models.
Technical Details
Admin Pages 1
/admin/config/workflow/eca/settings
Configure global settings for ECA including logging level, documentation domain, user execution settings, and dependency calculation options.
Permissions 1
Hooks 1
hook_eca_token_data_provider
Register a token data provider to supply custom token data to ECA.
Drush Commands 3
drush eca:subscriber:rebuild
Rebuilds the state of subscribed events. Use this when ECA models are not responding to events correctly.
drush eca:doc:plugins
Exports documentation for all ECA plugins (events, conditions, actions). Development module only.
drush eca:doc:models
Exports documentation for all ECA models including model files and recipes. Development module only.
Troubleshooting 6
Run 'drush eca:subscriber:rebuild' to rebuild the event subscription state. Also check that the ECA model is enabled and that events are correctly configured with matching entity types/bundles.
ECA includes built-in recursion prevention. If you see recursion errors, review your models for circular event triggering (e.g., a save event triggering another save). Use conditions to break the cycle or increase the recursion threshold parameter 'eca.max_recursion_level'.
Ensure tokens are properly formatted with square brackets. Check that the token exists in the current context. Enable debug logging (log level 7) to see available tokens at each execution step.
Check the ECA log for error messages. Verify that all required conditions are met. Ensure dependent tokens have values before they are used in action configurations.
Ensure the Endpoint submodule is enabled. The endpoint needs both an access event (to grant access) and a response event (to build content). Clear all caches after creating endpoint models.
Verify the cron frequency syntax follows cron notation. Check that Drupal cron is running. The first execution is scheduled after the model is saved, so new models won't run immediately.
Security Notes 6
- The 'administer eca' permission grants significant power - only assign to trusted administrators.
- Models executed as a specific user (via settings) bypass normal permission checks - use with caution.
- The service account feature should use a dedicated account with only necessary permissions.
- Custom endpoints need explicit access configuration - never assume they are protected by default.
- Token values in logs may contain sensitive data - restrict access to ECA logs appropriately.
- Review imported models carefully before enabling them on production sites.