Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 30 ยท Events, Flows and Background Work

Flow Builder: Triggers and Custom Actions

Understand Shopware Flow Builder triggers, conditions and actions, and write a custom FlowAction with aware interfaces, registration and an admin form.

A subscriber is code that always runs when an event happens. Merchants often want something softer: "when an order is placed and the total is over 500, add a tag and send a mail", configured in the Administration without a developer. That is the Flow Builder. A merchant combines a trigger (an event), optional conditions and a list of actions. As a plugin developer you can add your own actions, so merchants can use your functionality inside their flows.

This lesson explains the concepts, how a trigger supplies data, how a custom FlowAction is written and registered, and what the administration side needs. Shopware cannot run here, so the platform code is read-only. The runnable part is a small flow engine in plain PHP, with conditions, actions and a check that an action can only run when its trigger provides the data it needs. The method names in the real API changed between Shopware versions, so verify them against the version you target.

The pieces of a flow

A flow has four parts:

  1. Trigger. The event that starts the flow, such as "order placed" or "customer registered". Triggers are Shopware business events.
  2. Rules or conditions. Optional checks on the data of the event. Flow Builder reuses the platform's rule system (the same rules used for shipping and payment availability). A branch can have an "if" and an "else" path.
  3. Actions. Things to do: send a mail, add a tag, change a state, call a webhook, or your custom action.
  4. Sequences. Actions and conditions are arranged in order, and conditions fork the sequence.
flowchart TD
    T["Trigger:<br/>checkout.order.placed"] --> C{"Condition:<br/>order total over 500?"}
    C -- yes --> A1["Action: add tag 'vip'"]
    A1 --> A2["Action: acme.notify.sales<br/>(custom)"]
    C -- no --> A3["Action: send confirmation mail"]

A merchant builds this in the Administration under Settings, then Flow Builder. The custom action is one more box to choose from.

Flows are stored in the database. When the trigger event happens, the platform loads the flows for that event, evaluates the conditions and runs the actions. Merchants can switch flows on and off without a deployment, which is the reason to prefer a flow action over a hard-coded subscriber when the behavior is optional.

What a trigger provides: aware interfaces

An event only helps an action if it carries the data that action needs. Shopware expresses this with small aware interfaces. An event that carries an order implements OrderAware, and one with a customer implements CustomerAware; there are more, such as MailAware, SalesChannelAware and CustomerGroupAware.

An action declares what it requires. The Administration then only offers the action for triggers that fulfill all requirements. If a trigger has no order, an order-only action is hidden, and it can never fail at runtime because of missing data.

Writing a custom action

A custom action extends Shopware\Core\Content\Flow\Dispatching\Action\FlowAction. It has three jobs: give itself a name, list its requirements, and do the work.

PHP
<?php declare(strict_types=1);

namespace Acme\Notify\Flow\Action;

use Psr\Log\LoggerInterface;
use Shopware\Core\Content\Flow\Dispatching\Action\FlowAction;
use Shopware\Core\Content\Flow\Dispatching\StorableFlow;
use Shopware\Core\Framework\Event\OrderAware;

class NotifySalesAction extends FlowAction
{
    public function __construct(private readonly LoggerInterface $logger)
    {
    }

    public static function getName(): string
    {
        return 'action.acme.notify.sales';
    }

    /**
     * @return array<int, string>
     */
    public function requirements(): array
    {
        return [OrderAware::class];
    }

    public function handleFlow(StorableFlow $flow): void
    {
        $orderId = $flow->getStore('orderId');
        $config = $flow->getConfig(); // values the merchant entered in the action form

        $this->logger->info('Notify sales about order', [
            'orderId' => $orderId,
            'channel' => $config['channel'] ?? 'default',
        ]);
    }
}

Things to note:

  • The name is a unique string. Convention is action.<vendor>.<what>, so it cannot clash with core actions like action.add.order.tag.
  • requirements() lists the aware interfaces. The action receives its data from the StorableFlow. For an order flow, getStore('orderId') gives the id, and getData(...) gives the entity if it was loaded. The exact accessors depend on the version, so check StorableFlow.
  • getConfig() returns what the merchant typed into the action's form.
  • handleFlow should be quick. Flows may run in the request that placed the order. For slow work, dispatch a message.
  • Be defensive: re-load the order by id and handle a missing record, because the flow may run asynchronously.

Register the class as a service with the subscriber tag. Flow actions are wired through the event system:

XML
<service id="Acme\Notify\Flow\Action\NotifySalesAction">
    <argument type="service" id="logger"/>
    <tag name="kernel.event_subscriber"/>
</service>

The base class declares the events it listens to, so the tag is all you add. After a cache clear, the platform knows the action.

The Administration side

The backend part makes the action visible and gives it a form. In the plugin's Administration JavaScript you register the action name with a label and an icon, and you provide a modal component for its settings. The registration happens through the flowBuilderService:

JavaScript
// sketch only: the API of this service differs between Shopware versions
Shopware.Service('flowBuilderService').addIcons({
    'action.acme.notify.sales': 'regular-bell',
});

Shopware.Service('flowBuilderService').addLabels({
    'action.acme.notify.sales': 'acme-notify.flow.actionLabel',
});

The label points to a snippet key, which you define in the plugin's snippet JSON files, so the text can be translated. The settings form is a Vue component, shown in a modal when the merchant clicks the action. It emits the entered values, which later arrive as getConfig(). The Administration is the subject of The Administration at a Glance; for now remember that three things must line up: the action name in PHP, the name in the admin registration, and the snippet keys.

Custom triggers

You can also add your own trigger. A trigger is a business event class that implements FlowEventAware. It names itself, declares the data it provides, and implements the aware interfaces for the data it carries. Dispatching it works like any other event:

PHP
$this->eventDispatcher->dispatch(new LabelPrintedEvent($order, $context));

Flows listening to that event then run. A custom trigger is worthwhile when your plugin produces a business moment other plugins or merchants should react to, such as "label printed" or "return approved".

Flow or subscriber?

Situation Use
Must always happen, whatever the merchant configures Subscriber
Technical bookkeeping, indexing, cache handling Subscriber
Optional business reaction a merchant should tune Flow action
Needs conditions chosen by the merchant Flow action
High-volume event (every product read) Subscriber (flows are for business events)

The order lifecycle that most triggers represent is explained in Order Lifecycle.

Try it: a tiny flow engine

This stand-in is not Shopware's flow dispatcher, but it models the same ideas: an event that implements aware interfaces, a flow with a condition and an if/else path, and actions that declare requirements. The engine skips an action whose requirements the trigger cannot fulfill, mirroring how the Administration hides such actions.

PHP Triggers, conditions and actions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The last flow deliberately wires an order action to a trigger without an order. The engine skips it. In real Shopware the Administration would not even offer that action for the trigger.

Try it: reading the config of an action

Real actions receive the form values of the merchant as configuration. Good actions validate it and fail with a clear message. This stand-in builds the registry the Administration would read, listing which actions fit which trigger, and validates a configuration before running.

PHP Which actions fit which trigger, and validating config

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Both examples are stand-ins. What is real: actions declare requirements through aware interfaces, and the platform uses them to decide where an action may appear. What is stand-in: the engine, the config validation, and the class names for events.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a flow made of in Flow Builder?

    A trigger event starts the flow, conditions select a branch, and actions do the work.
  2. 2. What is the purpose of requirements() in a FlowAction?

    Aware interfaces such as OrderAware describe the data a trigger carries. Actions with unmet requirements are not offered.
  3. 3. When is a flow action better than a subscriber?

    Flows are merchant-configurable. Subscribers are for code that must always run.
  4. 4. Which three names must match between PHP and the Administration for a custom action?

    The PHP name identifies the action, the admin registration makes it visible, and snippets provide translatable text.

Summary

  • Flow Builder lets merchants combine triggers, conditions and actions in the Administration, without code.
  • Triggers are business events; aware interfaces such as OrderAware describe the data they carry.
  • A custom action extends FlowAction, returns a unique name, lists its requirements and implements the handler; the merchant's form values arrive as configuration.
  • The action is registered as a tagged service, and the Administration needs a matching registration, snippet labels and a form component.
  • Use a flow action for optional business reactions and a subscriber for behavior that must always run; keep handlers fast and use the queue for slow work.

Next, run work on a schedule and in the background with Scheduled Tasks and the Message Queue.