Skip to content

Upgrading from ECA 2 to ECA 3

ECA 3 moved everything about modeling out of ECA and into the Modeler API. ECA keeps the executable model, and the Modeler API owns the diagram. Your models are migrated for you when you run the database updates.

Two parts of the upgrade are not automatic. ECA 2 shipped its own BPMN modeler as the sub-module eca_modeller_bpmn, whose code ECA 3.1 no longer contains, and the minimum Drupal core version rises with every ECA release. Both need a decision before you change any code.

Check the Drupal core version first

ECA cannot bridge the whole range in one step:

ECA release Drupal core PHP
2.1.x ^10.3 \|\| ^11 8.1 or later
3.0.x ^11.2 8.3 or later
3.1.x ^11.3 \|\| ^12.0 8.3 or later

A site on Drupal 10.3 cannot reach ECA 3.0 at all. Move that site to Drupal 11.2 first, and to Drupal 11.3 if you want ECA 3.1. Drupal core and ECA can go into the same composer require call, which is what the route instructions below assume.

Two upgrade routes

Both routes end on the current ECA 3 release and both migrate your models. They differ in how the old modeler sub-module gets removed:

Route What you do Choose it when
Route A Uninstall eca_modeller_bpmn while still on ECA 2, then update straight to ECA 3.1 or later You want one code update and one round of database updates. This is the recommended route.
Route B Update to ECA 3.0, run the database updates, then update to the current release You prefer smaller steps, or your site cannot reach Drupal 11.3 yet and has to stop on ECA 3.0 for a while.

Route A needs one manual step that Route B does not, described next.

Uninstall eca_modeller_bpmn while you are still on ECA 2

Route A does not work without this step

eca_modeller_bpmn was removed from the code base in ECA 3.1. Drupal cannot boot with a module that is recorded as installed but whose code is gone, so the module has to be uninstalled before the ECA 3.1 code reaches the site, while ECA 2 is still in place. No update hook can do it for you, because none of them get to run: the site is already unbootable by the time you would call drush updatedb.

In ECA 2 the bpmn_io module depends on eca_modeller_bpmn, so it has to be uninstalled in the same command. Your models are not affected by this, because they are stored as configuration owned by eca itself, not by the modeler:

1
drush pm:uninstall bpmn_io eca_modeller_bpmn

Route B does not need this step. ECA 3.0 still ships eca_modeller_bpmn as a deprecated placeholder, and its update hook installs the Modeler API and uninstalls the placeholder for you. That hook can run because the module's code is still on disk.

Route A: straight to ECA 3.1

  1. Uninstall the old modeler while the site still runs ECA 2:

    1
    drush pm:uninstall bpmn_io eca_modeller_bpmn

  2. Update the code, including Drupal core if the table above says so:

    1
    composer require drupal/eca:^3 drupal/bpmn_io:^3 drupal/modeler_api:^1

  3. Enable the modeler again. This also installs the Modeler API:

    1
    drush en bpmn_io

  4. Run the database updates:

    1
    drush cr && drush updatedb

Enable bpmn_io before you run the database updates

The migration reads the diagram of each model through the modeler that drew it, and it can only hand that diagram over to the Modeler API while the modeler is available. If you run drush updatedb with bpmn_io still uninstalled, the update reports which models it could not migrate, leaves their diagrams untouched, and stays pending. Enable bpmn_io and run drush updatedb again to finish the job.

Route B: through ECA 3.0

  1. Update to ECA 3.0. Leave bpmn_io enabled throughout, so the migration can read your diagrams:

    1
    composer require drupal/eca:~3.0.0 drupal/bpmn_io:^3 drupal/modeler_api:^1

  2. Run the database updates. This installs the Modeler API, uninstalls eca_modeller_bpmn, and migrates your models:

    1
    drush cr && drush updatedb

  3. Update to the current release:

    1
    composer require drupal/eca:^3

  4. Run the database updates again:

    1
    drush cr && drush updatedb

The intermediate step needs Drupal 11.2, and the last step needs Drupal 11.3.

What happens to your models

In ECA 2, a model consisted of two configuration objects:

eca.eca.<model_id>
The executable model that ECA processes.
eca.model.<model_id>
The raw diagram that the modeler had drawn.

ECA 3 keeps the first one and hands everything about the diagram to the Modeler API, which stores it in third_party_settings.modeler_api of that same eca.eca.<model_id> entity. The label, documentation, changelog, tags, and version of a model move into the same place. For the full list of keys in that envelope, see Modeler API metadata.

Once the content of an eca.model.* object has been carried over, the migration deletes it, because ECA 3.1 no longer ships a schema that describes it. The default storage strategy puts the diagram straight into the third-party settings, so no second configuration object replaces it. Raw diagram data can also live in a separate config entity or nowhere at all, and a site that has chosen one of those strategies keeps it. The three strategies are described under ECA model config files.

Form events change their executable configuration. The single form_id setting of ECA 2 became the list form_ids in ECA 3, and the migration renames it both in the eca.eca.* entity and in the copy of the event configuration that the diagram carries.

Check the result

The migration is automatic, and apart from the update message it is invisible. These five checks confirm that it did what it should:

  1. Read the update message. drush updatedb reports Handed <n> ECA model(s) over to the Modeler API: <model_ids>., or No ECA models needed to be handed over to the Modeler API. on a site that went through ECA 3.0 already.

  2. No ECA 2 diagram objects are left behind. An empty array is the expected result:

    1
    drush php:eval 'print_r(\Drupal::configFactory()->listAll("eca.model."));'

  3. Every model carries the Modeler API envelope:

    1
    drush config:get eca.eca.<model_id> third_party_settings

    Expect a modeler_api key with modeler_id: bpmn_io and the diagram under data. A model that never had a diagram gets modeler_id: fallback and no diagram data, which is the correct outcome for it.

  4. Form events use the new key:

    1
    drush config:get eca.eca.<model_id> events

    No form_id may remain anywhere in the output. Form events list their forms under form_ids now.

  5. Open your models at /admin/config/workflow/eca. Labels, tags, documentation, and the diagram layout all come from the third-party settings now, so a model that opens with its original label and layout confirms the handover.

Export your configuration again afterwards, because both the executable model and its metadata changed:

1
drush config:export

When the update reports a problem

The migration keeps the raw data of every model it could not migrate and stays pending, so you can resolve the cause and run drush updatedb again. Three messages are worth knowing:

The diagrams of the following ECA models can not be read ...
bpmn_io is not installed, so the diagrams cannot be parsed. Install and enable it, then run the database updates again.
The following ECA models could not be migrated, because one or more of their plugins is no longer available ...
A model references a plugin that the site does not provide, which after an upgrade to ECA 3.1 is usually a plugin from one of the extracted integrations. Install the replacement module, then run the database updates again.
The Modeler API model owner plugin for ECA is not available ...
The migration needs the ECA UI module, which provides that plugin. Enable eca_ui, then run the database updates again.

Integrations extracted in ECA 3.1

ECA 3.1 removed six contrib integrations from ECA itself. Install the replacement for every integration you use, so that the migration finds each plugin your models reference:

Integration Replacement
AI function calls AI Integration - ECA
Inline Entity Form ECA Inline Entity Form
Project Browser ECA Project Browser
Field Widget Actions ECA Field Widget Actions
Token None
Webform None

The last two rows cost you nothing. ECA 3.1 dropped its dependency on the contrib Token module, which only ever served ECA's own tests, and its entity comparison now handles the one piece of Webform logic on its own, without depending on Webform. Webform events, conditions, and actions come from ECA Webform, as they did before.

For the wider picture, see Modules extending ECA.

After the upgrade

ECA 3.1 also removed all code that ECA 3.0 had marked as deprecated. Custom plugins or other custom code that called a deprecated ECA API need to be updated to the replacement API.

The release notes carry the full change lists:

The direct route from ECA 2.1 to ECA 3.1 was restored in issue #3590389, which also documents why it works.