From bec55db09c7ecca3ecd112f0625117849b043176 Mon Sep 17 00:00:00 2001 From: Michael Lenahan <michael.lenahan@gmail.com> Date: Thu, 6 Feb 2025 22:01:33 +0100 Subject: [PATCH 1/9] Rewrite home and concepts --- docs/eca/concepts/index.md | 67 +++++++++++++++++++++++++++++++++-- docs/index.md | 72 ++++++++++++++++++-------------------- 2 files changed, 98 insertions(+), 41 deletions(-) diff --git a/docs/eca/concepts/index.md b/docs/eca/concepts/index.md index 81f11d37..19a40e09 100644 --- a/docs/eca/concepts/index.md +++ b/docs/eca/concepts/index.md @@ -1,6 +1,67 @@ --- -title: Concepts +title: ECA concepts --- -# Concepts -In this section you'll find basic ECA concepts that are important to understand when building models. +# Understanding ECA concepts + +ECA (Events - Conditions - Actions) models help you automate business processes in Drupal by responding to events that happen on your site. Think of ECA as a watchful assistant that can detect when something happens, check if certain conditions apply, and then take appropriate actions. + +## Core components + +### Events + +Events are triggers that start an ECA process. These could be things like: + +- A user logging in +- Content being created or updated +- A form being submitted +- A scheduled time arriving +- A custom event you define + +When an event occurs, ECA checks if any models are listening for that event and runs them if so. + +### Conditions + +Conditions are checks that determine whether actions should run. They act as filters or guards, ensuring actions only happen when appropriate. For example, you might want to: + +- Check if a user has a specific role +- Verify content has certain field values +- Ensure a threshold has been met +- Compare dates or times +- Combine multiple conditions with AND/OR logic + +### Actions + +Actions are the tasks ECA performs when an event occurs and conditions are met. Actions can: + +- Create or update content +- Send notifications +- Modify user accounts +- Interact with external systems +- Trigger other events +- Perform custom operations + +## How components work together + +Let's look at a common example: sending a welcome email to new users in a specific role. + +1. **Event**: User account is created +2. **Condition**: User has the "member" role +3. **Action**: Send customized welcome email + +ECA processes this flow by: + +1. Detecting the account creation event +2. Checking the user's roles +3. Sending the email if the condition is met + +## Next steps + +Learn more about specific concepts: + +- [Working with custom events](custom_events.md) +- [Understanding tokens](tokens.md) +- [Using loops](loops.md) +- [Managing permissions](permissions.md) + +For practical examples, visit our [model library](../../library/index.md). diff --git a/docs/index.md b/docs/index.md index d6df4836..7c3871ee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,59 +3,55 @@ title: Drupal ECA Documentation --- # Welcome to Drupal ECA -ECA stands for **Events - Conditions - Actions**. +This document explains how to use the Events - Conditions - Actions (ECA) module for Drupal. -It's a [Drupal](https://www.drupal.org) module and has its own [project page](https://www.drupal.org/project/eca). This -**ECA Guide** is provided by the ECA maintainers, you can contact them on their user profile on drupal.org or in the -[ECA Slack Channel](https://drupal.slack.com/archives/C0287U62CSG). +## What is ECA? -## The 5 sections of this guide +ECA (Events - Conditions - Actions) is a Drupal module that processes business process models based on Drupal events. The module integrates with Drupal core components and provides plugin management for: -### ECA +* [Events](eca/concepts/index.md#events) +* [Conditions](eca/concepts/index.md#conditions) +* [Actions](eca/concepts/index.md#actions) -[All about the ECA](/index.md) module, [how to install](eca/install.md) it, [important concepts](eca/concepts/index.md) to understand -how ECA works and instructions on [how to extend ECA](eca/extend/index.md). +Note: ECA does not include a built-in user interface. Instead, it provides a modeller plugin manager that integrates with existing tools. If a modeller supports templates, ECA provides them for all plugins available on your Drupal site. -Important building blocks of ECA are the plugins for events, conditions and actions. Those are contained in their own -section for [plugins](#plugins) +## Contents -The ECA module is the heart of the module suite. Whenever a Drupal event -occurs, it processes any (business process) model defined for that event. +* [Installation guide](eca/install.md) +* [Key concepts](eca/concepts/index.md) +* [Extension guide](eca/extend/index.md) +* [Plugin documentation](plugins/index.md) +* [Available modellers](modeller/index.md) +* [Example models](library/index.md) +* [Additional resources](#additional-resources) -ECA leverages existing components of Drupal core, i.e. events and actions, -and provides its own plugin manager for conditions. Hence all 3 components -(events, conditions, actions) are implemented as plugins and may be easily -extended by other modules. +## Additional resources -!!! attention +You can find articles, tutorials, videos and other learning materials in the Resources section. - The ECA module does not provide any user interface to define models. Instead, - it provides a modeller plugin manager to easily integrate existing tools. - If a modeller supports templates for events, conditions and actions, - ECA will provide them for all the plugins that are available on a Drupal site. +## Get support -### Modellers +Contact the ECA maintainers through: -[Modellers](modeller/index.md) are the UI for ECA. They are described in this chapter. +* Their Drupal.org user profiles +* The [ECA Slack channel](https://drupal.slack.com/archives/C0287U62CSG) -### Plugins +## Contribute -Each event, each condition and each action is available as a [plugin](plugins/index.md). This chapter contains documentation -for each of them and how they can be configured. +We welcome contributions including: -### Library +* Bug reports and feature requests +* Documentation improvements +* Example models +* Custom plugins +* General feedback -This is where you can find [example ECA models](library/index.md). +To contribute: -### Resources +1. Create an account on [ECA Guide GitLab](https://gitlab.lakedrops.com) +2. Visit the [ECA Guide Project](https://gitlab.lakedrops.com/drupal/documentation/eca) +3. Open an issue or create a merge request -Articles, blog posts, tutorials, videos and so much more - all learning resources in one place. +This documentation uses British English. -## How to contribute - -Found a typo? Want to write some chapters for this guide? Have an example model you want to publish? Wrote your own ECA -plugins? Or you just want to provide feedback? This is all very welcome. To do so, please create an account in the -[ECA Guide GitLab](https://gitlab.lakedrops.com) and then go to the [ECA Guide Project](https://gitlab.lakedrops.com/drupal/documentation/eca) -where you can either open an issue or fork the project and then create a merge request. - -We use British English in this guide. +For more information about ECA, visit the [project page](https://www.drupal.org/project/eca). -- GitLab From baa6ab0927a3e159eb18dd9ead9162a77d5d7e7e Mon Sep 17 00:00:00 2001 From: Michael Lenahan <michael.lenahan@gmail.com> Date: Wed, 12 Feb 2025 10:22:24 +0100 Subject: [PATCH 2/9] Revert "Rewrite home and concepts" This reverts commit bec55db09c7ecca3ecd112f0625117849b043176. --- docs/eca/concepts/index.md | 67 ++--------------------------------- docs/index.md | 72 ++++++++++++++++++++------------------ 2 files changed, 41 insertions(+), 98 deletions(-) diff --git a/docs/eca/concepts/index.md b/docs/eca/concepts/index.md index 19a40e09..81f11d37 100644 --- a/docs/eca/concepts/index.md +++ b/docs/eca/concepts/index.md @@ -1,67 +1,6 @@ --- -title: ECA concepts +title: Concepts --- +# Concepts -# Understanding ECA concepts - -ECA (Events - Conditions - Actions) models help you automate business processes in Drupal by responding to events that happen on your site. Think of ECA as a watchful assistant that can detect when something happens, check if certain conditions apply, and then take appropriate actions. - -## Core components - -### Events - -Events are triggers that start an ECA process. These could be things like: - -- A user logging in -- Content being created or updated -- A form being submitted -- A scheduled time arriving -- A custom event you define - -When an event occurs, ECA checks if any models are listening for that event and runs them if so. - -### Conditions - -Conditions are checks that determine whether actions should run. They act as filters or guards, ensuring actions only happen when appropriate. For example, you might want to: - -- Check if a user has a specific role -- Verify content has certain field values -- Ensure a threshold has been met -- Compare dates or times -- Combine multiple conditions with AND/OR logic - -### Actions - -Actions are the tasks ECA performs when an event occurs and conditions are met. Actions can: - -- Create or update content -- Send notifications -- Modify user accounts -- Interact with external systems -- Trigger other events -- Perform custom operations - -## How components work together - -Let's look at a common example: sending a welcome email to new users in a specific role. - -1. **Event**: User account is created -2. **Condition**: User has the "member" role -3. **Action**: Send customized welcome email - -ECA processes this flow by: - -1. Detecting the account creation event -2. Checking the user's roles -3. Sending the email if the condition is met - -## Next steps - -Learn more about specific concepts: - -- [Working with custom events](custom_events.md) -- [Understanding tokens](tokens.md) -- [Using loops](loops.md) -- [Managing permissions](permissions.md) - -For practical examples, visit our [model library](../../library/index.md). +In this section you'll find basic ECA concepts that are important to understand when building models. diff --git a/docs/index.md b/docs/index.md index 7c3871ee..d6df4836 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,55 +3,59 @@ title: Drupal ECA Documentation --- # Welcome to Drupal ECA -This document explains how to use the Events - Conditions - Actions (ECA) module for Drupal. +ECA stands for **Events - Conditions - Actions**. -## What is ECA? +It's a [Drupal](https://www.drupal.org) module and has its own [project page](https://www.drupal.org/project/eca). This +**ECA Guide** is provided by the ECA maintainers, you can contact them on their user profile on drupal.org or in the +[ECA Slack Channel](https://drupal.slack.com/archives/C0287U62CSG). -ECA (Events - Conditions - Actions) is a Drupal module that processes business process models based on Drupal events. The module integrates with Drupal core components and provides plugin management for: +## The 5 sections of this guide -* [Events](eca/concepts/index.md#events) -* [Conditions](eca/concepts/index.md#conditions) -* [Actions](eca/concepts/index.md#actions) +### ECA -Note: ECA does not include a built-in user interface. Instead, it provides a modeller plugin manager that integrates with existing tools. If a modeller supports templates, ECA provides them for all plugins available on your Drupal site. +[All about the ECA](/index.md) module, [how to install](eca/install.md) it, [important concepts](eca/concepts/index.md) to understand +how ECA works and instructions on [how to extend ECA](eca/extend/index.md). -## Contents +Important building blocks of ECA are the plugins for events, conditions and actions. Those are contained in their own +section for [plugins](#plugins) -* [Installation guide](eca/install.md) -* [Key concepts](eca/concepts/index.md) -* [Extension guide](eca/extend/index.md) -* [Plugin documentation](plugins/index.md) -* [Available modellers](modeller/index.md) -* [Example models](library/index.md) -* [Additional resources](#additional-resources) +The ECA module is the heart of the module suite. Whenever a Drupal event +occurs, it processes any (business process) model defined for that event. -## Additional resources +ECA leverages existing components of Drupal core, i.e. events and actions, +and provides its own plugin manager for conditions. Hence all 3 components +(events, conditions, actions) are implemented as plugins and may be easily +extended by other modules. -You can find articles, tutorials, videos and other learning materials in the Resources section. +!!! attention -## Get support + The ECA module does not provide any user interface to define models. Instead, + it provides a modeller plugin manager to easily integrate existing tools. + If a modeller supports templates for events, conditions and actions, + ECA will provide them for all the plugins that are available on a Drupal site. -Contact the ECA maintainers through: +### Modellers -* Their Drupal.org user profiles -* The [ECA Slack channel](https://drupal.slack.com/archives/C0287U62CSG) +[Modellers](modeller/index.md) are the UI for ECA. They are described in this chapter. -## Contribute +### Plugins -We welcome contributions including: +Each event, each condition and each action is available as a [plugin](plugins/index.md). This chapter contains documentation +for each of them and how they can be configured. -* Bug reports and feature requests -* Documentation improvements -* Example models -* Custom plugins -* General feedback +### Library -To contribute: +This is where you can find [example ECA models](library/index.md). -1. Create an account on [ECA Guide GitLab](https://gitlab.lakedrops.com) -2. Visit the [ECA Guide Project](https://gitlab.lakedrops.com/drupal/documentation/eca) -3. Open an issue or create a merge request +### Resources -This documentation uses British English. +Articles, blog posts, tutorials, videos and so much more - all learning resources in one place. -For more information about ECA, visit the [project page](https://www.drupal.org/project/eca). +## How to contribute + +Found a typo? Want to write some chapters for this guide? Have an example model you want to publish? Wrote your own ECA +plugins? Or you just want to provide feedback? This is all very welcome. To do so, please create an account in the +[ECA Guide GitLab](https://gitlab.lakedrops.com) and then go to the [ECA Guide Project](https://gitlab.lakedrops.com/drupal/documentation/eca) +where you can either open an issue or fork the project and then create a merge request. + +We use British English in this guide. -- GitLab From 1fdd4e10405eb47ed618066934c022aa1fade626 Mon Sep 17 00:00:00 2001 From: Michael Lenahan <michael.lenahan@gmail.com> Date: Fri, 14 Feb 2025 19:45:22 +0100 Subject: [PATCH 3/9] docs/eca/install.md --- docs/eca/install.md | 34 ++++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/docs/eca/install.md b/docs/eca/install.md index bac1cdbe..873403d0 100644 --- a/docs/eca/install.md +++ b/docs/eca/install.md @@ -1,22 +1,40 @@ --- -title: Installation +title: Installing the ECA module tags: - install --- -# Installation -ECA can use different modellers. The recommended BPMN.iO modeller is used in this Quick Start guide. +# Installing the ECA module -Download the ECA module and BPMN.iO modeller module: +This guide explains how to install the Events - Conditions - Actions (ECA) module and its required components on your Drupal site. The installation process includes both the core ECA module and a modeller, which provides the user interface for creating automation models. -``` +## Prerequisites + +Before installing ECA, ensure your system meets these requirements: +Your Drupal site must be up and running with administrative access. You need to have Composer installed to manage the module dependencies. + +## Installing with Composer + +Use Composer to download the `eca` Drupal module and the recommended `BPMN.iO` modeller. The `BPMN.iO` modeller provides a visual interface for creating your automation models. + +```shell composer require drupal/eca drupal/bpmn_io ``` -Install the ECA and BPMN.iO module and their dependencies via the GUI at `/admin/modules` or with Drush: +## Enabling the modules -``` +After downloading the modules, you need to enable them in Drupal. You can do this through Drupal's administrative interface or using `drush`. +Through Drupal's administrative interface, sign in as an administrator and go to the Extend page (/admin/modules). Find and enable the following modules: `Events - Conditions - Actions (ECA)`, `ECA Base`, and `BPMN.iO Modeller`. Select "Install" to complete the process. +Alternatively, if you prefer using `drush`, you can enable the modules with this command: + +```shell drush -y pm:install eca eca_base bpmn_io ``` -The list of modules you may want to install depends on your use-case. You can now start building your own models. +## Next steps + +After completing the installation, you can begin exploring ECA's capabilities. Start by learning about [basic ECA concepts](/eca/concepts), read the [usage guide](/eca/usage.md), or explore our [library of example models](/library) for common use cases. The [concepts documentation](/eca/concepts) will help you understand how ECA can automate tasks on your Drupal site. + +## Additional components + +You might want to install additional ECA components depending on your specific needs. These components enhance ECA's functionality by adding support for specific types of events, conditions, or actions. Review our [extension guide](/eca/extend) and [plugin documentation](/plugins) to learn about available components and how they can help you build more sophisticated automation models. -- GitLab From 51a52bb2568f4807ad4aa48cc7bfc614f1724601 Mon Sep 17 00:00:00 2001 From: Michael Lenahan <michael.lenahan@gmail.com> Date: Fri, 14 Feb 2025 22:24:55 +0100 Subject: [PATCH 4/9] Split on 80 characters --- docs/eca/install.md | 45 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 34 insertions(+), 11 deletions(-) diff --git a/docs/eca/install.md b/docs/eca/install.md index 873403d0..a78ba4de 100644 --- a/docs/eca/install.md +++ b/docs/eca/install.md @@ -6,16 +6,22 @@ tags: # Installing the ECA module -This guide explains how to install the Events - Conditions - Actions (ECA) module and its required components on your Drupal site. The installation process includes both the core ECA module and a modeller, which provides the user interface for creating automation models. +This document explains how to install the Events - Conditions - Actions (ECA) +module and its required components on your Drupal site. +The installation process includes both the core ECA module and a modeler, which +provides the user interface for creating automation models. ## Prerequisites -Before installing ECA, ensure your system meets these requirements: -Your Drupal site must be up and running with administrative access. You need to have Composer installed to manage the module dependencies. +Before installing ECA, your Drupal site should be up and running with +administrative access. +You need to have Composer installed to manage the module dependencies. ## Installing with Composer -Use Composer to download the `eca` Drupal module and the recommended `BPMN.iO` modeller. The `BPMN.iO` modeller provides a visual interface for creating your automation models. +Use Composer to download the `eca` Drupal module and the recommended `BPMN.iO` +modeler. +The `BPMN.iO` modeler provides a visual interface for creating your automation models. ```shell composer require drupal/eca drupal/bpmn_io @@ -23,18 +29,35 @@ composer require drupal/eca drupal/bpmn_io ## Enabling the modules -After downloading the modules, you need to enable them in Drupal. You can do this through Drupal's administrative interface or using `drush`. -Through Drupal's administrative interface, sign in as an administrator and go to the Extend page (/admin/modules). Find and enable the following modules: `Events - Conditions - Actions (ECA)`, `ECA Base`, and `BPMN.iO Modeller`. Select "Install" to complete the process. -Alternatively, if you prefer using `drush`, you can enable the modules with this command: +After downloading the modules, you need to enable them in Drupal. +You can do this through Drupal's administrative interface or using `drush`. + +In Drupal, sign in as an administrator and go to the `Extend` page +(`/admin/modules`). +Find and enable the following modules: `ECA Core`, `ECA Base` and +`BPMN.iO Modeller`. +Select "Install" to complete the process. + +Alternatively, if you prefer using `drush`, you can enable the modules with this +command: ```shell drush -y pm:install eca eca_base bpmn_io ``` -## Next steps +## Additional ECA sub-modules -After completing the installation, you can begin exploring ECA's capabilities. Start by learning about [basic ECA concepts](/eca/concepts), read the [usage guide](/eca/usage.md), or explore our [library of example models](/library) for common use cases. The [concepts documentation](/eca/concepts) will help you understand how ECA can automate tasks on your Drupal site. +You might want to install additional ECA sub-modules. +These sub-modules add support for extra events, conditions, and actions. -## Additional components +ECA is also supported by a large number of Drupal contrib modules. +Review the [extension guide](/eca/extend) and [plugin documentation](/plugins) +to learn about available modules and how they can help you build more sophisticated +automation models. + +## Next steps -You might want to install additional ECA components depending on your specific needs. These components enhance ECA's functionality by adding support for specific types of events, conditions, or actions. Review our [extension guide](/eca/extend) and [plugin documentation](/plugins) to learn about available components and how they can help you build more sophisticated automation models. +After completing the installation, you can begin exploring ECA's capabilities. +Start by learning about [basic ECA concepts](/eca/concepts), read the +[usage guide](/eca/usage), or explore the +[library of example models](/library) for common use cases. -- GitLab From 3a3775ad723e0bbc3d2772890f4200f51b0aa96b Mon Sep 17 00:00:00 2001 From: Michael Lenahan <michael.lenahan@gmail.com> Date: Fri, 14 Feb 2025 22:35:02 +0100 Subject: [PATCH 5/9] Improve wording --- docs/eca/install.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/eca/install.md b/docs/eca/install.md index a78ba4de..43c4b851 100644 --- a/docs/eca/install.md +++ b/docs/eca/install.md @@ -7,7 +7,7 @@ tags: # Installing the ECA module This document explains how to install the Events - Conditions - Actions (ECA) -module and its required components on your Drupal site. +module on your Drupal site. The installation process includes both the core ECA module and a modeler, which provides the user interface for creating automation models. @@ -50,7 +50,7 @@ drush -y pm:install eca eca_base bpmn_io You might want to install additional ECA sub-modules. These sub-modules add support for extra events, conditions, and actions. -ECA is also supported by a large number of Drupal contrib modules. +ECA is also supported by a large number of Drupal contributed modules. Review the [extension guide](/eca/extend) and [plugin documentation](/plugins) to learn about available modules and how they can help you build more sophisticated automation models. -- GitLab From f4b48f90ab226a55060d4a500c953553020d1f38 Mon Sep 17 00:00:00 2001 From: Michael Lenahan <michael.lenahan@gmail.com> Date: Thu, 6 Mar 2025 13:12:07 +0100 Subject: [PATCH 6/9] Allow up to 120 characters per line --- docs/eca/install.md | 32 ++++++++++++-------------------- 1 file changed, 12 insertions(+), 20 deletions(-) diff --git a/docs/eca/install.md b/docs/eca/install.md index 43c4b851..c44f83eb 100644 --- a/docs/eca/install.md +++ b/docs/eca/install.md @@ -6,21 +6,18 @@ tags: # Installing the ECA module -This document explains how to install the Events - Conditions - Actions (ECA) -module on your Drupal site. -The installation process includes both the core ECA module and a modeler, which -provides the user interface for creating automation models. +This document explains how to install the Events - Conditions - Actions (ECA) module on your Drupal site. +The installation process includes both the core ECA module and a modeler, which provides the user interface for creating +automation models. ## Prerequisites -Before installing ECA, your Drupal site should be up and running with -administrative access. +Before installing ECA, your Drupal site should be up and running with administrative access. You need to have Composer installed to manage the module dependencies. ## Installing with Composer -Use Composer to download the `eca` Drupal module and the recommended `BPMN.iO` -modeler. +Use Composer to download the `eca` Drupal module and the recommended `BPMN.iO` modeler. The `BPMN.iO` modeler provides a visual interface for creating your automation models. ```shell @@ -32,14 +29,11 @@ composer require drupal/eca drupal/bpmn_io After downloading the modules, you need to enable them in Drupal. You can do this through Drupal's administrative interface or using `drush`. -In Drupal, sign in as an administrator and go to the `Extend` page -(`/admin/modules`). -Find and enable the following modules: `ECA Core`, `ECA Base` and -`BPMN.iO Modeller`. +In Drupal, sign in as an administrator and go to the `Extend` page (`/admin/modules`). +Find and enable the following modules: `ECA Core`, `ECA Base` and `BPMN.iO Modeller`. Select "Install" to complete the process. -Alternatively, if you prefer using `drush`, you can enable the modules with this -command: +Alternatively, if you prefer using `drush`, you can enable the modules with this command: ```shell drush -y pm:install eca eca_base bpmn_io @@ -51,13 +45,11 @@ You might want to install additional ECA sub-modules. These sub-modules add support for extra events, conditions, and actions. ECA is also supported by a large number of Drupal contributed modules. -Review the [extension guide](/eca/extend) and [plugin documentation](/plugins) -to learn about available modules and how they can help you build more sophisticated -automation models. +Review the [extension guide](/eca/extend) and [plugin documentation](/plugins) to learn about available modules +and how they can help you build more sophisticated automation models. ## Next steps After completing the installation, you can begin exploring ECA's capabilities. -Start by learning about [basic ECA concepts](/eca/concepts), read the -[usage guide](/eca/usage), or explore the -[library of example models](/library) for common use cases. +Start by learning about [basic ECA concepts](/eca/concepts), read the [usage guide](/eca/usage), +or explore the [library of example models](/library) for common use cases. -- GitLab From 008e44e9d1a809cde4674f228159a520094e7df5 Mon Sep 17 00:00:00 2001 From: Michael Lenahan <michael.lenahan@gmail.com> Date: Tue, 11 Mar 2025 11:20:26 +0100 Subject: [PATCH 7/9] Update usage.md --- docs/eca/usage.md | 201 +++++++++++++++++++--------------------------- 1 file changed, 82 insertions(+), 119 deletions(-) diff --git a/docs/eca/usage.md b/docs/eca/usage.md index da9771a2..990e34c8 100644 --- a/docs/eca/usage.md +++ b/docs/eca/usage.md @@ -1,168 +1,131 @@ --- title: Usage --- -# Usage +# Using the ECA module -Actually, ECA is processing all enabled models in the background and there is nothing a user needs to do, when -everything has been set up. In fact, there isn't anything a user could do to prevent ECA from processing all these -models +Once installed and configured, the Events - Conditions - Actions (ECA) module operates automatically in the background. +This page explains how ECA processes models and how to manage them on your site. -!!! attention - - Should there ever be a problem, that ECA breaks your site, please refer to the - [troubleshooting](/eca/troubleshooting.md) section which explains how to fix that. - -## How it works +## How ECA works -ECA is a processor that works in the background by subscribing to all events on a Drupal site and executing ECA models -that define processes for any of those events. There is no UI required for that, ECA just operates based on the -available and enabled models. +ECA monitors Drupal events and executes defined models when those events occur. When the models are in place, +and enabled, they will run without any user interaction. +In fact, there is nothing that a user can do to prevent ECA from processing the enabled modules. -!!! tip "Recommended setup for production sites" - - Creating and maintaining ECA models might be a task for your development environment. On the production site, there - is often no access to either view or edit those models. If that applies to your Drupal site, you only need to enable - ECA and all the sub-modules that are required by the configured ECA models. There won't be any UI and no modeller - available for any user on the live site, ECA just operates on the configured models. +!!! attention -Subscribing to all events on a Drupal site may sound worrysome in regard to site performance. We've taken much care -to avoid unnecessary overhead and ECA is able to decide very quickly, whether an event is relevant for any of the -configured models or not. All information, that's required to make those decisions are stored in cache separately and -will only be loaded once for each request, so that the extra processing for each event on top of Symfony's event -dispatching is in fact negligable, and we haven't been able to even measure any impact. + It may occur that your site stops functioning because of an ECA model. + If you experience this, or any issue affecting your site functionality, + refer to the [troubleshooting guide](/eca/troubleshooting.md) for solutions. -### ECA model config files +## Background processing -The ECA models have been mentioned a lot, and this chapter explains how those models are stored and describe the -structure of their config files. This should help you plan the maintenance and deployment of your own models on all -your different Drupal sites. +ECA continuously processes all enabled models. The module: -Each ECA model is a set of 2 config entities, each of which being exported by Drupal's configuration management into -a separate file. The config entities (and files) for a single model are named with the following pattern: +- Listens for events occurring on your Drupal site +- Matches events to conditions defined in your models +- Executes the appropriate actions when conditions are met -- `eca.eca.[MODEL-ID]`: contains all events, conditions and actions that ECA operates upon -- `eca.model.[MODEL-ID]`: contains the proprietary model data of the modeller that has been used to create and edit this - model +## Disabling the ECA admin UI on production environments -In other words, the config entity `eca.eca.[MODEL-ID]` is being used by ECA to operate on the Drupal site. The other one -is not needed for that at any time. That second config entity is only reequired by the modeller, when the model gets -edited. When editing a model with a modeller, ECA will recreate its `eca.eca.[MODEL.ID]` config entity by converting -the modeller data when the model gets saved by the modeller. +ECA does not require the UI (`eca_ui`) in order to function. +We recommend that you disable the UI and the modeler in production environments. -!!! danger +For production sites, consider this recommended approach: - Always keep the 2 config entities together - ECA always keeps them in sync. And never edit them manually, the - eca.eca entity will always be recreated from the eca.model entity. +- Create and test ECA models in your development environment +- Export the models to your production site +- Enable only ECA and required submodules on production +- Uninstall the `eca_ui` module on production. This will also uninstall modeler interfaces (for example, `bpmn_io`) -Having said that, the `eca.model` config entity contains everything needed to recreate the `eca.eca` config entity, -should you ever loose that. That implies that you could send the `eca.model` config entity to someone else only, and -they could load that into their Drupal site which would then recreate the companion `eca.eca` config entity, if they -had the same modeller available to interpret the proprietary data. More about that below in -[Import and export models](#import-and-export-models). +This setup allows ECA to operate based on your configured models without exposing the model creation interface to users +on the production site. -## Admin UI +This is similar to the approach that Drupal takes for Views and Fields - +the user interfaces for those modules can also be disabled when not required. -As mentioned above, to let ECA do its work by processing available ECA models, no UI is required whatsoever. Only if -you need to maintain your ECA models, the ECA UI is required. Very much like Drupal core has implemented this for the -fields and views modules, where the UIs can also be disabled when not required. +## ECA admin UI is separate from the modeler -When the ECA UI is being required, you can enable it separately: +The ECA admin UI does not, by itself, provide you access to the create or edit models. +To make the `BPMN.iO` modeler interface available, enable the `bpmn_io` module: ``` -drush en eca_ui +drush pm:enable bpmn_io ``` -This enables the admin UI which can be found in the admin menu under Administration / Configuration / Workflow / ECA -with the path `/admin/config/workflow/eca`: - - - -On this ECA admin page you can manage all aspects of ECA: Changing the order of the models by re-arranging them, -importing new models and performing operations on each of the available models. That's all described in the chapters -below. +## Site performance -??? note "Creating and editing models" +ECA efficiently subscribes to Drupal events with minimal performance impact. +The module uses cached information to quickly determine whether an event is relevant to any configured models, +avoiding unnecessary processing overhead. +In fact, in our own tests, we have not been able to measure any performance impact, over and above that of the Symfony +event dispatching in Drupal. - The ECA admin UI does not provide you access to create new models or to edit existing ones. Those actions are only - available, when at least one modeller is enabled which provides support for integrated editing, like e.g. the - [bpmn.io modeller](/modeller/bpmn/bpmn_io/index.md). +## ECA model configuration -### Settings +Each ECA model consists of two configuration entities: -`Log level` +- `eca.eca.[MODEL-ID]` - Contains the events, conditions, and actions +- `eca.model.[MODEL-ID]` - Contains the modeler-specific data -: _Default: Error_ +The first entity (`eca.eca.[MODEL-ID]`) is what ECA uses to operate on your site. +The second entity is only required when editing the model. +When you save a model using a modeler, ECA recreates the first entity by converting the modeler data. - Determines, which ECA log messages will be logged to which ever logging backend is enabled on your site. By default, - ECA only logs errors or more severe log messages. You can change that to e.g. `Debug` to also get much more detailed - logs, see also [Logs](#logs) and [Debugging](/eca/debugging.md). +Always keep both configuration entities together, as ECA keeps them synchronized. +Never edit the `.yml` files manually, as the `eca.eca` entity will always be regenerated from the `eca.model` entity. -`Documentation domain` +## Administrative interface -: _Default: https://ecaguide.org_ +The ECA administrative interface is optional and can be enabled separately: - This domain is being used to provide links to the documentation when working with a modeller, and it points to this - official ECA guide by default. You can change this to any other domain, if you provide your own documentation, or - make this field empty, so that ECA won't display any links to documentation. - -### Logs - -This is only available, if you've also enabled the `Database Logging` module. It will display all the logged ECA -messages depending on the log level you've configured in the [settings](#settings). You can filter the messages by -content and/or time range and the list is sorted in exactly that order how the messages got produced. - -Each log message for a condition or an action will also contain a list of tokens, that have been available at the time -when that component has been evaluated or executed. For more details about token, see -[Concepts: Token](/eca/concepts/tokens.md). - -### ECA model operations - -In the list of models, the operations column contains a list of operations for each model, that's available on that -Drupal site: +``` +drush en eca_ui +``` -#### Creating and editing models +After enabling the UI, access it at Administration > Configuration > Workflow > ECA, +or at the path `/admin/config/workflow/eca`. -These actions are only available, if you have a modeller enebaled that supports integrated editing, like e.g. the -[bpmn.io modeller](/modeller/bpmn/bpmn_io/index.md). + -#### Import and export models +### Models tab -Models can be imported by clicking on the `Import` button in the top right corner. This will open a form where you can -select a file to import. There are actually 2 different file types supported for import: +The `Models` tab allows you to: -- an `eca.model.[MODEL-ID].yml` config file, see [ECA model config files](#eca-model-config-files) -- an archive file (e.g. `[MODELLER-TYPE]-[MODEL-ID].tar.gz`) which has been previously exported (see below) or - downloaded from the [Library](/library/index.md) +- Reorder models to change their processing sequence +- Enable or disable models: disabled models are not processed by ECA +- Delete an ECA model entirely from the Drupal site +- Clone an ECA model with a new random model ID -Once you've selected the file and click on the `Import` button, ECA will validate the file and if all dependencies are -available, import the model and show it on the list of models for further operations. +If the `bpmn_io` module is enabled, you can edit the model in the modeler interface. -To export a model from your Drupal site, e.g. because you want to use it on a different Drupal site, or you need to -attach it to an issue on drupal.org, select the `Export` operation in the list of models for that model, that you want -to export. This will create an archive with a filename `[MODELLER-TYPE]-[MODEL-ID].tar.gz` which contains the id of -the used modeller and the ID of the model itself. +### Import tab -!!! note +The `Import` tab (`/admin/config/workflow/eca/import`) allow you to import a model from an archive `tar.gz` file. +The archive will have the name format `[MODELLER-TYPE]-[MODEL-ID].tar.gz`. - It's important to keep that filename as it is part of the validation when later importing that model again. +This could be an archive you have exported previously, +or one of the many examples which you can download from the [ECA Library](/library). -The exported archive contains 3 or more files: +### Settings tab -- `dependencies.yml`: a metadata file containing the names of ECA config entities and a list of required modules -- `eca.eca.[MODEL.ID].yml`: the ECA config entity for processing -- `eca.model.[MODEL.ID].yml`: the ECA config entity with proprietary model data -- optionally more config entities, if the exported ECA model depends on other config entities +The `Settings` tab (`/admin/config/workflow/eca/settings`) provides these configuration options: -#### Clone +#### Log level -This will clone an existing ECA model and create a random ID for the new model. +Controls which ECA messages are recorded in your site's logging system. +The default setting logs only errors, but you can increase verbosity for debugging purposes. +For detailed logging, see the [debugging guide](/eca/debugging.md). -#### Enable / disable +#### Documentation domain -Only one of those 2 operations is available, depending on the state of each model. Enabled model can be disabled and -vice versa. Disabled models will not be processed by ECA, but they remain available on the Drupal site for editing or -other operations. Only if you re-enable a disabled model will it be processed by ECA again. +Determines where documentation links point when using a modeler. +The default is <https://ecaguide.org>, but you can change this to your own documentation site, +or leave it empty to disable documentation links. -### Delete +### Logs tab -This will delete an ECA model entirly from the Drupal site. +When the `Database Logging` (`dblog`) module is enabled, you can view ECA log messages through the `Logs` tab: +`admin/config/workflow/eca/log`. +The log displays messages according to the log level you have configured in the `Settings` tab. +Log entries can be filtered by content or time range. -- GitLab From 41a3c7afb607692012fc78f161010b7f80de532d Mon Sep 17 00:00:00 2001 From: Michael Lenahan <michael.lenahan@gmail.com> Date: Tue, 11 Mar 2025 11:41:54 +0100 Subject: [PATCH 8/9] Apply gitlab linting suggestions --- docs/eca/usage.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/eca/usage.md b/docs/eca/usage.md index 990e34c8..99083ed7 100644 --- a/docs/eca/usage.md +++ b/docs/eca/usage.md @@ -9,7 +9,7 @@ This page explains how ECA processes models and how to manage them on your site. ## How ECA works ECA monitors Drupal events and executes defined models when those events occur. When the models are in place, -and enabled, they will run without any user interaction. +and enabled, they run without any user interaction. In fact, there is nothing that a user can do to prevent ECA from processing the enabled modules. !!! attention @@ -28,15 +28,15 @@ ECA continuously processes all enabled models. The module: ## Disabling the ECA admin UI on production environments -ECA does not require the UI (`eca_ui`) in order to function. -We recommend that you disable the UI and the modeler in production environments. +ECA doesn't require the UI (`eca_ui`) in order to function. +We recommend that you turn off the UI and the modeler in production environments. For production sites, consider this recommended approach: - Create and test ECA models in your development environment - Export the models to your production site - Enable only ECA and required submodules on production -- Uninstall the `eca_ui` module on production. This will also uninstall modeler interfaces (for example, `bpmn_io`) +- Uninstall the `eca_ui` module on production This setup allows ECA to operate based on your configured models without exposing the model creation interface to users on the production site. @@ -58,7 +58,7 @@ drush pm:enable bpmn_io ECA efficiently subscribes to Drupal events with minimal performance impact. The module uses cached information to quickly determine whether an event is relevant to any configured models, avoiding unnecessary processing overhead. -In fact, in our own tests, we have not been able to measure any performance impact, over and above that of the Symfony +In fact, in our own tests, we have not seen any measurable performance impact, over and above that of the Symfony event dispatching in Drupal. ## ECA model configuration @@ -73,7 +73,7 @@ The second entity is only required when editing the model. When you save a model using a modeler, ECA recreates the first entity by converting the modeler data. Always keep both configuration entities together, as ECA keeps them synchronized. -Never edit the `.yml` files manually, as the `eca.eca` entity will always be regenerated from the `eca.model` entity. +Never edit the `.yml` files manually, as the `eca.eca` entity is always regenerated from the `eca.model` entity. ## Administrative interface @@ -102,7 +102,7 @@ If the `bpmn_io` module is enabled, you can edit the model in the modeler interf ### Import tab The `Import` tab (`/admin/config/workflow/eca/import`) allow you to import a model from an archive `tar.gz` file. -The archive will have the name format `[MODELLER-TYPE]-[MODEL-ID].tar.gz`. +The archive has the name format `[MODELLER-TYPE]-[MODEL-ID].tar.gz`. This could be an archive you have exported previously, or one of the many examples which you can download from the [ECA Library](/library). -- GitLab From 15a1403341fdc1f68d819acbf06d03fa8b68e025 Mon Sep 17 00:00:00 2001 From: Michael Lenahan <michael.lenahan@gmail.com> Date: Tue, 11 Mar 2025 19:33:50 +0100 Subject: [PATCH 9/9] Review changes to usage.md --- docs/eca/usage.md | 45 +++++++++++++++++++++++++++++++-------------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/docs/eca/usage.md b/docs/eca/usage.md index 99083ed7..5b61bc9a 100644 --- a/docs/eca/usage.md +++ b/docs/eca/usage.md @@ -3,7 +3,8 @@ title: Usage --- # Using the ECA module -Once installed and configured, the Events - Conditions - Actions (ECA) module operates automatically in the background. +Once [installed](/eca/install/) and configured, the Events - Conditions - Actions (ECA) module operates automatically +in the background. This page explains how ECA processes models and how to manage them on your site. ## How ECA works @@ -26,28 +27,27 @@ ECA continuously processes all enabled models. The module: - Matches events to conditions defined in your models - Executes the appropriate actions when conditions are met -## Disabling the ECA admin UI on production environments +## Optionally disabling the ECA admin UI on production environments -ECA doesn't require the UI (`eca_ui`) in order to function. -We recommend that you turn off the UI and the modeler in production environments. - -For production sites, consider this recommended approach: +ECA doesn't require the `ECA UI module` (`eca_ui`) in order to function. +Some Drupal administrators may choose to turn off the UI and the modeler in production environments. +The steps are as follows: - Create and test ECA models in your development environment - Export the models to your production site - Enable only ECA and required submodules on production - Uninstall the `eca_ui` module on production -This setup allows ECA to operate based on your configured models without exposing the model creation interface to users -on the production site. - -This is similar to the approach that Drupal takes for Views and Fields - -the user interfaces for those modules can also be disabled when not required. +Drupal takes a similar approach for Views and Fields - +the user interfaces for those modules can also be (optionally) disabled. ## ECA admin UI is separate from the modeler -The ECA admin UI does not, by itself, provide you access to the create or edit models. -To make the `BPMN.iO` modeler interface available, enable the `bpmn_io` module: +The ECA admin UI does not, by itself, provide you access to create or edit models. +To make the `BPMN.iO` modeler interface available, go to Administration > Extend (`/admin/modules`) +and enable thie `BPMN.iO for ECA` module. + +If you are familiar with the command-line, you can use `drush`: ``` drush pm:enable bpmn_io @@ -55,7 +55,7 @@ drush pm:enable bpmn_io ## Site performance -ECA efficiently subscribes to Drupal events with minimal performance impact. +ECA dynamically subscribes to all Drupal events which have been defined in the active models on your site. The module uses cached information to quickly determine whether an event is relevant to any configured models, avoiding unnecessary processing overhead. In fact, in our own tests, we have not seen any measurable performance impact, over and above that of the Symfony @@ -75,6 +75,10 @@ When you save a model using a modeler, ECA recreates the first entity by convert Always keep both configuration entities together, as ECA keeps them synchronized. Never edit the `.yml` files manually, as the `eca.eca` entity is always regenerated from the `eca.model` entity. +!!! note + + Since the release of ECA version 2.1, you can (optionally) omit the `eca.model.[MODEL-ID]` configuration entity. + ## Administrative interface The ECA administrative interface is optional and can be enabled separately: @@ -96,6 +100,8 @@ The `Models` tab allows you to: - Enable or disable models: disabled models are not processed by ECA - Delete an ECA model entirely from the Drupal site - Clone an ECA model with a new random model ID +- Export an ECA model +- Export an ECA model as a Drupal Recipe If the `bpmn_io` module is enabled, you can edit the model in the modeler interface. @@ -123,6 +129,17 @@ Determines where documentation links point when using a modeler. The default is <https://ecaguide.org>, but you can change this to your own documentation site, or leave it empty to disable documentation links. +#### Execute models with user + +Allows you to specify the User ID (`uid`) of the user account that ECA uses to execute models. +It is recommended to leave this field empty unless you have a good reason to set another user account. +By default, the current user's account is used to execute models, that works for most use cases. + +#### Service account user + +The service account is a Drupal user account ECA will switch to when the action "Switch to service user" +is executed in a model. + ### Logs tab When the `Database Logging` (`dblog`) module is enabled, you can view ECA log messages through the `Logs` tab: -- GitLab