diff --git a/docs/eca/install.md b/docs/eca/install.md index bac1cdbe37016dd34aa9021856d308d65e1d9c61..c44f83eb04559e2352a8d17427a61ff275411a74 100644 --- a/docs/eca/install.md +++ b/docs/eca/install.md @@ -1,22 +1,55 @@ --- -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 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. +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. +The `BPMN.iO` modeler 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`. + +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 ``` -The list of modules you may want to install depends on your use-case. You can now start building your own models. +## Additional ECA sub-modules + +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. + +## 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. diff --git a/docs/eca/usage.md b/docs/eca/usage.md index da9771a28b684305c28287a567815141dc962c51..5b61bc9a560ce3bf4762872df4d7a39c365442d0 100644 --- a/docs/eca/usage.md +++ b/docs/eca/usage.md @@ -1,168 +1,148 @@ --- 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](/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. -!!! 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 - -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. +## How ECA works -!!! tip "Recommended setup for production sites" +ECA monitors Drupal events and executes defined models when those events occur. When the models are in place, +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. - 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. - -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. +!!! attention -### ECA model config files + 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. -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. +## Background processing -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: +ECA continuously processes all enabled models. The module: -- `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 +- Listens for events occurring on your Drupal site +- Matches events to conditions defined in your models +- Executes the appropriate actions when conditions are met -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. +## Optionally disabling the ECA admin UI on production environments -!!! danger +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: - 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 -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). +Drupal takes a similar approach for Views and Fields - +the user interfaces for those modules can also be (optionally) disabled. -## Admin UI +## ECA admin UI is separate from the modeler -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. +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. -When the ECA UI is being required, you can enable it separately: +If you are familiar with the command-line, you can use `drush`: ``` -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`: +## Site performance - +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 +event dispatching in Drupal. -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. +## ECA model configuration -??? note "Creating and editing models" +Each ECA model consists of two configuration entities: - 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.eca.[MODEL-ID]` - Contains the events, conditions, and actions +- `eca.model.[MODEL-ID]` - Contains the modeler-specific data -### Settings +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. -`Log level` +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. -: _Default: Error_ - - 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). +!!! note -`Documentation domain` + Since the release of ECA version 2.1, you can (optionally) omit the `eca.model.[MODEL-ID]` configuration entity. -: _Default: https://ecaguide.org_ +## Administrative interface - 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. +The ECA administrative interface is optional and can be enabled separately: -### Logs +``` +drush en eca_ui +``` -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. +After enabling the UI, access it at Administration > Configuration > Workflow > ECA, +or at the path `/admin/config/workflow/eca`. -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 +### Models tab -In the list of models, the operations column contains a list of operations for each model, that's available on that -Drupal site: +The `Models` tab allows you to: -#### Creating and editing models +- 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 +- Export an ECA model +- Export an ECA model as a Drupal Recipe -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). +If the `bpmn_io` module is enabled, you can edit the model in the modeler interface. -#### Import and export models +### Import 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 `Import` tab (`/admin/config/workflow/eca/import`) allow you to import a model from an archive `tar.gz` file. +The archive has the name format `[MODELLER-TYPE]-[MODEL-ID].tar.gz`. -- 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) +This could be an archive you have exported previously, +or one of the many examples which you can download from the [ECA Library](/library). -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. +### Settings tab -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. +The `Settings` tab (`/admin/config/workflow/eca/settings`) provides these configuration options: -!!! note +#### Log level - It's important to keep that filename as it is part of the validation when later importing that model again. +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). -The exported archive contains 3 or more files: +#### Documentation domain -- `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 +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. -#### Clone +#### Execute models with user -This will clone an existing ECA model and create a random ID for the new model. +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. -#### Enable / disable +#### Service account user -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. +The service account is a Drupal user account ECA will switch to when the action "Switch to service user" +is executed in a model. -### 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.