Skip to content

Usage

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

Attention

Should there ever be a problem, that ECA breaks your site, please refer to the troubleshooting 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.

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 modeler 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 worrisome 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 negligible, and we haven't been able to even measure any impact.

ECA model config files

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.

Each ECA model is a single config entity, exported by Drupal's configuration management into one file:

  • eca.eca.[MODEL-ID]: contains all events, conditions, gateways and actions that ECA operates upon

That config entity is canonical. It holds everything ECA needs to operate on the Drupal site, and a modeler reads and writes the same file when you edit the model. Sending this one file to someone else gives them the complete model.

A modeler may also keep the raw data of its own diagram, such as node coordinates and similar presentation details. That data is optional and is never required for processing. The Modeler API decides where it goes, per model, through the storage key in third_party_settings.modeler_api:

none
Do not store raw model data at all. Every model in the ECA Library uses this setting.
third-party
Store the raw data inside the model's own third_party_settings, so there is still only one config entity.
separate
Store the raw data in a companion modeler_api.data_model.[STORAGE-ID] config entity, where [STORAGE-ID] is eca_[MODELER-ID]_[MODEL-ID].

Note

Only the separate strategy produces a second config entity. Where it applies, keep the two files together and deploy them together. Losing the companion entity costs you the stored diagram layout, not the model itself: a modeler lays the diagram out automatically when raw data is absent.

You can write and edit an eca.eca config entity by hand. For the file format and the rules that are easy to get wrong, see Authoring models as configuration. More about moving models between sites below in Import and export models.

Admin UI

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.

When the ECA UI is being required, you can enable it separately:

1
drush en eca_ui

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.

Creating and editing models

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 modeler is enabled which provides support for integrated editing, like e.g. the Workflow Modeler.

Settings

Log level

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 and Debugging.

Documentation domain

Default: https://ecaguide.org

This domain is being used to provide links to the documentation when working with a modeler, 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. 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 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:

Creating and editing models

These actions are only available, if you have a modeler enabled that supports integrated editing, like e.g. the Workflow Modeler.

Import and export models

Models can be imported by clicking on the Import button in the top right corner. This opens a form where you first pick a type and then the file itself. ECA supports three types:

  • Model: an eca.eca.[MODEL-ID].yml config file, see ECA model config files
  • Raw: the native file of a modeler, for example the JSON of the Workflow Modeler. Pick the matching modeler on the form
  • Archive: an archive file (e.g. [MODELLER-TYPE]-[MODEL-ID].tar.gz) which has been previously exported (see below) or downloaded from the 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.

For a comprehensive guide on all import methods, common issues and troubleshooting, see Importing Models.

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 modeler and the ID of the model itself.

Note

It's important to keep that filename as it is part of the validation when later importing that model again.

The exported archive contains 2 or more files:

  • 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 model config entity
  • modeler_api.data_model.[STORAGE-ID].yml: the raw modeler data, only present when the model uses the separate storage strategy
  • optionally more config entities, if the exported ECA model depends on other config entities

Clone

This will clone an existing ECA model and create a random ID for the new model.

Enable / disable

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.

Delete

This will delete an ECA model entirely from the Drupal site.