Importing Models

ECA models can be imported into your Drupal site in several ways. This guide covers all available import methods, explains common issues that may arise during import, and provides solutions for resolving them.

Import methods

Using recipes (recommended)

Since Drupal 10.3, the recommended way to import models from the ECA Library is via recipes. Each library model is available as a Composer package that can be applied as a Drupal recipe.

# Require the recipe package
composer require drupal-eca-recipe/eca_lib_XXXX

# Apply the recipe with Drush (version 13 or later):
drush recipe ../recipes/eca_lib_XXXX

# Or apply the recipe without Drush:
cd web && php core/scripts/drupal recipe ../recipes/eca_lib_XXXX

# Rebuilding caches is optional, sometimes required:
drush cr

Replace XXXX with the library model number. Each library model page shows the exact commands to use.

Tip

Recipes handle dependencies automatically. If the model requires additional configuration entities (e.g. content types, fields, or vocabularies), the recipe will create them for you.

Using the ECA admin UI

Models can also be imported manually through the ECA admin interface at /admin/config/workflow/eca:

1. Click the Import button in the top right corner.
2. Select the file to import.
3. Click Import to validate and import the model.

Two file types are supported:

eca.model.[MODEL-ID].yml

A single YAML config file containing the proprietary model data. ECA will recreate the companion eca.eca.[MODEL-ID] config entity automatically, provided the appropriate modeler is enabled. See ECA model config files for details.

[MODELER-TYPE]-[MODEL-ID].tar.gz

An archive file previously exported from another Drupal site or downloaded from the ECA Library. The archive contains:

• dependencies.yml — metadata listing required config entities and modules
• eca.eca.[MODEL-ID].yml — the ECA processing config entity
• eca.model.[MODEL-ID].yml — the modeler-specific model data
• optionally, additional config entities that the model depends on

Note

When importing an archive, do not rename the file. The filename is validated during import and must match the pattern [MODELER-TYPE]-[MODEL-ID].tar.gz.

Using Drupal's configuration management

ECA models are standard Drupal configuration. You can also deploy them through Drupal's configuration synchronisation system by placing the two config files (eca.eca.[MODEL-ID].yml and eca.model.[MODEL-ID].yml) into your configuration sync directory and running a config import:

drush config:import

This is particularly useful for deploying models from a development environment to production. See also the recommended setup for production sites.

Troubleshooting import failures

Sometimes, importing a model may fail. Below are the most common causes and their solutions.

Existing entities prevent import

Symptom: The import fails with a message similar to:

The import failed due to the following reason: There were errors validating the config synchronization. Entities exist of type Content and Content type Basic page. These entities need to be deleted before importing.

Cause: The model archive includes configuration for entities such as content types, vocabularies or fields. If those entities already exist on your site with content attached to them, Drupal's configuration validation rejects the import because it would overwrite existing configuration that has dependent data.

Solutions:

1. Check for conflicting entities. Compare the configuration in the archive with what already exists on your site. If the existing configuration matches what the model expects, the import may succeed after removing the conflicting config entities from the archive. Extract the archive, remove the unnecessary files, update dependencies.yml accordingly, and repackage it.

2. Delete conflicting content first. If the existing entities contain test data or content you do not need, delete the content and then the configuration entities before retrying the import.

3. Import only the ECA model files. Instead of importing the full archive, import just the eca.model.[MODEL-ID].yml file through the admin UI. This skips the dependency configuration but requires that all dependencies already exist on your site with a compatible setup.

4. Use the recipe method. Recipes handle existing configuration more gracefully. If the configuration already exists and is compatible, the recipe will skip creating it and only add the ECA model.

Tip

For more context on this issue, see drupal.org issue #3381483.

Missing required modules

Symptom: The import fails because one or more required modules are not enabled.

Cause: The model uses plugins provided by modules that are not installed on your site. The dependencies.yml file in the archive lists all required modules.

Solution: Enable the required modules before importing:

# Check which modules are required by extracting the archive
# and reading the dependencies.yml file, then enable them:
drush en module_name_1 module_name_2

When using the recipe method, missing modules are listed as Composer dependencies. Running composer require for the recipe package will automatically install the required modules.

Modeler not available

Symptom: The model imports but cannot be edited, or the import of a .yml file fails to recreate the eca.eca config entity.

Cause: The model was created with a specific modeler (e.g. the Workflow Modeler or BPMN.iO), and that modeler is not enabled on your site.

Solution: Enable the modeler that was used to create the model. All ECA Library models are built with the Workflow Modeler, so enabling eca_ui and eca_modeller_bpmn is sufficient for library models:

drush en eca_ui eca_modeller_bpmn

Archive filename has been changed

Symptom: The import fails during file validation.

Cause: The archive file was renamed after export. ECA validates the filename to extract the modeler type and model ID.

Solution: Restore the original filename matching the pattern [MODELER-TYPE]-[MODEL-ID].tar.gz. If you do not know the original name, extract the archive and check the config filenames inside — the model ID is part of the eca.model.[MODEL-ID].yml filename.

Configuration validation errors

Symptom: The import fails with generic configuration validation errors.

Cause: This can happen when the model was created on a different version of Drupal or ECA, and there are schema differences between versions.

Solution:

1. Ensure you are running a compatible version of ECA. Check the model's documentation or the library page for version requirements.
2. Update ECA to the latest version: composer update drupal/eca
3. If the issue persists, try importing just the eca.model.[MODEL-ID].yml file instead of the full archive.

Best practices for importing

• Back up your site before importing models, especially on production environments.
• Review the model before importing. Each library model page includes a visual representation of the model and a list of its dependencies.
• Use a development environment to test imported models before deploying them to production.
• Prefer recipes when importing library models — they handle dependencies automatically and are more resilient to existing configuration.
• Keep your ECA installation up to date to ensure compatibility with the latest library models.