Skip to content

Custom events

Custom events are user-defined events that you create and trigger yourself from within ECA models. They allow you to build modular, reusable workflows by breaking complex logic into smaller, self-contained processes.

What are custom events used for?

Custom events serve several important purposes:

  • Modularity: Split large models into smaller, focused models that communicate via custom events. This makes models easier to understand and maintain.
  • Looping: Iterate over lists of items by triggering a custom event for each item. See Loops.
  • Reusability: Define a process once and trigger it from multiple places. For example, a "send notification" custom event model can be triggered from different models throughout your site.
  • Token forwarding: Pass data between models by forwarding tokens to the custom event.

Types of custom events

ECA provides two types of custom events:

Custom event
The basic Custom event listens for a specific event ID and receives forwarded tokens. It does not carry an entity context by default.
Entity-aware custom event
The Entity-aware custom event works like a standard custom event but also carries a content entity. The entity is always available under the token name entity in the receiving model, in addition to any forwarded tokens.

Triggering custom events

Custom events are triggered explicitly using action plugins:

Trigger custom event
The Trigger custom event action fires a custom event with a specified event ID. You can list tokens to forward to the receiving model.
Trigger entity-aware custom event
The Trigger entity-aware custom event action fires an entity-aware custom event, forwarding both the specified entity and any additional tokens.
Trigger via Drush

Custom events can also be triggered from the command line using Drush:

1
drush eca:trigger:custom-event my_event_id

This is useful for cron jobs, scripts, or manual triggering during development and testing.

The event ID

Every custom event has an event ID -- a string that identifies which custom event is being triggered. The event ID is how the triggering action and the listening event are matched.

  • The event ID can be any string value you choose (e.g. send_welcome_email, process_order, notify_admins).
  • The event ID is case-sensitive.
  • Multiple models can listen for the same event ID -- they will all be triggered.

Empty event IDs

An event ID can be left empty. A custom event with an empty event ID acts as a catch-all: it responds to every custom event trigger, regardless of the ID used. This can be useful for logging or auditing purposes but should be used with care to avoid unintended processing.

Forwarding tokens

When triggering a custom event, the Tokens to forward field specifies which tokens from the current process should be made available in the triggered event's process.

  • Enter a comma-separated list of token names (without brackets): e.g. node, user, myValue.
  • The tokens will be available in the receiving model under the same names.
  • For entity-aware custom events, the entity is always forwarded automatically -- you do not need to include it in the tokens list.

Common pitfall

If tokens appear blank or missing in the custom event's process, the most likely cause is that they were not listed in the "Tokens to forward" field. This is one of the most frequently encountered issues when working with custom events.

Practical example

Consider a model that processes new article nodes and needs to notify all editors:

Model 1: Content created

  1. Event: Insert content entity (bundle: article)
  2. Action: Trigger custom event with ID notify_editors, forwarding the token node

Model 2: Notify editors

  1. Event: Custom event with ID notify_editors
  2. Action: Execute a View returning all users with the "editor" role
  3. For each user, send an email using [node:title] and [user:mail]

This separation keeps the content creation model clean and the notification logic reusable.

Best practices

  • Use descriptive event IDs: Choose clear, meaningful names like order_completed rather than vague ones like event1.
  • Document your custom events: Since custom events are user-defined, they are not documented automatically. Add comments or notes in your models to explain what each custom event does.
  • Forward only what is needed: Keep the "Tokens to forward" list focused on the tokens the receiving model actually uses.
  • Avoid circular triggers: Be careful not to create situations where model A triggers a custom event handled by model B, which in turn triggers a custom event handled by model A. This can cause infinite loops.