From 021012e620820bbb1d0902f0eda793ad626742a3 Mon Sep 17 00:00:00 2001 From: Dnyaneshwar S Jambhulkar Date: Tue, 16 Sep 2025 23:53:01 +0530 Subject: [PATCH 01/43] AC-15629::Adobe Development Doc - Message Queues - ActiveMq (Artemis) updates --- .../components/message-queues/index.md | 50 +++++++++++++++++-- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/src/pages/development/components/message-queues/index.md b/src/pages/development/components/message-queues/index.md index 10db2b50d..36ed357c4 100644 --- a/src/pages/development/components/message-queues/index.md +++ b/src/pages/development/components/message-queues/index.md @@ -9,9 +9,12 @@ keywords: Message queues provide an asynchronous communications mechanism in which the sender and the receiver of a message do not contact each other, nor do they need to communicate with the message queue at the same time. When a sender places a message onto a queue, it is stored until the recipient receives them. -In Adobe Commerce and Magento Open Source, the Message Queue Framework (MQF) is a fully-functional system that allows a module to publish messages to queues. It also creates consumers to receive them asynchronously. The MQF primarily uses [RabbitMQ](http://www.rabbitmq.com) as the messaging broker, which provides a scalable platform for sending and receiving messages. It also includes a mechanism for storing undelivered messages. RabbitMQ is based on the Advanced Message Queuing Protocol (AMQP) 0.9.1 specification. +In Adobe Commerce and Magento Open Source, the Message Queue Framework (MQF) is a fully-functional system that allows a module to publish messages to queues. It also creates consumers to receive them asynchronously. The MQF supports multiple messaging brokers: -A basic message queue system can also be set up without using RabbitMQ. In this system, a MySQL adapter stores messages in the database. Three database tables (`queue`, `queue_message`, and `queue_message_status`) manage the message queue workload. Cron jobs ensure the consumers are able to receive messages. This solution is not very scalable. RabbitMQ should be used whenever possible. +- **[RabbitMQ](http://www.rabbitmq.com)** - The primary messaging broker, which provides a scalable platform for sending and receiving messages. It includes a mechanism for storing undelivered messages and is based on the Advanced Message Queuing Protocol (AMQP) 0.9.1 specification. +- **[Apache ActiveMQ Artemis](https://activemq.apache.org/components/artemis/)** - An alternative messaging broker that uses the STOMP (Simple Text Oriented Messaging Protocol) for reliable and scalable messaging, offering flexibility for STOMP-based integrations. + +A basic message queue system can also be set up without using external message brokers. In this system, a MySQL adapter stores messages in the database. Three database tables (`queue`, `queue_message`, and `queue_message_status`) manage the message queue workload. Cron jobs ensure the consumers are able to receive messages. This solution is not very scalable. External message brokers like RabbitMQ or ActiveMQ Artemis should be used whenever possible. See [Configure message queues](configuration.md) for information about setting up the message queue system. @@ -49,7 +52,11 @@ Perform the following actions: 1. Decode the message using topic name taken from the `\Magento\Framework\MessageQueue\ConsumerConfigurationInterface`. 1. Invoke callback `Magento\Framework\MessageQueue\ConsumerConfigurationInterface::getCallback` and pass the decoded data as an argument. -## Change message queue from MySQL to AMQP +### ActiveMQ Artemis (STOMP) + +Same as RabbitMQ, this is also instantiates a consumer that is defined in a [`queue_consumer.xml`](configuration.md#queue_consumerxml) file. The consumer (`customer_created_listener`) listens to the queue and receives all new messages. For every message, it invokes `Magento\Some\Class::processMessage($message)` + +## Change message queue from MySQL to external brokers The following sample introduces a runtime configuration that allows you to redefine the adapter for a topic. @@ -85,3 +92,40 @@ The following sample introduces a runtime configuration that allows you to redef ], ], ``` + +### Switch from MySQL to STOMP (ActiveMQ Artemis) + +The following configuration shows how to configure a topic to use STOMP instead of MySQL: + +```php +'queue' => [ + 'topics' => [ + 'inventory.update' => [ + 'publisher' => 'stomp-magento' + ] + ], + 'config' => [ + 'publishers' => [ + 'inventory.update' => [ + 'connections' => [ + 'stomp' => [ + 'name' => 'stomp', + 'exchange' => 'magento', + 'disabled' => false + ], + 'db' => [ + 'name' => 'db', + 'exchange' => 'magento', + 'disabled' => true + ] + ] + ] + ] + ], + 'consumers' => [ + 'inventory.update' => [ + 'connection' => 'stomp', + ], + ] +], +``` From 15842dc5a24c4610233067f6a07c9b827fdb69e6 Mon Sep 17 00:00:00 2001 From: Dnyaneshwar S Jambhulkar Date: Fri, 19 Sep 2025 00:42:23 +0530 Subject: [PATCH 02/43] AC-15629::Adobe Development Doc - Message Queues - ActiveMq (Artemis) updates --- .../message-queues/async-configuration.md | 18 +++++++---- .../message-queues/bulk-operations-example.md | 30 +++++++++++++++---- 2 files changed, 38 insertions(+), 10 deletions(-) diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index ef216ef16..8ffebb42e 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -46,28 +46,36 @@ The `queue_publisher.xml` file is generated by the `\Magento\WebapiAsync\Code\Ge The sort order is set to 0 and allows developers to change some aspects of the generated configuration in configuration readers such as `queue_publisher.xml` and `env.php`. -`\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of all REST API routes which can be executed asynchronously. Then it defines the connection name as `amqp` and the exchange as `magento` for each generated topic name. +`\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of all REST API routes which can be executed asynchronously. Then it defines the connection name as `amqp` (or `stomp` for ActiveMQ Artemis) and the exchange as `magento` for each generated topic name. ## queue_consumer.xml The asynchronous/bulk API has one defined consumer which processes all asynchronous/bulk APIs messages. ```xml - ``` +The connection type (AMQP or STOMP) is determined automatically based on your `env.php` configuration. + ### queue_topology.xml The message queue topology configuration links all auto-generated topic names with prefix `async.` to the `magento` exchange and defines the queue named `async.operations.all` as the destination for all messages. ```xml - + ``` +The connection type is automatically determined from your `env.php` configuration. + + + +Message queues connection is defined dynamically based on deployment configuration in `env.php`. If AMQP or STOMP is configured in deployment configuration of the queue, the respective connection is used. Otherwise, db connection is used. +As a result, if AMQP or STOMP is configured in deployment configuration of the queue, connection declaration can be omitted in [message queue configuration files](./configuration.md): `queue_customer.xml`, `queue_publisher.xml`, `queue_topology.xml`. + -Message queues connection is defined dynamically based on deployment configuration in `env.php`. If AMQP is configured in deployment configuration of the queue, AMQP connection is used. Otherwise, db connection is used. -As a result, if AMQP is configured in deployment configuration of the queue, connection declaration can be omitted in [message queue configuration files](./configuration.md): `queue_customer.xml`, `queue_publisher.xml`, `queue_topology.xml`. +ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.6 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. diff --git a/src/pages/development/components/message-queues/bulk-operations-example.md b/src/pages/development/components/message-queues/bulk-operations-example.md index e75df910a..c1f9f6674 100644 --- a/src/pages/development/components/message-queues/bulk-operations-example.md +++ b/src/pages/development/components/message-queues/bulk-operations-example.md @@ -319,35 +319,55 @@ The `queue_consumer.xml` file defines the relationship between a queue and its c ```xml - + ``` +The connection type (AMQP or STOMP) is determined automatically based on your `env.php` configuration. + ### Create `queue_publisher.xml` The `queue_publisher.xml` file defines the exchange where a topic is published. Create this file with the following contents: +**For RabbitMQ (AMQP):** + ```xml - + ``` +**For ActiveMQ Artemis (STOMP):** + +```xml + + + +``` + +**Note**: For ActiveMQ Artemis, the `` element is not required as the connection type is determined from `env.php`. When the topic name and queue name are different, you must specify the `queue` attribute in the `` element. + ### Create `queue_topology.xml` The `queue_topology.xml` file defines the message routing rules and declares queues and exchanges. Create this file with the following contents: ```xml - + ``` +The connection type is automatically determined from your `env.php` configuration. + + + +Message queue connections are defined dynamically, based on the deployment configuration in the `env.php` file. If AMQP or STOMP is configured in the deployment configuration of the queue, the respective connection is used. Otherwise, database connections are used. +As a result, if AMQP or STOMP is configured in the deployment configuration of the queue, you can omit connection declarations in the `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml` [message queue configuration files](./configuration.md). + -Message queue connections are defined dynamically, based on the deployment configuration in the `env.php` file. If AMQP is configured in the deployment configuration of the queue, AMQP connections are used. Otherwise, database connections are used. -As a result, if AMQP is configured in the deployment configuration of the queue, you can omit connection declarations in the `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml` [message queue configuration files](./configuration.md). +ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.6 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. From aa82663ec64117f2cc81684438f74e2dbe36fbce Mon Sep 17 00:00:00 2001 From: Dnyaneshwar S Jambhulkar Date: Fri, 19 Sep 2025 00:43:54 +0530 Subject: [PATCH 03/43] AC-15629::Adobe Development Doc - Message Queues - ActiveMq (Artemis) updates --- src/pages/development/components/message-queues/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/index.md b/src/pages/development/components/message-queues/index.md index 36ed357c4..ed9b11831 100644 --- a/src/pages/development/components/message-queues/index.md +++ b/src/pages/development/components/message-queues/index.md @@ -54,7 +54,7 @@ Perform the following actions: ### ActiveMQ Artemis (STOMP) -Same as RabbitMQ, this is also instantiates a consumer that is defined in a [`queue_consumer.xml`](configuration.md#queue_consumerxml) file. The consumer (`customer_created_listener`) listens to the queue and receives all new messages. For every message, it invokes `Magento\Some\Class::processMessage($message)` +Similar to RabbitMQ, ActiveMQ Artemis instantiates a consumer that is defined in a [`queue_consumer.xml`](configuration.md#queue_consumerxml) file. The consumer (`customer_created_listener`) listens to the queue and receives all new messages. For every message, it invokes `Magento\Some\Class::processMessage($message)` ## Change message queue from MySQL to external brokers From 7c1af0bfd5d86b5e51f0a794ae58f12eb138686b Mon Sep 17 00:00:00 2001 From: Dnyaneshwar S Jambhulkar Date: Fri, 19 Sep 2025 16:57:01 +0530 Subject: [PATCH 04/43] AC-15629::Adobe Development Doc - Message Queues - ActiveMq (Artemis) updates --- .../message-queues/configuration.md | 36 +++- .../components/message-queues/migration.md | 201 ++++++++++++++++++ 2 files changed, 230 insertions(+), 7 deletions(-) diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index aa68277c0..8351fd347 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -28,7 +28,7 @@ Depending on your needs, you may only need to create and configure `communicatio ## `communication.xml` -The `/etc/communication.xml` file defines aspects of the message queue system that all communication types have in common. This release supports AMQP and database connections. +The `/etc/communication.xml` file defines aspects of the message queue system that all communication types have in common. This release supports AMQP, STOMP, and database connections. ### Example @@ -81,8 +81,8 @@ The `queue_consumer.xml` file contains one or more `consumer` elements: - - + + ``` @@ -94,7 +94,7 @@ The `queue_consumer.xml` file contains one or more `consumer` elements: | queue (required) | Defines the queue name to send the message to. | | handler | Specifies the class and method that processes the message. The value must be specified in the format `\Module\::`.| | consumerInstance | The class name that consumes the message. Default value: `Magento\Framework\MessageQueue\Consumer`. | -| connection | Connection is defined dynamically based on deployment configuration of message queue in `env.php`. If AMQP is configured in deployment configuration, AMQP connection is used. Otherwise, db connection is used. If you still want to specify connection type for consumer, keep in mind that for AMQP connections, the connection name must match the `connection` attribute in the `queue_topology.xml` file. Otherwise, the connection name must be `db`. | +| connection | Connection is defined dynamically based on deployment configuration of message queue in `env.php`. If AMQP or STOMP is configured in deployment configuration, the respective connection is used. Otherwise, db connection is used. If you still want to specify connection type for consumer, keep in mind that for AMQP connections, the connection name must match the `connection` attribute in the `queue_topology.xml` file. For STOMP connections, use `stomp`. Otherwise, the connection name must be `db`. | | maxMessages | Specifies the maximum number of messages to consume.| | maxIdleTime | Defines the maximum waiting time in seconds for a new message from the queue. If no message was handled within this period of time, the consumer exits. Default value: `null`| | sleep | Specifies time in seconds to sleep before checking if a new message is available in the queue. Default value is `null` which equals to 1 second.| @@ -178,7 +178,7 @@ The `queue_topology.xml` file defines the message routing rules and declares que | -------------- | ----------- | name (required) | A unique ID for the exchange. type | Specifies the type of exchange. The default value is `topic` because only `topic` type is supported. - connection (required) | Connection is defined dynamically based on deployment configuration of message queue in `env.php`. If AMQP is configured in deployment configuration, AMQP connection is used. Otherwise, db connection is used. If you still want to specify connection, the connection name must be `amqp` for AMQP. For MySQL connections, the connection name must be `db`. + connection (required) | Connection is defined dynamically based on deployment configuration of message queue in `env.php`. If AMQP or STOMP is configured in deployment configuration, the respective connection is used. Otherwise, db connection is used. If you still want to specify connection, the connection name must be `amqp` for AMQP, `stomp` for STOMP. For MySQL connections, the connection name must be `db`. durable | Boolean value indicating whether the exchange is persistent. Non-durable exchanges are purged when the server restarts. The default is `true`. autoDelete | Boolean value indicating whether the exchange is deleted when all queues have finished using it. The default is `false`. internal | Boolean value. If set to true, the exchange may not be used directly by publishers, but only when bound to other exchanges. The default is `false`. @@ -233,6 +233,8 @@ The `queue_publisher.xml` file defines which connection and exchange to use to p ### Example +**For RabbitMQ (AMQP):** + ```xml @@ -244,20 +246,34 @@ The `queue_publisher.xml` file defines which connection and exchange to use to p ``` +**For ActiveMQ Artemis (STOMP):** + +```xml + + + + + + + + +``` + #### `publisher` element | Attribute | Description | | -------------------- | ----------- | | topic (required) | The name of the topic. | +| queue | For ActiveMQ Artemis (STOMP), specify the queue name when it differs from the topic name. | | disabled | Determines whether this queue is disabled. The default value is `false`. | #### `connection` element -The `connection` element is a subnode of the `publisher` element. There must not be more than one enabled active connection to a publisher defined at a time. If you omit the `connection` element, connection will be defined dynamically based on deployment configuration of message queue in `env.php` and exchange `magento` will be used. If AMQP is configured in deployment configuration, AMQP connection is used. Otherwise, db connection is used. +The `connection` element is a subnode of the `publisher` element. There must not be more than one enabled active connection to a publisher defined at a time. If you omit the `connection` element, connection will be defined dynamically based on deployment configuration of message queue in `env.php` and exchange `magento` will be used. If AMQP or STOMP is configured in deployment configuration, the respective connection is used. Otherwise, db connection is used. | Attribute | Description | | -------------------- | ----------- | -| name | Connection name is defined dynamically based on deployment configuration of message queue in `env.php`. If you still want to specify connection type for publisher, keep in mind that for AMQP connections, the connection name must match the `connection` attribute in the `queue_topology.xml` file. Otherwise, the connection name must be `db`. | +| name | Connection name is defined dynamically based on deployment configuration of message queue in `env.php`. If you still want to specify connection type for publisher, keep in mind that for AMQP connections, the connection name must match the `connection` attribute in the `queue_topology.xml` file. For STOMP connections, use `stomp`. Otherwise, the connection name must be `db`. | | exchange | The name of the exchange to publish to. The default system exchange name is `magento`. | | disabled | Determines whether this queue is disabled. The default value is `false`. | @@ -265,6 +281,12 @@ The `connection` element is a subnode of the `publisher` element. There must not You cannot enable more than one `publisher` for each `topic`. +## ActiveMQ Artemis (STOMP) Support + + + +ActiveMQ Artemis (STOMP) support was introduced in Adobe Commerce 2.4.6 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. + ## Updating `queue.xml` See [Migrate message queue configuration](migration.md) for information about upgrading from Adobe Commerce and Magento Open Source 2.0 or 2.1. diff --git a/src/pages/development/components/message-queues/migration.md b/src/pages/development/components/message-queues/migration.md index ee5a47094..35e18e7e3 100644 --- a/src/pages/development/components/message-queues/migration.md +++ b/src/pages/development/components/message-queues/migration.md @@ -8,6 +8,207 @@ keywords: # Migrate message queue configuration +## Migrate from 2.4.5 to 2.4.6, 2.4.7, 2.4.8, 2.4.9 + +Adobe Commerce 2.4.9 introduced support for Apache ActiveMQ Artemis (STOMP) as an alternative message broker to RabbitMQ (AMQP). This feature was also backported to versions 2.4.6, 2.4.7, and 2.4.8. When upgrading from 2.4.5 (or earlier) to 2.4.6 or later versions, you have the option to continue using RabbitMQ or migrate to ActiveMQ Artemis. + +### Key Changes in 2.4.6+ + +- **ActiveMQ Artemis (STOMP) Support**: New message broker option alongside RabbitMQ (introduced in 2.4.9, backported to 2.4.6, 2.4.7, 2.4.8) +- **Extended Dynamic Connection Detection**: Existing dynamic connection detection now supports STOMP in addition to AMQP +- **Enhanced SSL Configuration**: Improved SSL options for both brokers +- **Multiple Named Connections**: Enhanced support for configuring multiple broker connections + +### Configuration File Changes + +The following table shows the key differences between 2.4.5 and 2.4.6+ configurations: + +| Configuration Area | 2.4.5 | 2.4.6+ | +| ------------------ | ----- | ------ | +| `env.php` default_connection | Optional when single broker configured | Optional when single broker configured; required when multiple brokers (can be `'amqp'`, `'stomp'`, or `'db'`) | +| `env.php` broker configuration | RabbitMQ (AMQP) only | RabbitMQ (AMQP) and/or ActiveMQ Artemis (STOMP) | +| `queue_consumer.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.6+) | +| `queue_publisher.xml` connection element | Optional for AMQP, supports multiple connections | Optional for AMQP/STOMP, enhanced multiple connections | +| `queue_topology.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.6+) | + +### Update `env.php` Configuration + +**For RabbitMQ (AMQP) - No Changes Required:** +```php +'queue' => [ + 'amqp' => [ + 'host' => 'rabbitmq.example.com', + 'port' => '5672', + 'user' => 'magento', + 'password' => 'magento', + 'virtualhost' => '/', + 'ssl' => false + ] +] +``` + +**For ActiveMQ Artemis (STOMP) - Available in 2.4.6+ (introduced in 2.4.9, backported to 2.4.6-2.4.8):** +```php +'queue' => [ + 'stomp' => [ + 'host' => 'activemq.example.com', + 'port' => '61613', + 'user' => 'artemis', + 'password' => 'artemis', + 'ssl' => false + ] +] +``` + +**For Both Brokers - Available in 2.4.6+ (requires `default_connection`):** +```php +'queue' => [ + 'default_connection' => 'amqp', // Required when multiple brokers are configured + 'amqp' => [ + 'host' => 'rabbitmq.example.com', + 'port' => '5672', + 'user' => 'magento', + 'password' => 'magento', + 'virtualhost' => '/', + 'ssl' => false + ], + 'stomp' => [ + 'host' => 'activemq.example.com', + 'port' => '61613', + 'user' => 'artemis', + 'password' => 'artemis', + 'ssl' => false + ] +] +``` + +>[!NOTE] +> +>The `default_connection` parameter is only required when multiple message brokers are configured. When only one broker (AMQP or STOMP) is configured, the system automatically uses the available broker. + +>[!NOTE] +> +>The `connection` attribute in XML configuration files (`queue_consumer.xml`, `queue_publisher.xml`, `queue_topology.xml`) is optional when you want to use the default broker from `env.php`. However, you can explicitly specify `connection="amqp"` or `connection="stomp"` when you want a particular module or functionality to use a specific broker, even when multiple brokers are configured. + +### Update `queue_consumer.xml` Files + +The first column in the following table lists parameters in 2.4.6+ `queue_consumer.xml` files. The second column shows the equivalent in 2.4.5. + +| 2.4.6+ Attribute | 2.4.5 Equivalent | Notes | +| ----------------- | ----------------- | ----- | +| `/name` | `/name` | No change | +| `/queue` | `/queue` | No change | +| `/handler` | `/handler` | No change | +| `/consumerInstance` | `/consumerInstance` | No change | +| `/connection` | `/connection` | Optional in both versions, auto-detected from env.php. In 2.4.6+ also supports STOMP. Use explicitly to force specific broker selection. | +| `/maxMessages` | `/maxMessages` | No change | + +**2.4.5 Example:** +```xml + +``` + +**2.4.6+ Example (Uses default broker from env.php):** +```xml + +``` + +**2.4.6+ Example (Explicitly specifies broker):** +```xml + + + + + +``` + +### Update `queue_publisher.xml` Files + +The first column in the following table lists parameters in 2.4.6+ `queue_publisher.xml` files. The second column shows the equivalent in 2.4.5. + +| 2.4.6+ Attribute | 2.4.5 Equivalent | Notes | +| ----------------- | ----------------- | ----- | +| `/topic` | `/topic` | No change | +| `/queue` | Not available | Available in 2.4.6+ for ActiveMQ Artemis | +| `/disabled` | `/disabled` | No change | +| `//name` | `//name` | Can specify `stomp` for ActiveMQ (2.4.6+) | +| `//exchange` | `//exchange` | Not used with STOMP | +| `//disabled` | `//disabled` | Enhanced in 2.4.6+ for multiple connections | + +**2.4.5 Example (RabbitMQ only):** +```xml + + + +``` + +**2.4.6+ Example (RabbitMQ):** +```xml + + + + +``` + +**2.4.6+ Example (ActiveMQ Artemis):** +```xml + + + + +``` + +### Update `queue_topology.xml` Files + +The first column in the following table lists parameters in 2.4.6+ `queue_topology.xml` files. The second column shows the equivalent in 2.4.5. + +| 2.4.6+ Attribute | 2.4.5 Equivalent | Notes | +| ----------------- | ----------------- | ----- | +| `/name` | `/name` | No change | +| `/type` | `/type` | No change | +| `/connection` | `/connection` | Optional in both versions, auto-detected from env.php. In 2.4.6+ also supports STOMP. Use explicitly to force specific broker selection. | +| `/durable` | `/durable` | No change | +| `/autoDelete` | `/autoDelete` | No change | +| `//id` | `//id` | No change | +| `//topic` | `//topic` | No change | +| `//destinationType` | `//destinationType` | No change | +| `//destination` | `//destination` | No change | + +**2.4.5 Example:** +```xml + + + +``` + +**2.4.6+ Example (Uses default broker from env.php):** +```xml + + + +``` + +**2.4.6+ Example (Explicitly specifies broker):** +```xml + + + + + + + + + +``` + + + +Connection detection has always been dynamic based on your `env.php` configuration. If AMQP is configured in deployment configuration, the AMQP connection is used automatically. In 2.4.6+, this same dynamic detection was extended to support STOMP connections. This allows you to omit connection declarations in XML configuration files. + + + +ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.9 and backported to versions 2.4.6, 2.4.7, and 2.4.8. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. + ## Migrate from 2.1 to 2.2 To upgrade the message queues for Adobe Commerce or Magento Open Source 2.1, you must create the following files in the `/etc` directory for each module that will use the message queue framework. From 2cc1a363a6098271268e049901b7b78739b8db9c Mon Sep 17 00:00:00 2001 From: Dnyaneshwar S Jambhulkar Date: Sat, 20 Sep 2025 16:56:37 +0530 Subject: [PATCH 05/43] AC-15629::Adobe Development Doc - Message Queues - ActiveMq (Artemis) updates --- .../components/message-queues/migration.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/pages/development/components/message-queues/migration.md b/src/pages/development/components/message-queues/migration.md index 35e18e7e3..40d604fd4 100644 --- a/src/pages/development/components/message-queues/migration.md +++ b/src/pages/development/components/message-queues/migration.md @@ -82,13 +82,13 @@ The following table shows the key differences between 2.4.5 and 2.4.6+ configura ] ``` ->[!NOTE] -> ->The `default_connection` parameter is only required when multiple message brokers are configured. When only one broker (AMQP or STOMP) is configured, the system automatically uses the available broker. + + +The `default_connection` parameter is only required when multiple message brokers are configured. When only one broker (AMQP or STOMP) is configured, the system automatically uses the available broker. + + ->[!NOTE] -> ->The `connection` attribute in XML configuration files (`queue_consumer.xml`, `queue_publisher.xml`, `queue_topology.xml`) is optional when you want to use the default broker from `env.php`. However, you can explicitly specify `connection="amqp"` or `connection="stomp"` when you want a particular module or functionality to use a specific broker, even when multiple brokers are configured. +The `connection` attribute in XML configuration files (`queue_consumer.xml`, `queue_publisher.xml`, `queue_topology.xml`) is optional when you want to use the default broker from `env.php`. However, you can explicitly specify `connection="amqp"` or `connection="stomp"` when you want a particular module or functionality to use a specific broker, even when multiple brokers are configured. ### Update `queue_consumer.xml` Files From e7b89957e810870bd6d064ac1afd7bd2b6ea349f Mon Sep 17 00:00:00 2001 From: Dnyaneshwar S Jambhulkar Date: Sat, 20 Sep 2025 17:04:53 +0530 Subject: [PATCH 06/43] AC-15629::Adobe Development Doc - Message Queues - ActiveMq (Artemis) updates --- .../components/message-queues/migration.md | 24 ++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/src/pages/development/components/message-queues/migration.md b/src/pages/development/components/message-queues/migration.md index 40d604fd4..2b4dcc1f2 100644 --- a/src/pages/development/components/message-queues/migration.md +++ b/src/pages/development/components/message-queues/migration.md @@ -34,6 +34,7 @@ The following table shows the key differences between 2.4.5 and 2.4.6+ configura ### Update `env.php` Configuration **For RabbitMQ (AMQP) - No Changes Required:** + ```php 'queue' => [ 'amqp' => [ @@ -48,6 +49,7 @@ The following table shows the key differences between 2.4.5 and 2.4.6+ configura ``` **For ActiveMQ Artemis (STOMP) - Available in 2.4.6+ (introduced in 2.4.9, backported to 2.4.6-2.4.8):** + ```php 'queue' => [ 'stomp' => [ @@ -61,6 +63,7 @@ The following table shows the key differences between 2.4.5 and 2.4.6+ configura ``` **For Both Brokers - Available in 2.4.6+ (requires `default_connection`):** + ```php 'queue' => [ 'default_connection' => 'amqp', // Required when multiple brokers are configured @@ -104,16 +107,19 @@ The first column in the following table lists parameters in 2.4.6+ `queue_consum | `/maxMessages` | `/maxMessages` | No change | **2.4.5 Example:** + ```xml ``` **2.4.6+ Example (Uses default broker from env.php):** + ```xml ``` **2.4.6+ Example (Explicitly specifies broker):** + ```xml @@ -136,6 +142,7 @@ The first column in the following table lists parameters in 2.4.6+ `queue_publis | `//disabled` | `//disabled` | Enhanced in 2.4.6+ for multiple connections | **2.4.5 Example (RabbitMQ only):** + ```xml @@ -143,6 +150,7 @@ The first column in the following table lists parameters in 2.4.6+ `queue_publis ``` **2.4.6+ Example (RabbitMQ):** + ```xml @@ -151,6 +159,7 @@ The first column in the following table lists parameters in 2.4.6+ `queue_publis ``` **2.4.6+ Example (ActiveMQ Artemis):** + ```xml @@ -175,6 +184,7 @@ The first column in the following table lists parameters in 2.4.6+ `queue_topolo | `//destination` | `//destination` | No change | **2.4.5 Example:** + ```xml @@ -182,6 +192,7 @@ The first column in the following table lists parameters in 2.4.6+ `queue_topolo ``` **2.4.6+ Example (Uses default broker from env.php):** + ```xml @@ -189,6 +200,7 @@ The first column in the following table lists parameters in 2.4.6+ `queue_topolo ``` **2.4.6+ Example (Explicitly specifies broker):** + ```xml @@ -213,9 +225,9 @@ ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.9 and backported t To upgrade the message queues for Adobe Commerce or Magento Open Source 2.1, you must create the following files in the `/etc` directory for each module that will use the message queue framework. -* `queue_consumer.xml` - Defines the relationship between an existing queue and its consumer. -* `queue_topology.xml`- Defines the message routing rules and declares queues and exchanges. -* `queue_publisher.xml` - Defines the exchange where a topic is published. +- `queue_consumer.xml` - Defines the relationship between an existing queue and its consumer. +- `queue_topology.xml`- Defines the message routing rules and declares queues and exchanges. +- `queue_publisher.xml` - Defines the exchange where a topic is published. The existing `queue.xml` file is deprecated. @@ -273,9 +285,9 @@ The first column in the following table lists the all the parameters in the `que To upgrade from Adobe Commerce or Magento Open Source 2.0, you must create the following files in the `/etc` directory for each module that will use the message queue framework. -* `queue_consumer.xml` - Defines the relationship between an existing queue and its consumer. -* `queue_topology.xml`- Defines the message routing rules. -* `queue_publisher.xml` - Defines the relationship between a topic and its publisher. +- `queue_consumer.xml` - Defines the relationship between an existing queue and its consumer. +- `queue_topology.xml`- Defines the message routing rules. +- `queue_publisher.xml` - Defines the relationship between a topic and its publisher. The existing `queue.xml` file is deprecated. From 85b6f24032e37ab15a9e82a6eca614c6e8146abd Mon Sep 17 00:00:00 2001 From: Dnyaneshwar S Jambhulkar Date: Sat, 20 Sep 2025 17:10:10 +0530 Subject: [PATCH 07/43] AC-15629::Adobe Development Doc - Message Queues - ActiveMq (Artemis) updates --- .../development/components/message-queues/configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index 8351fd347..91bf7c49c 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -233,7 +233,7 @@ The `queue_publisher.xml` file defines which connection and exchange to use to p ### Example -**For RabbitMQ (AMQP):** +__For RabbitMQ (AMQP):__ ```xml @@ -246,7 +246,7 @@ The `queue_publisher.xml` file defines which connection and exchange to use to p ``` -**For ActiveMQ Artemis (STOMP):** +__For ActiveMQ Artemis (STOMP):__ ```xml From c06b77d87a64c0a42382e8b78c065447c15c323b Mon Sep 17 00:00:00 2001 From: "sandesh.as" Date: Thu, 4 Dec 2025 14:43:42 +0530 Subject: [PATCH 08/43] AC-16115: Adobe Development Doc - Message Queues - ActiveMq (Artemis) updates 2.4.5 --- .../message-queues/async-configuration.md | 2 +- .../message-queues/bulk-operations-example.md | 2 +- .../components/message-queues/migration.md | 64 +++++++++---------- 3 files changed, 34 insertions(+), 34 deletions(-) diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index 8ffebb42e..4ecd0fa87 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -78,4 +78,4 @@ As a result, if AMQP or STOMP is configured in deployment configuration of the q -ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.6 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. +ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.5 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. diff --git a/src/pages/development/components/message-queues/bulk-operations-example.md b/src/pages/development/components/message-queues/bulk-operations-example.md index c1f9f6674..f1aaccc04 100644 --- a/src/pages/development/components/message-queues/bulk-operations-example.md +++ b/src/pages/development/components/message-queues/bulk-operations-example.md @@ -370,4 +370,4 @@ As a result, if AMQP or STOMP is configured in the deployment configuration of t -ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.6 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. +ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.5 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. diff --git a/src/pages/development/components/message-queues/migration.md b/src/pages/development/components/message-queues/migration.md index 2b4dcc1f2..6df570610 100644 --- a/src/pages/development/components/message-queues/migration.md +++ b/src/pages/development/components/message-queues/migration.md @@ -8,28 +8,28 @@ keywords: # Migrate message queue configuration -## Migrate from 2.4.5 to 2.4.6, 2.4.7, 2.4.8, 2.4.9 +## Migrate from 2.4.4 to 2.4.5, 2.4.6, 2.4.7, 2.4.8, 2.4.9 -Adobe Commerce 2.4.9 introduced support for Apache ActiveMQ Artemis (STOMP) as an alternative message broker to RabbitMQ (AMQP). This feature was also backported to versions 2.4.6, 2.4.7, and 2.4.8. When upgrading from 2.4.5 (or earlier) to 2.4.6 or later versions, you have the option to continue using RabbitMQ or migrate to ActiveMQ Artemis. +Adobe Commerce 2.4.9 introduced support for Apache ActiveMQ Artemis (STOMP) as an alternative message broker to RabbitMQ (AMQP). This feature was also backported to versions 2.4.5, 2.4.6, 2.4.7, and 2.4.8. When upgrading from 2.4.4 (or earlier) to 2.4.5 or later versions, you have the option to continue using RabbitMQ or migrate to ActiveMQ Artemis. -### Key Changes in 2.4.6+ +### Key Changes in 2.4.5+ -- **ActiveMQ Artemis (STOMP) Support**: New message broker option alongside RabbitMQ (introduced in 2.4.9, backported to 2.4.6, 2.4.7, 2.4.8) +- **ActiveMQ Artemis (STOMP) Support**: New message broker option alongside RabbitMQ (introduced in 2.4.9, backported to 2.4.5, 2.4.6, 2.4.7, 2.4.8) - **Extended Dynamic Connection Detection**: Existing dynamic connection detection now supports STOMP in addition to AMQP - **Enhanced SSL Configuration**: Improved SSL options for both brokers - **Multiple Named Connections**: Enhanced support for configuring multiple broker connections ### Configuration File Changes -The following table shows the key differences between 2.4.5 and 2.4.6+ configurations: +The following table shows the key differences between 2.4.4 and 2.4.5+ configurations: -| Configuration Area | 2.4.5 | 2.4.6+ | +| Configuration Area | 2.4.4 | 2.4.5+ | | ------------------ | ----- | ------ | | `env.php` default_connection | Optional when single broker configured | Optional when single broker configured; required when multiple brokers (can be `'amqp'`, `'stomp'`, or `'db'`) | | `env.php` broker configuration | RabbitMQ (AMQP) only | RabbitMQ (AMQP) and/or ActiveMQ Artemis (STOMP) | -| `queue_consumer.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.6+) | +| `queue_consumer.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.5+) | | `queue_publisher.xml` connection element | Optional for AMQP, supports multiple connections | Optional for AMQP/STOMP, enhanced multiple connections | -| `queue_topology.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.6+) | +| `queue_topology.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.5+) | ### Update `env.php` Configuration @@ -48,7 +48,7 @@ The following table shows the key differences between 2.4.5 and 2.4.6+ configura ] ``` -**For ActiveMQ Artemis (STOMP) - Available in 2.4.6+ (introduced in 2.4.9, backported to 2.4.6-2.4.8):** +**For ActiveMQ Artemis (STOMP) - Available in 2.4.5+ (introduced in 2.4.9, backported to 2.4.5-2.4.8):** ```php 'queue' => [ @@ -62,7 +62,7 @@ The following table shows the key differences between 2.4.5 and 2.4.6+ configura ] ``` -**For Both Brokers - Available in 2.4.6+ (requires `default_connection`):** +**For Both Brokers - Available in 2.4.5+ (requires `default_connection`):** ```php 'queue' => [ @@ -95,30 +95,30 @@ The `connection` attribute in XML configuration files (`queue_consumer.xml`, `qu ### Update `queue_consumer.xml` Files -The first column in the following table lists parameters in 2.4.6+ `queue_consumer.xml` files. The second column shows the equivalent in 2.4.5. +The first column in the following table lists parameters in 2.4.5+ `queue_consumer.xml` files. The second column shows the equivalent in 2.4.4. -| 2.4.6+ Attribute | 2.4.5 Equivalent | Notes | +| 2.4.5+ Attribute | 2.4.4 Equivalent | Notes | | ----------------- | ----------------- | ----- | | `/name` | `/name` | No change | | `/queue` | `/queue` | No change | | `/handler` | `/handler` | No change | | `/consumerInstance` | `/consumerInstance` | No change | -| `/connection` | `/connection` | Optional in both versions, auto-detected from env.php. In 2.4.6+ also supports STOMP. Use explicitly to force specific broker selection. | +| `/connection` | `/connection` | Optional in both versions, auto-detected from env.php. In 2.4.5+ also supports STOMP. Use explicitly to force specific broker selection. | | `/maxMessages` | `/maxMessages` | No change | -**2.4.5 Example:** +**2.4.4 Example:** ```xml ``` -**2.4.6+ Example (Uses default broker from env.php):** +**2.4.5+ Example (Uses default broker from env.php):** ```xml ``` -**2.4.6+ Example (Explicitly specifies broker):** +**2.4.5+ Example (Explicitly specifies broker):** ```xml @@ -130,18 +130,18 @@ The first column in the following table lists parameters in 2.4.6+ `queue_consum ### Update `queue_publisher.xml` Files -The first column in the following table lists parameters in 2.4.6+ `queue_publisher.xml` files. The second column shows the equivalent in 2.4.5. +The first column in the following table lists parameters in 2.4.5+ `queue_publisher.xml` files. The second column shows the equivalent in 2.4.4. -| 2.4.6+ Attribute | 2.4.5 Equivalent | Notes | +| 2.4.5+ Attribute | 2.4.4 Equivalent | Notes | | ----------------- | ----------------- | ----- | | `/topic` | `/topic` | No change | -| `/queue` | Not available | Available in 2.4.6+ for ActiveMQ Artemis | +| `/queue` | Not available | Available in 2.4.5+ for ActiveMQ Artemis | | `/disabled` | `/disabled` | No change | -| `//name` | `//name` | Can specify `stomp` for ActiveMQ (2.4.6+) | +| `//name` | `//name` | Can specify `stomp` for ActiveMQ (2.4.5+) | | `//exchange` | `//exchange` | Not used with STOMP | -| `//disabled` | `//disabled` | Enhanced in 2.4.6+ for multiple connections | +| `//disabled` | `//disabled` | Enhanced in 2.4.5+ for multiple connections | -**2.4.5 Example (RabbitMQ only):** +**2.4.4 Example (RabbitMQ only):** ```xml @@ -149,7 +149,7 @@ The first column in the following table lists parameters in 2.4.6+ `queue_publis ``` -**2.4.6+ Example (RabbitMQ):** +**2.4.5+ Example (RabbitMQ):** ```xml @@ -158,7 +158,7 @@ The first column in the following table lists parameters in 2.4.6+ `queue_publis ``` -**2.4.6+ Example (ActiveMQ Artemis):** +**2.4.5+ Example (ActiveMQ Artemis):** ```xml @@ -169,13 +169,13 @@ The first column in the following table lists parameters in 2.4.6+ `queue_publis ### Update `queue_topology.xml` Files -The first column in the following table lists parameters in 2.4.6+ `queue_topology.xml` files. The second column shows the equivalent in 2.4.5. +The first column in the following table lists parameters in 2.4.5+ `queue_topology.xml` files. The second column shows the equivalent in 2.4.4. -| 2.4.6+ Attribute | 2.4.5 Equivalent | Notes | +| 2.4.5+ Attribute | 2.4.4 Equivalent | Notes | | ----------------- | ----------------- | ----- | | `/name` | `/name` | No change | | `/type` | `/type` | No change | -| `/connection` | `/connection` | Optional in both versions, auto-detected from env.php. In 2.4.6+ also supports STOMP. Use explicitly to force specific broker selection. | +| `/connection` | `/connection` | Optional in both versions, auto-detected from env.php. In 2.4.5+ also supports STOMP. Use explicitly to force specific broker selection. | | `/durable` | `/durable` | No change | | `/autoDelete` | `/autoDelete` | No change | | `//id` | `//id` | No change | @@ -183,7 +183,7 @@ The first column in the following table lists parameters in 2.4.6+ `queue_topolo | `//destinationType` | `//destinationType` | No change | | `//destination` | `//destination` | No change | -**2.4.5 Example:** +**2.4.4 Example:** ```xml @@ -191,7 +191,7 @@ The first column in the following table lists parameters in 2.4.6+ `queue_topolo ``` -**2.4.6+ Example (Uses default broker from env.php):** +**2.4.5+ Example (Uses default broker from env.php):** ```xml @@ -199,7 +199,7 @@ The first column in the following table lists parameters in 2.4.6+ `queue_topolo ``` -**2.4.6+ Example (Explicitly specifies broker):** +**2.4.5+ Example (Explicitly specifies broker):** ```xml @@ -215,11 +215,11 @@ The first column in the following table lists parameters in 2.4.6+ `queue_topolo -Connection detection has always been dynamic based on your `env.php` configuration. If AMQP is configured in deployment configuration, the AMQP connection is used automatically. In 2.4.6+, this same dynamic detection was extended to support STOMP connections. This allows you to omit connection declarations in XML configuration files. +Connection detection has always been dynamic based on your `env.php` configuration. If AMQP is configured in deployment configuration, the AMQP connection is used automatically. In 2.4.5+, this same dynamic detection was extended to support STOMP connections. This allows you to omit connection declarations in XML configuration files. -ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.9 and backported to versions 2.4.6, 2.4.7, and 2.4.8. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. +ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.9 and backported to versions 2.4.5, 2.4.6, 2.4.7, and 2.4.8. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. ## Migrate from 2.1 to 2.2 From e51f9054127e8ce49acaa85a94b752b189699f66 Mon Sep 17 00:00:00 2001 From: "sandesh.as" Date: Thu, 11 Dec 2025 17:33:06 +0530 Subject: [PATCH 09/43] AC-16115: Adobe Commerce Doc - Migration from RabbitMQ to ActiveMQ updates 2.4.5 --- .../components/message-queues/migration.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/src/pages/development/components/message-queues/migration.md b/src/pages/development/components/message-queues/migration.md index 6df570610..48d71ad4d 100644 --- a/src/pages/development/components/message-queues/migration.md +++ b/src/pages/development/components/message-queues/migration.md @@ -8,13 +8,12 @@ keywords: # Migrate message queue configuration -## Migrate from 2.4.4 to 2.4.5, 2.4.6, 2.4.7, 2.4.8, 2.4.9 - -Adobe Commerce 2.4.9 introduced support for Apache ActiveMQ Artemis (STOMP) as an alternative message broker to RabbitMQ (AMQP). This feature was also backported to versions 2.4.5, 2.4.6, 2.4.7, and 2.4.8. When upgrading from 2.4.4 (or earlier) to 2.4.5 or later versions, you have the option to continue using RabbitMQ or migrate to ActiveMQ Artemis. +## Migrate from 2.4.4 to 2.4.5, 2.4.6, 2.4.7, 2.4.8 +Adobe Commerce introduced support for Apache ActiveMQ Artemis (STOMP) as an alternative message broker to RabbitMQ (AMQP), and this feature was backported to versions 2.4.5, 2.4.6, 2.4.7, and 2.4.8. When upgrading from 2.4.4 (or earlier) to 2.4.5 or later, you can continue using RabbitMQ or choose to migrate to ActiveMQ Artemis. ### Key Changes in 2.4.5+ -- **ActiveMQ Artemis (STOMP) Support**: New message broker option alongside RabbitMQ (introduced in 2.4.9, backported to 2.4.5, 2.4.6, 2.4.7, 2.4.8) +- **ActiveMQ Artemis (STOMP) Support**: New message broker option alongside RabbitMQ (backported to 2.4.5, 2.4.6, 2.4.7, 2.4.8) - **Extended Dynamic Connection Detection**: Existing dynamic connection detection now supports STOMP in addition to AMQP - **Enhanced SSL Configuration**: Improved SSL options for both brokers - **Multiple Named Connections**: Enhanced support for configuring multiple broker connections @@ -48,7 +47,7 @@ The following table shows the key differences between 2.4.4 and 2.4.5+ configura ] ``` -**For ActiveMQ Artemis (STOMP) - Available in 2.4.5+ (introduced in 2.4.9, backported to 2.4.5-2.4.8):** +**For ActiveMQ Artemis (STOMP) - Available in 2.4.5+ (backported to 2.4.5-2.4.8):** ```php 'queue' => [ @@ -219,8 +218,7 @@ Connection detection has always been dynamic based on your `env.php` configurati -ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.9 and backported to versions 2.4.5, 2.4.6, 2.4.7, and 2.4.8. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. - +ActiveMQ Artemis (STOMP) was backported to Adobe Commerce versions 2.4.5, 2.4.6, 2.4.7, and 2.4.8. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. ## Migrate from 2.1 to 2.2 To upgrade the message queues for Adobe Commerce or Magento Open Source 2.1, you must create the following files in the `/etc` directory for each module that will use the message queue framework. From c5e6d6c4fd99989e5bbc359603a8a86d805c22fd Mon Sep 17 00:00:00 2001 From: "sandesh.as" Date: Thu, 11 Dec 2025 17:37:05 +0530 Subject: [PATCH 10/43] AC-16115: Adobe Commerce Doc - Migration from RabbitMQ to ActiveMQ updates 2.4.5 --- .../development/components/message-queues/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index 91bf7c49c..b0f09540d 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -285,7 +285,7 @@ You cannot enable more than one `publisher` for each `topic`. -ActiveMQ Artemis (STOMP) support was introduced in Adobe Commerce 2.4.6 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. +ActiveMQ Artemis (STOMP) support was introduced in Adobe Commerce 2.4.5 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. ## Updating `queue.xml` From ef052c5ed1b2412dd0a3fa25d9ea68a9664db191 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Tue, 20 Jan 2026 13:56:56 -0600 Subject: [PATCH 11/43] Update src/pages/development/components/message-queues/bulk-operations-example.md --- .../components/message-queues/bulk-operations-example.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/bulk-operations-example.md b/src/pages/development/components/message-queues/bulk-operations-example.md index f1aaccc04..0995fbe02 100644 --- a/src/pages/development/components/message-queues/bulk-operations-example.md +++ b/src/pages/development/components/message-queues/bulk-operations-example.md @@ -347,7 +347,9 @@ The `queue_publisher.xml` file defines the exchange where a topic is published. ``` -**Note**: For ActiveMQ Artemis, the `` element is not required as the connection type is determined from `env.php`. When the topic name and queue name are different, you must specify the `queue` attribute in the `` element. +>[!NOTE] +> +>For ActiveMQ Artemis, the `` element is not required as the connection type is determined from `env.php`. When the topic name and queue name are different, you must specify the `queue` attribute in the `` element. ### Create `queue_topology.xml` From 2e15718101f7e04f8643e9975bd54a76528090c2 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Tue, 20 Jan 2026 13:57:06 -0600 Subject: [PATCH 12/43] Update src/pages/development/components/message-queues/configuration.md --- .../development/components/message-queues/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index b0f09540d..48b443a68 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -269,7 +269,7 @@ __For ActiveMQ Artemis (STOMP):__ #### `connection` element -The `connection` element is a subnode of the `publisher` element. There must not be more than one enabled active connection to a publisher defined at a time. If you omit the `connection` element, connection will be defined dynamically based on deployment configuration of message queue in `env.php` and exchange `magento` will be used. If AMQP or STOMP is configured in deployment configuration, the respective connection is used. Otherwise, db connection is used. +The `connection` element is a subnode of the `publisher` element. There must not be more than one enabled active connection to a publisher defined at a time. If you omit the `connection` element, the connection is defined dynamically based on deployment configuration of message queue in `env.php` and `magento` is used as the exchange. If AMQP or STOMP is configured in the deployment configuration, the respective connection is used. Otherwise, the `db` connection is used. | Attribute | Description | | -------------------- | ----------- | From 14b282d214187b4253d656e7cbf372c5050f285e Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Tue, 20 Jan 2026 13:58:05 -0600 Subject: [PATCH 13/43] Update async-configuration.md --- .../components/message-queues/async-configuration.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index 4ecd0fa87..d3206471a 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -69,8 +69,6 @@ The message queue topology configuration links all auto-generated topic names wi ``` -The connection type is automatically determined from your `env.php` configuration. - Message queues connection is defined dynamically based on deployment configuration in `env.php`. If AMQP or STOMP is configured in deployment configuration of the queue, the respective connection is used. Otherwise, db connection is used. From 5c0c71288a018ee9ad11b72170b990e3ab3b931a Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Fri, 30 Jan 2026 05:10:48 -0600 Subject: [PATCH 14/43] Update src/pages/development/components/message-queues/async-configuration.md --- .../components/message-queues/async-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index d3206471a..9b997987c 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -71,7 +71,7 @@ The message queue topology configuration links all auto-generated topic names wi -Message queues connection is defined dynamically based on deployment configuration in `env.php`. If AMQP or STOMP is configured in deployment configuration of the queue, the respective connection is used. Otherwise, db connection is used. +The message queues connection is defined dynamically based on deployment configuration in `env.php`. If `AMQP` or `STOMP` is configured in the deployment configuration for the queue, the respective connection is used. Otherwise, the `db` connection is used. As a result, if AMQP or STOMP is configured in deployment configuration of the queue, connection declaration can be omitted in [message queue configuration files](./configuration.md): `queue_customer.xml`, `queue_publisher.xml`, `queue_topology.xml`. From 3ea7bbe1ba2024b51cee4fae916149ad57c7e426 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Fri, 30 Jan 2026 05:13:05 -0600 Subject: [PATCH 15/43] Update src/pages/development/components/message-queues/configuration.md --- .../development/components/message-queues/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index 48b443a68..a4bea1824 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -273,7 +273,7 @@ The `connection` element is a subnode of the `publisher` element. There must not | Attribute | Description | | -------------------- | ----------- | -| name | Connection name is defined dynamically based on deployment configuration of message queue in `env.php`. If you still want to specify connection type for publisher, keep in mind that for AMQP connections, the connection name must match the `connection` attribute in the `queue_topology.xml` file. For STOMP connections, use `stomp`. Otherwise, the connection name must be `db`. | +| name | The connection name is defined dynamically based on the deployment configuration for the message queue in `env.php`. If you still want to specify connection type for publisher, keep in mind that for AMQP connections, the connection name must match the `connection` attribute in the `queue_topology.xml` file. For STOMP connections, use `stomp`. Otherwise, the connection name must be `db`. | | exchange | The name of the exchange to publish to. The default system exchange name is `magento`. | | disabled | Determines whether this queue is disabled. The default value is `false`. | From 6afb0d4d692916f6b470e3130fd7f144443f045b Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Fri, 30 Jan 2026 05:13:55 -0600 Subject: [PATCH 16/43] Update src/pages/development/components/message-queues/async-configuration.md --- .../components/message-queues/async-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index 9b997987c..5c5d857fe 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -46,7 +46,7 @@ The `queue_publisher.xml` file is generated by the `\Magento\WebapiAsync\Code\Ge The sort order is set to 0 and allows developers to change some aspects of the generated configuration in configuration readers such as `queue_publisher.xml` and `env.php`. -`\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of all REST API routes which can be executed asynchronously. Then it defines the connection name as `amqp` (or `stomp` for ActiveMQ Artemis) and the exchange as `magento` for each generated topic name. +`\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of all REST API routes which can be executed asynchronously. Then, it defines the connection name as `amqp` (or `stomp` for ActiveMQ Artemis) and the exchange as `magento` for each generated topic name. ## queue_consumer.xml From 42cfdc00f8c29efb7c702c4fade42a581a7cb5b2 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Fri, 30 Jan 2026 05:14:43 -0600 Subject: [PATCH 17/43] Update src/pages/development/components/message-queues/async-configuration.md --- .../components/message-queues/async-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index 5c5d857fe..1c3f501f6 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -71,7 +71,7 @@ The message queue topology configuration links all auto-generated topic names wi -The message queues connection is defined dynamically based on deployment configuration in `env.php`. If `AMQP` or `STOMP` is configured in the deployment configuration for the queue, the respective connection is used. Otherwise, the `db` connection is used. +The message queues connection is defined dynamically based on deployment configuration in `env.php`. If AMQP or STOMP is configured in the deployment configuration for the queue, the respective connection is used. Otherwise, the database connection is used. As a result, if AMQP or STOMP is configured in deployment configuration of the queue, connection declaration can be omitted in [message queue configuration files](./configuration.md): `queue_customer.xml`, `queue_publisher.xml`, `queue_topology.xml`. From 90631805baf06d28c6189f79f323f599c33532f4 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Fri, 30 Jan 2026 05:29:21 -0600 Subject: [PATCH 18/43] Update bulk-operations-example.md Editorial updates --- .../message-queues/bulk-operations-example.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/src/pages/development/components/message-queues/bulk-operations-example.md b/src/pages/development/components/message-queues/bulk-operations-example.md index 0995fbe02..5b775e34f 100644 --- a/src/pages/development/components/message-queues/bulk-operations-example.md +++ b/src/pages/development/components/message-queues/bulk-operations-example.md @@ -15,9 +15,13 @@ This document describes how bulk operations can be implemented. There are three ## Create a publisher -A publisher's duties include scheduling a bulk operation. It must generate a `bulkUuid` for each operation, send each operation to the message queue, and report on the status of each operations. +A publisher is responsible for scheduling a bulk operation that performs the following tasks: -The following code sample shows how these duties can be completed. +* Generate a bulkUuid for each operation +* Publish each operation to the message queue +* Track and report the status of each operation + +The following example defines a publisher that implements these responsibilities. ```php ``` -The connection type (AMQP or STOMP) is determined automatically based on your `env.php` configuration. +The connection type (AMQP or STOMP) is determined automatically based on the configuration in the `env.php` file. ### Create `queue_publisher.xml` @@ -349,11 +353,11 @@ The `queue_publisher.xml` file defines the exchange where a topic is published. >[!NOTE] > ->For ActiveMQ Artemis, the `` element is not required as the connection type is determined from `env.php`. When the topic name and queue name are different, you must specify the `queue` attribute in the `` element. +>For ActiveMQ Artemis, the `` element is not required as the connection type is determined by the configuration in the `env.php` file. When the topic name and queue name are different, you must specify the `queue` attribute in the `` element. ### Create `queue_topology.xml` -The `queue_topology.xml` file defines the message routing rules and declares queues and exchanges. Create this file with the following contents: +The `queue_topology.xml` file defines the message routing rules and declares queues and exchanges. Create this file with the following content: ```xml @@ -363,12 +367,9 @@ The `queue_topology.xml` file defines the message routing rules and declares que ``` -The connection type is automatically determined from your `env.php` configuration. - -Message queue connections are defined dynamically, based on the deployment configuration in the `env.php` file. If AMQP or STOMP is configured in the deployment configuration of the queue, the respective connection is used. Otherwise, database connections are used. -As a result, if AMQP or STOMP is configured in the deployment configuration of the queue, you can omit connection declarations in the `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml` [message queue configuration files](./configuration.md). +Message queue connections are resolved dynamically from the deployment configuration in the `env.php` file. If the queue is configured to use AMQP or STOMP, the corresponding connection is applied. Otherwise, the database connection is used. Therefore, when AMQP or STOMP is specified in the deployment configuration, you can omit connection declarations from `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml`files (see the ./configuration.md). From e67e0af65af7e57b1a5f7de575fe629dd2f8b416 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Fri, 30 Jan 2026 05:40:32 -0600 Subject: [PATCH 19/43] Update src/pages/development/components/message-queues/configuration.md --- .../development/components/message-queues/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index a4bea1824..befd3e0e8 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -269,7 +269,7 @@ __For ActiveMQ Artemis (STOMP):__ #### `connection` element -The `connection` element is a subnode of the `publisher` element. There must not be more than one enabled active connection to a publisher defined at a time. If you omit the `connection` element, the connection is defined dynamically based on deployment configuration of message queue in `env.php` and `magento` is used as the exchange. If AMQP or STOMP is configured in the deployment configuration, the respective connection is used. Otherwise, the `db` connection is used. +The `connection` element is a subnode of the `publisher` element, and only one enabled active connection can be defined for a publisher at any given time. If you omit the `connection` element, the connection is resolved dynamically from the message queue deployment configuration in `env.php`, and `magento` is used as the exchange. If AMQP or STOMP is configured, the corresponding connection is used. Otherwise, the db connection is used. | Attribute | Description | | -------------------- | ----------- | From 22a5dbd5a365eb0052683a4df8707a44315893fc Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Fri, 30 Jan 2026 05:44:40 -0600 Subject: [PATCH 20/43] Update src/pages/development/components/message-queues/configuration.md --- .../development/components/message-queues/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index befd3e0e8..79acf1302 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -273,7 +273,7 @@ The `connection` element is a subnode of the `publisher` element, and only one e | Attribute | Description | | -------------------- | ----------- | -| name | The connection name is defined dynamically based on the deployment configuration for the message queue in `env.php`. If you still want to specify connection type for publisher, keep in mind that for AMQP connections, the connection name must match the `connection` attribute in the `queue_topology.xml` file. For STOMP connections, use `stomp`. Otherwise, the connection name must be `db`. | +| name | The connection name is resolved dynamically from the message queue deployment configuration in `env.php`. If you choose to explicitly define a connection for a publisher, note the following requirements: For AMQP connections, the connection name must match the `connection` attribute defined in the `queue_topology.xml` file. For STOMP connections, the connection name must be `stomp`. If neither AMQP or STOMP is configured, the connection name must be `db`. | | exchange | The name of the exchange to publish to. The default system exchange name is `magento`. | | disabled | Determines whether this queue is disabled. The default value is `false`. | From bb501c776a3be6fd42b736c6c7c303a4bbbcd165 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Fri, 30 Jan 2026 05:49:13 -0600 Subject: [PATCH 21/43] Update src/pages/development/components/message-queues/configuration.md --- .../development/components/message-queues/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index 79acf1302..54090679f 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -94,7 +94,7 @@ The `queue_consumer.xml` file contains one or more `consumer` elements: | queue (required) | Defines the queue name to send the message to. | | handler | Specifies the class and method that processes the message. The value must be specified in the format `\Module\::`.| | consumerInstance | The class name that consumes the message. Default value: `Magento\Framework\MessageQueue\Consumer`. | -| connection | Connection is defined dynamically based on deployment configuration of message queue in `env.php`. If AMQP or STOMP is configured in deployment configuration, the respective connection is used. Otherwise, db connection is used. If you still want to specify connection type for consumer, keep in mind that for AMQP connections, the connection name must match the `connection` attribute in the `queue_topology.xml` file. For STOMP connections, use `stomp`. Otherwise, the connection name must be `db`. | +| connection | The connection is resolved dynamically based on the message queue deployment configuration in `env.php`. If the queue is configured to use AMQP or STOMP, the corresponding connection is used. Otherwise, db connection is used. If you choose to explicitly define a connection for a consumer, note the following requirements: For AMQP connections, the connection name must match the value of the `connection` attribute in the `queue_topology.xml` file. For STOMP connections, use `stomp` as the connection name. Otherwise, the connection name must be `db`. | | maxMessages | Specifies the maximum number of messages to consume.| | maxIdleTime | Defines the maximum waiting time in seconds for a new message from the queue. If no message was handled within this period of time, the consumer exits. Default value: `null`| | sleep | Specifies time in seconds to sleep before checking if a new message is available in the queue. Default value is `null` which equals to 1 second.| From af98cd0dd968281d0b4a480ddfb5a0da5706a2eb Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Fri, 30 Jan 2026 05:49:52 -0600 Subject: [PATCH 22/43] Update src/pages/development/components/message-queues/migration.md --- src/pages/development/components/message-queues/migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/migration.md b/src/pages/development/components/message-queues/migration.md index 48d71ad4d..253ad16e0 100644 --- a/src/pages/development/components/message-queues/migration.md +++ b/src/pages/development/components/message-queues/migration.md @@ -225,7 +225,7 @@ To upgrade the message queues for Adobe Commerce or Magento Open Source 2.1, you - `queue_consumer.xml` - Defines the relationship between an existing queue and its consumer. - `queue_topology.xml`- Defines the message routing rules and declares queues and exchanges. -- `queue_publisher.xml` - Defines the exchange where a topic is published. +- `queue_publisher.xml` - Defines the exchange where a topic is published. The existing `queue.xml` file is deprecated. From 2d7912141ceb4dc28b29536d033b84855c77804a Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Fri, 30 Jan 2026 05:52:34 -0600 Subject: [PATCH 23/43] Update src/pages/development/components/message-queues/index.md --- src/pages/development/components/message-queues/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/index.md b/src/pages/development/components/message-queues/index.md index ed9b11831..ffb1895b8 100644 --- a/src/pages/development/components/message-queues/index.md +++ b/src/pages/development/components/message-queues/index.md @@ -12,7 +12,7 @@ Message queues provide an asynchronous communications mechanism in which the sen In Adobe Commerce and Magento Open Source, the Message Queue Framework (MQF) is a fully-functional system that allows a module to publish messages to queues. It also creates consumers to receive them asynchronously. The MQF supports multiple messaging brokers: - **[RabbitMQ](http://www.rabbitmq.com)** - The primary messaging broker, which provides a scalable platform for sending and receiving messages. It includes a mechanism for storing undelivered messages and is based on the Advanced Message Queuing Protocol (AMQP) 0.9.1 specification. -- **[Apache ActiveMQ Artemis](https://activemq.apache.org/components/artemis/)** - An alternative messaging broker that uses the STOMP (Simple Text Oriented Messaging Protocol) for reliable and scalable messaging, offering flexibility for STOMP-based integrations. +- **[Apache ActiveMQ Artemis](https://activemq.apache.org/components/artemis/)** - An alternative messaging broker that uses STOMP (Simple Text Oriented Messaging Protocol) for reliable and scalable messaging, offering flexibility for STOMP-based integrations. A basic message queue system can also be set up without using external message brokers. In this system, a MySQL adapter stores messages in the database. Three database tables (`queue`, `queue_message`, and `queue_message_status`) manage the message queue workload. Cron jobs ensure the consumers are able to receive messages. This solution is not very scalable. External message brokers like RabbitMQ or ActiveMQ Artemis should be used whenever possible. From 5c79a3db9ef3ec24abc29d4b213e50510e92f2af Mon Sep 17 00:00:00 2001 From: "sandesh.as" Date: Mon, 2 Feb 2026 12:33:03 +0530 Subject: [PATCH 24/43] Update src/pages/development/components/message-queues/bulk-operations-example.md --- .../components/message-queues/bulk-operations-example.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/bulk-operations-example.md b/src/pages/development/components/message-queues/bulk-operations-example.md index 5b775e34f..d1773f86d 100644 --- a/src/pages/development/components/message-queues/bulk-operations-example.md +++ b/src/pages/development/components/message-queues/bulk-operations-example.md @@ -353,7 +353,7 @@ The `queue_publisher.xml` file defines the exchange where a topic is published. >[!NOTE] > ->For ActiveMQ Artemis, the `` element is not required as the connection type is determined by the configuration in the `env.php` file. When the topic name and queue name are different, you must specify the `queue` attribute in the `` element. +>For ActiveMQ Artemis, the `` element is not required because the connection type is determined by the configuration in the `env.php` file. If the topic name and queue name differ, you must specify the `queue` attribute in the `` element. ### Create `queue_topology.xml` From 921d4dbb64df2f6a11d82a5f300c63eb4ce1c430 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 09:48:01 -0600 Subject: [PATCH 25/43] Update src/pages/development/components/message-queues/async-configuration.md --- .../components/message-queues/async-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index 1c3f501f6..71fa584b9 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -71,8 +71,8 @@ The message queue topology configuration links all auto-generated topic names wi -The message queues connection is defined dynamically based on deployment configuration in `env.php`. If AMQP or STOMP is configured in the deployment configuration for the queue, the respective connection is used. Otherwise, the database connection is used. -As a result, if AMQP or STOMP is configured in deployment configuration of the queue, connection declaration can be omitted in [message queue configuration files](./configuration.md): `queue_customer.xml`, `queue_publisher.xml`, `queue_topology.xml`. +```suggestion +The message queues connection is defined dynamically based on deployment configuration in `env.php`. If AMQP or STOMP is configured in the deployment configuration for the queue, the respective connection is used. Otherwise, the database connection is used. Because the connection is resolved using the configuration, explicit declarations are unnecessary in the [message queue configuration files](./configuration.md): `queue_customer.xml`, `queue_publisher.xml`, `queue_topology.xml`. From f3e4f84f192ab67901a70cea524cb45c49e57b25 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 09:48:42 -0600 Subject: [PATCH 26/43] Update async-configuration.md --- .../development/components/message-queues/async-configuration.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index 71fa584b9..a52b1dd68 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -71,7 +71,6 @@ The message queue topology configuration links all auto-generated topic names wi -```suggestion The message queues connection is defined dynamically based on deployment configuration in `env.php`. If AMQP or STOMP is configured in the deployment configuration for the queue, the respective connection is used. Otherwise, the database connection is used. Because the connection is resolved using the configuration, explicit declarations are unnecessary in the [message queue configuration files](./configuration.md): `queue_customer.xml`, `queue_publisher.xml`, `queue_topology.xml`. From 2427f039adc9625384e672bf0dd03588cae7794a Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 09:54:59 -0600 Subject: [PATCH 27/43] Update src/pages/development/components/message-queues/migration.md --- src/pages/development/components/message-queues/migration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pages/development/components/message-queues/migration.md b/src/pages/development/components/message-queues/migration.md index 253ad16e0..445c6e210 100644 --- a/src/pages/development/components/message-queues/migration.md +++ b/src/pages/development/components/message-queues/migration.md @@ -11,6 +11,7 @@ keywords: ## Migrate from 2.4.4 to 2.4.5, 2.4.6, 2.4.7, 2.4.8 Adobe Commerce introduced support for Apache ActiveMQ Artemis (STOMP) as an alternative message broker to RabbitMQ (AMQP), and this feature was backported to versions 2.4.5, 2.4.6, 2.4.7, and 2.4.8. When upgrading from 2.4.4 (or earlier) to 2.4.5 or later, you can continue using RabbitMQ or choose to migrate to ActiveMQ Artemis. + ### Key Changes in 2.4.5+ - **ActiveMQ Artemis (STOMP) Support**: New message broker option alongside RabbitMQ (backported to 2.4.5, 2.4.6, 2.4.7, 2.4.8) From d71eed15f7847f7049696dfb956feef91d2cf4d6 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 18:07:32 -0600 Subject: [PATCH 28/43] Enhance documentation on async configuration details Clarified the explanation of the asynchronous configuration process, emphasizing the dynamic nature of the connection and the association of topic names with the exchange. --- .../components/message-queues/async-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index a52b1dd68..72fca15da 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -46,7 +46,7 @@ The `queue_publisher.xml` file is generated by the `\Magento\WebapiAsync\Code\Ge The sort order is set to 0 and allows developers to change some aspects of the generated configuration in configuration readers such as `queue_publisher.xml` and `env.php`. -`\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of all REST API routes which can be executed asynchronously. Then, it defines the connection name as `amqp` (or `stomp` for ActiveMQ Artemis) and the exchange as `magento` for each generated topic name. +`\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of REST API routes that can be executed asynchronously. It generates topic names and associates them with the `magento` exchange. The connection is not hard-coded in the generated configuration—the runtime connection (AMQP or STOMP for Active MQ Artemis) is determined by the deployment configuration in the `env.php` file. ## queue_consumer.xml From 5bc51edd5369d5d79c5346bfd92b17f0a4857e73 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 18:32:27 -0600 Subject: [PATCH 29/43] Update src/pages/development/components/message-queues/async-configuration.md --- .../components/message-queues/async-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index 72fca15da..9a9d10d48 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -46,7 +46,7 @@ The `queue_publisher.xml` file is generated by the `\Magento\WebapiAsync\Code\Ge The sort order is set to 0 and allows developers to change some aspects of the generated configuration in configuration readers such as `queue_publisher.xml` and `env.php`. -`\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of REST API routes that can be executed asynchronously. It generates topic names and associates them with the `magento` exchange. The connection is not hard-coded in the generated configuration—the runtime connection (AMQP or STOMP for Active MQ Artemis) is determined by the deployment configuration in the `env.php` file. +`\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of REST API routes that can be executed asynchronously. Then, it dynamically resolves the connection name (`db` (default), `ampqp` or `stomp` for ActiveMQ Artemis) based on the `env.php` deployment configuration and defines the exchange as `magento` for each generated topic name. ## queue_consumer.xml From bf852a4af759a9bcf38814fb5fc5f0db42379ce0 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 18:46:21 -0600 Subject: [PATCH 30/43] Fix XML formatting and update notes in documentation Fix admonition format and add correct markdown link syntax for ./configure.md reference. --- .../message-queues/bulk-operations-example.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/pages/development/components/message-queues/bulk-operations-example.md b/src/pages/development/components/message-queues/bulk-operations-example.md index d1773f86d..b9af8d7b7 100644 --- a/src/pages/development/components/message-queues/bulk-operations-example.md +++ b/src/pages/development/components/message-queues/bulk-operations-example.md @@ -338,7 +338,7 @@ The `queue_publisher.xml` file defines the exchange where a topic is published. ```xml - + /> ``` @@ -351,9 +351,9 @@ The `queue_publisher.xml` file defines the exchange where a topic is published. ``` ->[!NOTE] -> ->For ActiveMQ Artemis, the `` element is not required because the connection type is determined by the configuration in the `env.php` file. If the topic name and queue name differ, you must specify the `queue` attribute in the `` element. + + +For ActiveMQ Artemis, the `` element is not required because the connection type is determined by the configuration in the `env.php` file. If the topic name and queue name differ, you must specify the `queue` attribute in the `` element. ### Create `queue_topology.xml` @@ -369,7 +369,7 @@ The `queue_topology.xml` file defines the message routing rules and declares que -Message queue connections are resolved dynamically from the deployment configuration in the `env.php` file. If the queue is configured to use AMQP or STOMP, the corresponding connection is applied. Otherwise, the database connection is used. Therefore, when AMQP or STOMP is specified in the deployment configuration, you can omit connection declarations from `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml`files (see the ./configuration.md). +Message queue connections are resolved dynamically from the deployment configuration in the `env.php` file. If the queue is configured to use AMQP or STOMP, the corresponding connection is applied. Otherwise, the database connection is used. Therefore, when AMQP or STOMP is specified in the deployment configuration, you can omit connection declarations from `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml` files.(See [Message queue configuration files](./configuration.md). From 14af8f001ba35def98de4505a674de0de90ff7d8 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 18:48:39 -0600 Subject: [PATCH 31/43] Update src/pages/development/components/message-queues/bulk-operations-example.md --- .../components/message-queues/bulk-operations-example.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/bulk-operations-example.md b/src/pages/development/components/message-queues/bulk-operations-example.md index b9af8d7b7..6ff437da2 100644 --- a/src/pages/development/components/message-queues/bulk-operations-example.md +++ b/src/pages/development/components/message-queues/bulk-operations-example.md @@ -327,7 +327,7 @@ The `queue_consumer.xml` file defines the relationship between a queue and its c ``` -The connection type (AMQP or STOMP) is determined automatically based on the configuration in the `env.php` file. +The connection name (AMQP or STOMP) is determined automatically based on the configuration in the `env.php` file. ### Create `queue_publisher.xml` From bf3c4376386401132d334ea8474c4a513ef007b7 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 20:40:29 -0600 Subject: [PATCH 32/43] Update message queue configuration documentation Improved organization and reduced repetitive information to make topic easier to read and maintain. - Moved handler processing to separate section linked from the `handler` element section. - Moved consume spawning behavior to a separate section linked from the `consumer` element section - Create a separate shared section for Connection resolution that provides information about specifying connection type in deployment configuration or explicitly with info about possible connection types and how they work. Linked this section from the `connection` name parameters so information is not repeated multiple times. --- .../message-queues/`consumer` element | 336 ++++++++++++++++++ .../message-queues/configuration.md | 292 --------------- 2 files changed, 336 insertions(+), 292 deletions(-) create mode 100644 src/pages/development/components/message-queues/`consumer` element delete mode 100644 src/pages/development/components/message-queues/configuration.md diff --git a/src/pages/development/components/message-queues/`consumer` element b/src/pages/development/components/message-queues/`consumer` element new file mode 100644 index 000000000..0e48085e3 --- /dev/null +++ b/src/pages/development/components/message-queues/`consumer` element @@ -0,0 +1,336 @@ +--- +title: Configure Message Queues | Commerce PHP Extensions +description: Add message queue functionality to Adobe Commerce and Magento Open Source extensions. +keywords: + - Configuration + - Extensions +--- + +# Configure message queues + +The message queue topology is an Adobe Commerce and Magento Open Source feature that can be added to existing modules. + +Configuring the message queue topology involves creating and modifying the following configuration files in the `/etc` directory: + +* [`communication.xml`](#communicationxml)—Defines aspects of the message queue system that all communication types have in common. +* [`queue_consumer.xml`](#queue_consumerxml)—Defines the relationship between an existing queue and its consumer. +* [`queue_topology.xml`](#queue_topologyxml)—Defines the message routing rules and declares queues and exchanges. +* [`queue_publisher.xml`](#queue_publisherxml)—Defines the exchange where a topic is published. + + + +If you are upgrading from Adobe Commerce or Magento Open Source 2.0 or 2.1, see [Migrate message queue configuration](migration.md). + +## Use cases + +Depending on your use case, you can create and configure `communication.xml` along with one or more of the following files: + +* **Publish messages to an existing queue created by a third-party system**—Configure the `queue_publisher.xml` file only. + +* **Consume messages from an existing queue**—Configure the `queue_consumer.xml` file only. + +* **Define a local queue and consume messages published by a third-party system**—Configure both the `queue_topology.xml` and `queue_consumer.xml` files. + +## `communication.xml` + +The `/etc/communication.xml` file defines aspects of the message queue system that all communication types have in common. Adobe Commerce supports AMQP, STOMP, and database connections. + +### Example + +The following sample defines two synchronous topics. The first topic is for RPC calls. The second uses a custom service interface. + +```xml + + + + + + + + + +``` + +#### `topic` element + +Topic configuration is flexible in that you can switch the transport layer for topics at deployment time. These values can be overwritten in the `env.php` file. + +The `name` parameter is required. The topic definition must include either a `request` or a `schema`. Use `schema` if you want to implement a custom service interface. Otherwise, specify `request`. If `request` is specified, then also specify `response` if the topic is synchronous. + +| Parameter | Description | +| --- | --- | +| `name` | A unique string identifier for the topic. Use a series of period-separated strings, with the leftmost being most general and each subsequent string narrowing the scope. For example, `cat.white.feed` and `dog.retriever.walk`. Wildcards are not supported in `communication.xml`. +| `request` | Specifies the data type of the topic. | +| `response` | Specifies the format of the response. This parameter is required if you are defining a synchronous topic. Omit this parameter if you are defining an asynchronous topic. | +| `schema` | The interface that describes the structure of the message. The format must be `\Api\::`. | + +#### `handler` element + +The `handler` element specifies the class where the logic for handling messages exists and the method it executes. + +| Parameter | Description | +| --- | --- | +| `name` | A string that uniquely defines the handler. The name can be derived from the topic name if the handler is specific to the topic. If the handler provides more generic capabilities, name the handler so that it describes those capabilities. | +| `type` | The class or interface that defines the handler. | +| `method` | The method this handler executes. | +| `disabled` | Determines whether this handler is disabled. The default value is `false`. | + +See [Handler processing](#handler-processing). + +## `queue_consumer.xml` + +The `queue_consumer.xml` file contains one or more `consumer` elements: + +### Example + +```xml + + + + + + + +``` + +#### `consumer` element + +| Attribute | Description | +| --- | --- | +| `name` (required) | The name of the consumer. | +| `queue` (required) | Specifies the queue name to send the message to. | +| `handler` | Specifies the class and method that processes the message. The value must be specified in the format `\Module\::`. See [Handler processing](#handler-processing). | +| `consumerInstance` | The class name that consumes the message. The default value is `Magento\Framework\MessageQueue\Consumer`. | +| `connection` | For explicit values, use `amqp`, `stomp`, or `db`. If omitted, the connection is resolved automatically. See [Connection resolution](#connection-resolution). | +| `maxMessages` | Specifies the maximum number of messages to consume. | +| `maxIdleTime` | Defines the maximum waiting time in seconds for a new message from the queue. If no message was handled within this period of time, the consumer exits. The default value is `null`. | +| `sleep` | Specifies time in seconds to sleep before checking if a new message is available in the queue. The default value is `null` which equals 1 second. | +| `onlySpawnWhenMessageAvailable` | Boolean value (`1` or `0` only) that identifies whether a consumer should be spawned only if there is available message in the related queue. The default value is `null`. | + + + +The `maxIdleTime` and `sleep` attributes are handled only by consumers fired with a defined `maxMessages` parameter. The `onlySpawnWhenMessageAvailable` attribute is only validated by the `\Magento\MessageQueue\Model\Cron\ConsumersRunner` class that runs consumer processes with cron. For details, see [Consumer spawning behavior](#consumer-spawning-behavior). + +## `queue_topology.xml` + +The `queue_topology.xml` file defines the message routing rules and declares queues and exchanges. It contains the following elements: + +* `exchange` +* `exchange/binding` (optional) +* `exchange/arguments` (optional) +* `exchange/binding/arguments` (optional) + +### Example + +```xml + + + + + + + value + + + + magento-log-exchange + + + + + + magento-log-exchange + + + +``` + +#### `exchange` element + +| Attribute | Description | +| -------------- | ----------- | +| `name` (required) | A unique ID for the exchange. | +| `type` | Specifies the type of exchange. Currently, the only value supported is `topic`. | +| `connection` | For explicit values, use `amqp`, `stomp`, or `db`. If omitted, the connection is resolved automatically. See [Connection resolution](#connection-resolution). | +| `durable` | Boolean value indicating whether the exchange is persistent. Non-durable exchanges are purged when the server restarts. The default value is `true`. | +| `autoDelete` | Boolean value indicating whether the exchange is deleted when all queues have finished using it. The default is `false`. | +| `internal` | Boolean value. If set to true, the exchange may not be used directly by publishers, but only when bound to other exchanges. The default is `false`. | + +#### `binding` element + +The `binding` element is a subnode of the `exchange` element. + +| Attribute | Description | +| -------------- | ----------- | +| `id` (required) | A unique ID for this binding. | +| `topic` (required) | The name of a topic. You can specify an asterisk (*) or pound sign (#) as wildcards. These are described below the table.| +| `destinationType` | The default value is `queue`. | +| `destination` (required) | Identifies the name of a queue. | +| `disabled` | Determines whether this binding is disabled. The default value is `false`. | + +Example topic names that include wildcards: + +| Pattern | Description | Example matching topics | Example non-matching topics | +| --- | --- | --- | --- | +| `*.*.*` | Matches any topic that contains three segments (two periods) | `mytopic.createOrder.success`, `mytopic.updatePrice.item1` | `mytopic.createOrder`, `mytopic.createOrder.success.true` | +| `#` | Matches any topic name. | `mytopic`, `mytopic.createOrder.success`, `this.is.a.long.topic.name` | Not applicable | +| `mytopic.#` | Matches any topic name that begins with `mytopic` and has a period afterward. | `mytopic.success`, `mytopic.createOrder.error` | `new.mytopic.success` | +| `*.Order.#` | There must be one string before `.Order`. There can be any number of strings (including 0) after that. | `mytopic.Order`, `mytopic.Order.Create`, `newtopic.Order.delete.success` | `mytopic.Sales.Order.Create` | + +#### `arguments` element + +The `arguments` element is an optional element that contains one or more `argument` elements. These arguments define key/value pairs that are passed to the broker for processing. + +Each `argument` definition must have the following parameters: + +| Attribute | Description | +| --- | --- | +| `name` | The parameter name. | +| `type` | The data type of the value. | + +The following illustrates an `arguments` block: + +```xml + + 1 + USPS + +``` + +## `queue_publisher.xml` + +The `queue_publisher.xml` file defines which connection and exchange to use to publish messages for a specific topic. It contains the following elements: + +* `publisher` +* `publisher/connection` + +### Example + +**For RabbitMQ (AMQP):** + +```xml + + + + + + + + +``` + +**For ActiveMQ Artemis (STOMP):** + +```xml + + + + + + + + +``` + +#### `publisher` element + +| Attribute | Description | +| --- | --- | +| `topic` (required) | The name of the topic. | +| `queue` | For ActiveMQ Artemis (STOMP), specifies the queue name when it differs from the topic name. | +| `disabled` | Determines whether this queue is disabled. The default value is `false`. | + +#### `connection` element + +The `connection` element is a subnode of the `publisher` element. Only one enabled connection can be defined for a publisher at any given time. If you omit the `connection` element, the connection is resolved automatically and `magento` is used as the exchange. See [Connection resolution](#connection-resolution). + + +| Attribute | Description | +| --- | --- | +| `name` | The connection name. For explicit values, use `amqp`, `stomp`, or `db`. See [Connection resolution](#connection-resolution). | +| `exchange` | The name of the exchange to publish to. The default system exchange name is `magento`. | +| `disabled` | Determines whether this queue is disabled. The default value is `false`. | + + + +You cannot enable more than one `publisher` for each `topic`. + +## Connection resolution + +Connection names are resolved dynamically based on the message queue deployment configuration in `env.php`. If you don't explicitly specify a connection, the system automatically selects the appropriate one. + +### Automatic resolution + +The system checks `env.php` for message queue configuration: + +* If AMQP (RabbitMQ) is configured, the `amqp` connection is used +* If STOMP (ActiveMQ Artemis) is configured, the `stomp` connection is used +* Otherwise, the database (`db`) connection is used + +### Explicit connection values + +When specifying a connection explicitly, use one of these values: + +| Connection type | Value | Notes | +| --- | --- | --- | +| RabbitMQ | `amqp` | For AMQP connections in `queue_consumer.xml`, the value must match the `connection` attribute in `queue_topology.xml`. | +| ActiveMQ Artemis | `stomp` | Requires Adobe Commerce or Magento Open Source 2.4.5 or later. Use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. | +| Database | `db` | MySQL-based queue storage. Used as fallback when no message broker is configured. | + +## Handler processing + +A [handler](#handler-element) is a class and method that processes a message. You can define a handler in two places: + +* In the `` element of the module's `communication.xml` file +* In the `handler` attribute of the module's `queue_consumer.xml` file + +The following conditions determine which handler is executed: + +* If the consumer in `queue_consumer.xml` does not have a `consumerInstance` defined, the system uses the default consumer: `Magento\Framework\MessageQueue\Consumer`. In this case, if the `` element contains the `handler` attribute, it is used and the `` element in `communication.xml` is ignored. +* If the consumer in `queue_consumer.xml` has a `consumerInstance` defined, the specific consumer implementation defines how the handler is used. + +The following table shows how the built-in consumers process handlers: + +| Class name | Handler in `communication.xml` executed? | Handler in `queue_consumer.xml` executed? | +| --- | --- | --- | +| `Magento\Framework\MessageQueue\Consumer` | Only if not defined in `queue_consumer.xml` | Yes, if exists | +| `Magento\Framework\MessageQueue\BatchConsumer` | Only if not defined in `queue_consumer.xml` | Yes, if exists | +| `Magento\AsynchronousOperations\Model\MassConsumer` | Yes, if exists | Yes, if exists | + +## Consumer spawning behavior + +Two settings control when consumers spawn and exit: `onlySpawnWhenMessageAvailable` and [`consumers-wait-for-messages`](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/tutorials/message-consumers). Both help reduce server resource usage, but they work differently. + +| Setting | Scope | Behavior | +| --- | --- | --- | +| `onlySpawnWhenMessageAvailable` | Per-consumer or global | Checks for messages *before* spawning. Only creates a consumer process if messages exist in the queue. | +| `consumers-wait-for-messages` | Global only | Always spawns a consumer. When set to `false`, the consumer exits immediately if no messages are available. Because this option is a global option, it cannot be configured separately for each consumer. | + +The key difference between the two settings: `onlySpawnWhenMessageAvailable` prevents unnecessary process creation, while `consumers-wait-for-messages` creates a process that immediately terminates if the queue is empty. + +### Configuration + +Set `onlySpawnWhenMessageAvailable` globally in `app/etc/env.php`: + +```php +'queue' => [ + 'only_spawn_when_message_available' => 1 +] +``` + +The default global value is `1`. To override for a specific consumer, set the `onlySpawnWhenMessageAvailable` attribute in `queue_consumer.xml`. The per-consumer setting takes priority over the global setting. + +### Recommended combinations + +* **Infrequent consumers**—Combine `onlySpawnWhenMessageAvailable` with `maxIdleTime`. The consumer spawns only when needed and terminates after a period of inactivity. +* **Resource optimization**—Combine the global `only_spawn_when_message_available` setting with `consumers-wait-for-messages` set to `false`. Consumers run only when messages exist and exit when the queue is empty. + +## ActiveMQ Artemis (STOMP) support + + + +ActiveMQ Artemis (STOMP) support was introduced in Adobe Commerce 2.4.5 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. + +## Updating `queue.xml` + +See [Migrate message queue configuration](migration.md) for information about upgrading from Adobe Commerce and Magento Open Source 2.0 or 2.1. diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md deleted file mode 100644 index 54090679f..000000000 --- a/src/pages/development/components/message-queues/configuration.md +++ /dev/null @@ -1,292 +0,0 @@ ---- -title: Configure Message Queues | Commerce PHP Extensions -description: Add message queue functionality to Adobe Commerce and Magento Open Source extensions. -keywords: - - Configuration - - Extensions ---- - -# Configure message queues - -The message queue topology is an Adobe Commerce and Magento Open Source feature. You can also add it to existing modules. - -Configuring the message queue topology involves creating and modifying the following configuration files in the `/etc` directory: - -* [`communication.xml`](#communicationxml) - Defines aspects of the message queue system that all communication types have in common. -* [`queue_consumer.xml`](#queue_consumerxml) - Defines the relationship between an existing queue and its consumer. -* [`queue_topology.xml`](#queue_topologyxml) - Defines the message routing rules and declares queues and exchanges. -* [`queue_publisher.xml`](#queue_publisherxml) - Defines the exchange where a topic is published. - -## Use cases - -Depending on your needs, you may only need to create and configure `communication.xml` and one or two of these files. - -* If you only want to publish to an existing queue created by a 3rd party system, you will only need the `queue_publisher.xml` file. -* If you only want to consume from an existing queue, you will only need the `queue_consumer.xml` config file. -* In cases where you want to configure the local queue and publish to it for 3rd party systems to consume, you will need the `queue_publisher.xml` and `queue_topology.xml` files. -* When you want to configure the local queue and consume messages published by 3rd party system, you will need the `queue_topology.xml` and `queue_consumer.xml` files. - -## `communication.xml` - -The `/etc/communication.xml` file defines aspects of the message queue system that all communication types have in common. This release supports AMQP, STOMP, and database connections. - -### Example - -The following sample defines two synchronous topics. The first topic is for RPC calls. The second uses a custom service interface. - -```xml - - - - - - - - - -``` - -#### topic element - -Topic configuration is flexible in that you can switch the transport layer for topics at deployment time. These values can be overwritten in the `env.php` file. - -The `name` parameter is required. The topic definition must include either a `request` or a `schema`. Use `schema` if you want to implement a custom service interface. Otherwise, specify `request`. If `request` is specified, then also specify `response` if the topic is synchronous. - -Parameter | Description ---- | --- -name | A string that uniquely identifies the topic. A topic name should be a series of strings that are separated by periods. The leftmost string should be the most general, and each string afterward should narrow the scope. For example, to describe actions for tending to pets, you might create names such as `cat.white.feed` and `dog.retriever.walk`. Wildcards are not supported in the `communication.xml` file. -request | Specifies the data type of the topic. -response | Specifies the format of the response. This parameter is required if you are defining a synchronous topic. Omit this parameter if you are defining an asynchronous topic. -schema | The interface that describes the structure of the message. The format must be `\Api\::`. - -#### handler element - -The `handler` element specifies the class where the logic for handling messages exists and the method it executes. - -Parameter | Description ---- | --- -name | A string that uniquely defines the handler. The name can be derived from the topic name if the handler is specific to the topic. If the handler provides more generic capabilities, name the handler so that it describes those capabilities. -type | The class or interface that defines the handler. -method | The method this handler executes. -disabled | Determines whether this handler is disabled. The default value is `false`. - -## `queue_consumer.xml` - -The `queue_consumer.xml` file contains one or more `consumer` elements: - -### Example - -```xml - - - - - - - -``` - -#### `consumer` element - -| Attribute | Description | -| ----------------------------- | ----------- | -| name (required) | The name of the consumer. | -| queue (required) | Defines the queue name to send the message to. | -| handler | Specifies the class and method that processes the message. The value must be specified in the format `\Module\::`.| -| consumerInstance | The class name that consumes the message. Default value: `Magento\Framework\MessageQueue\Consumer`. | -| connection | The connection is resolved dynamically based on the message queue deployment configuration in `env.php`. If the queue is configured to use AMQP or STOMP, the corresponding connection is used. Otherwise, db connection is used. If you choose to explicitly define a connection for a consumer, note the following requirements: For AMQP connections, the connection name must match the value of the `connection` attribute in the `queue_topology.xml` file. For STOMP connections, use `stomp` as the connection name. Otherwise, the connection name must be `db`. | -| maxMessages | Specifies the maximum number of messages to consume.| -| maxIdleTime | Defines the maximum waiting time in seconds for a new message from the queue. If no message was handled within this period of time, the consumer exits. Default value: `null`| -| sleep | Specifies time in seconds to sleep before checking if a new message is available in the queue. Default value is `null` which equals to 1 second.| -| onlySpawnWhenMessageAvailable | Boolean value (`1` or `0` only) that identifies whether a consumer should be spawned only if there is available message in the related queue. Default value: `null`| - - - -The `maxIdleTime` and `sleep` attributes will be handled only by consumers that were fired with a defined `maxMessages` parameter. The `onlySpawnWhenMessageAvailable` attribute is only checked and validated by the `\Magento\MessageQueue\Model\Cron\ConsumersRunner` class that runs consumer processes with cron. - -It is possible to set `onlySpawnWhenMessageAvailable` globally by setting `queue/only_spawn_when_message_available` equal to `0` or `1` in `app/etc/env.php`. By default, the global value of `only_spawn_when_message_available` for all consumers is `1`. -The `onlySpawnWhenMessageAvailable` consumer attribute has higher priority than the global `queue/only_spawn_when_message_available` setting in `app/etc/env.php`. Therefore, it is possible to overwrite the global `only_spawn_when_message_available` value by setting `onlySpawnWhenMessageAvailable` equal to `0` or `1` for each consumer in `queue_consumer.xml`. - -The `onlySpawnWhenMessageAvailable` and `maxIdleTime` attributes may be combined if a specific consumer needs to run infrequently. The consumer will only spawn when it is needed, and it terminates itself if it is inactive for a certain period. -It is also possible to combine the global `queue/only_spawn_when_message_available` setting in `app/etc/env.php` with the `queue/consumers-wait-for-messages` setting. That means that the consumer will run only when there is an available message in the queue, and it will be terminated when there are no more messages to process. This combination of settings is recommended to save server resources such as CPU usage. - -The [`consumers-wait-for-messages`](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/tutorials/message-consumers) option works similar to `onlySpawnWhenMessageAvailable`. When it is set to `false`, the consumer processes all messages and exits if there are no available messages in the queue. -The problem is that every time the cron job `cron_consumers_runner` runs, it spawns a new consumer process, the consumer checks if messages are available, and it terminates itself if there are no messages. -Meanwhile, the `onlySpawnWhenMessageAvailable` attribute first checks if there are available messages, and it spawns a new consumer process only if there are messages. It means that it does not spawn unneeded processes which take up memory, live for a very short period, and then disappear. - - - -The [`consumers-wait-for-messages`](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/tutorials/message-consumers) option is a global option and cannot be configured separately for each consumer, such as the `onlySpawnWhenMessageAvailable` option. - -#### `handler` element - -A handler is a class and method that processes a message. The application has two ways to define a handler for messages. - -* In the `` element of the module's `communication.xml` file -* In the `handler` attribute of the module's `queue_consumer.xml` file - -The following conditions determine how these handlers are processed: - -* If the consumer in `queue_consumer.xml` does not have a `consumerInstance` defined, then the system uses the default consumer: `Magento\Framework\MessageQueue\Consumer`. In this case, if the `` element contains the `handler` attribute, then it will be used, and the `` element in `communication.xml` will be ignored. -* If the consumer in `queue_consumer.xml` has a `consumerInstance` defined, then the specific consumer implementation defines how the `handler` is used. - -The application provides these consumers out-of-the-box: - -| Class name | Handler in `communication.xml` will be executed? | Handler in `queue_consumer.xml` will be executed? | -| ---------------- | ----------- | ---------- | -| `Magento\Framework\MessageQueue\Consumer` | Only if not defined in `queue_consumer.xml` | Yes, if exists | -| `Magento\Framework\MessageQueue\BatchConsumer` | Only if not defined in `queue_consumer.xml` | Yes, if exists | -| `Magento\AsynchronousOperations\Model\MassConsumer` | Yes, if exists | Yes, if exists | - -## `queue_topology.xml` - -The `queue_topology.xml` file defines the message routing rules and declares queues and exchanges. It contains the following elements: - -* `exchange` -* `exchange/binding` (optional) -* `exchange/arguments` (optional) -* `exchange/binding/arguments` (optional) - -### Example - -```xml - - - - - - - value - - - - magento-log-exchange - - - - - - magento-log-exchange - - - -``` - -#### `exchange` element - -| Attribute | Description | -| -------------- | ----------- | - name (required) | A unique ID for the exchange. - type | Specifies the type of exchange. The default value is `topic` because only `topic` type is supported. - connection (required) | Connection is defined dynamically based on deployment configuration of message queue in `env.php`. If AMQP or STOMP is configured in deployment configuration, the respective connection is used. Otherwise, db connection is used. If you still want to specify connection, the connection name must be `amqp` for AMQP, `stomp` for STOMP. For MySQL connections, the connection name must be `db`. - durable | Boolean value indicating whether the exchange is persistent. Non-durable exchanges are purged when the server restarts. The default is `true`. - autoDelete | Boolean value indicating whether the exchange is deleted when all queues have finished using it. The default is `false`. - internal | Boolean value. If set to true, the exchange may not be used directly by publishers, but only when bound to other exchanges. The default is `false`. - -#### `binding` element - -The `binding` element is a subnode of the `exchange` element. - -| Attribute | Description | -| -------------- | ----------- | -| id (required) | A unique ID for this binding. | -| topic (required) | The name of a topic. You can specify an asterisk (*) or pound sign (#) as wildcards. These are described below the table.| -| destinationType | The default value is `queue`. | -| destination (required) | Identifies the name of a queue. | -| disabled | Determines whether this binding is disabled. The default value is `false`. | - -Example topic names that include wildcards: - -| Pattern | Description | Example matching topics | Example non-matching topics -| --- | --- | --- | --- -`*.*.*` | Matches any topic that contains exactly two periods. | `mytopic.createOrder.success`, `mytopic.updatePrice.item1` | `mytopic.createOrder`, `mytopic.createOrder.success.true` -`#`| Matches any topic name. | `mytopic`, `mytopic.createOrder.success`, `this.is.a.long.topic.name` | Not applicable -`mytopic.#` | Matches any topic name that begins with `mytopic` and has a period afterward. | `mytopic.success`, `mytopic.createOrder.error` | `new.mytopic.success`, -`*.Order.#` | There must be one string before __.Order__. There can be any number of strings (including 0) after that. | `mytopic.Order`, `mytopic.Order.Create`, `newtopic.Order.delete.success` | `mytopic.Sales.Order.Create` - -#### `arguments` element - -The `arguments` element is an optional element that contains one or more `argument` elements. These arguments define key/value pairs that are passed to the broker for processing. - -Each `argument` definition must have the following parameters: - -| Attribute | Description | -| --------------- | ----------- | -| name | The parameter name | -| type | The data type of the value | - -The following illustrates an `arguments` block: - -```xml - - 1 - USPS - -``` - -## `queue_publisher.xml` - -The `queue_publisher.xml` file defines which connection and exchange to use to publish messages for a specific topic. It contains the following elements: - -* publisher -* publisher/connection - -### Example - -__For RabbitMQ (AMQP):__ - -```xml - - - - - - - - -``` - -__For ActiveMQ Artemis (STOMP):__ - -```xml - - - - - - - - -``` - -#### `publisher` element - -| Attribute | Description | -| -------------------- | ----------- | -| topic (required) | The name of the topic. | -| queue | For ActiveMQ Artemis (STOMP), specify the queue name when it differs from the topic name. | -| disabled | Determines whether this queue is disabled. The default value is `false`. | - -#### `connection` element - -The `connection` element is a subnode of the `publisher` element, and only one enabled active connection can be defined for a publisher at any given time. If you omit the `connection` element, the connection is resolved dynamically from the message queue deployment configuration in `env.php`, and `magento` is used as the exchange. If AMQP or STOMP is configured, the corresponding connection is used. Otherwise, the db connection is used. - -| Attribute | Description | -| -------------------- | ----------- | -| name | The connection name is resolved dynamically from the message queue deployment configuration in `env.php`. If you choose to explicitly define a connection for a publisher, note the following requirements: For AMQP connections, the connection name must match the `connection` attribute defined in the `queue_topology.xml` file. For STOMP connections, the connection name must be `stomp`. If neither AMQP or STOMP is configured, the connection name must be `db`. | -| exchange | The name of the exchange to publish to. The default system exchange name is `magento`. | -| disabled | Determines whether this queue is disabled. The default value is `false`. | - - - -You cannot enable more than one `publisher` for each `topic`. - -## ActiveMQ Artemis (STOMP) Support - - - -ActiveMQ Artemis (STOMP) support was introduced in Adobe Commerce 2.4.5 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. - -## Updating `queue.xml` - -See [Migrate message queue configuration](migration.md) for information about upgrading from Adobe Commerce and Magento Open Source 2.0 or 2.1. From 79e6fc7ff85541b7837ae5a49c60b18f4d0ad03f Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 21:17:02 -0600 Subject: [PATCH 33/43] Update and rename migration.md to required Refactor migration.md for clarity and conciseness - Clarify ActiveMQ Artemis support timeline and consolidate redundant backport mentions - Simplify attribute tables to show only actual changes between versions - Remove verbose table introductions and combine related InlineAlerts - Add Legacy migrations section to organize older 2.0/2.1 content --- .../components/message-queues/migration.md | 337 ------------------ .../components/message-queues/required | 312 ++++++++++++++++ 2 files changed, 312 insertions(+), 337 deletions(-) delete mode 100644 src/pages/development/components/message-queues/migration.md create mode 100644 src/pages/development/components/message-queues/required diff --git a/src/pages/development/components/message-queues/migration.md b/src/pages/development/components/message-queues/migration.md deleted file mode 100644 index 445c6e210..000000000 --- a/src/pages/development/components/message-queues/migration.md +++ /dev/null @@ -1,337 +0,0 @@ ---- -title: Migrate Configuration | Commerce PHP Extensions -description: Use these examples to migrate your message queue configuration between 2.x versions of Adobe Commerce and Magento Open Source. -keywords: - - Configuration - - Extensions ---- - -# Migrate message queue configuration - -## Migrate from 2.4.4 to 2.4.5, 2.4.6, 2.4.7, 2.4.8 - -Adobe Commerce introduced support for Apache ActiveMQ Artemis (STOMP) as an alternative message broker to RabbitMQ (AMQP), and this feature was backported to versions 2.4.5, 2.4.6, 2.4.7, and 2.4.8. When upgrading from 2.4.4 (or earlier) to 2.4.5 or later, you can continue using RabbitMQ or choose to migrate to ActiveMQ Artemis. - -### Key Changes in 2.4.5+ - -- **ActiveMQ Artemis (STOMP) Support**: New message broker option alongside RabbitMQ (backported to 2.4.5, 2.4.6, 2.4.7, 2.4.8) -- **Extended Dynamic Connection Detection**: Existing dynamic connection detection now supports STOMP in addition to AMQP -- **Enhanced SSL Configuration**: Improved SSL options for both brokers -- **Multiple Named Connections**: Enhanced support for configuring multiple broker connections - -### Configuration File Changes - -The following table shows the key differences between 2.4.4 and 2.4.5+ configurations: - -| Configuration Area | 2.4.4 | 2.4.5+ | -| ------------------ | ----- | ------ | -| `env.php` default_connection | Optional when single broker configured | Optional when single broker configured; required when multiple brokers (can be `'amqp'`, `'stomp'`, or `'db'`) | -| `env.php` broker configuration | RabbitMQ (AMQP) only | RabbitMQ (AMQP) and/or ActiveMQ Artemis (STOMP) | -| `queue_consumer.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.5+) | -| `queue_publisher.xml` connection element | Optional for AMQP, supports multiple connections | Optional for AMQP/STOMP, enhanced multiple connections | -| `queue_topology.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.5+) | - -### Update `env.php` Configuration - -**For RabbitMQ (AMQP) - No Changes Required:** - -```php -'queue' => [ - 'amqp' => [ - 'host' => 'rabbitmq.example.com', - 'port' => '5672', - 'user' => 'magento', - 'password' => 'magento', - 'virtualhost' => '/', - 'ssl' => false - ] -] -``` - -**For ActiveMQ Artemis (STOMP) - Available in 2.4.5+ (backported to 2.4.5-2.4.8):** - -```php -'queue' => [ - 'stomp' => [ - 'host' => 'activemq.example.com', - 'port' => '61613', - 'user' => 'artemis', - 'password' => 'artemis', - 'ssl' => false - ] -] -``` - -**For Both Brokers - Available in 2.4.5+ (requires `default_connection`):** - -```php -'queue' => [ - 'default_connection' => 'amqp', // Required when multiple brokers are configured - 'amqp' => [ - 'host' => 'rabbitmq.example.com', - 'port' => '5672', - 'user' => 'magento', - 'password' => 'magento', - 'virtualhost' => '/', - 'ssl' => false - ], - 'stomp' => [ - 'host' => 'activemq.example.com', - 'port' => '61613', - 'user' => 'artemis', - 'password' => 'artemis', - 'ssl' => false - ] -] -``` - - - -The `default_connection` parameter is only required when multiple message brokers are configured. When only one broker (AMQP or STOMP) is configured, the system automatically uses the available broker. - - - -The `connection` attribute in XML configuration files (`queue_consumer.xml`, `queue_publisher.xml`, `queue_topology.xml`) is optional when you want to use the default broker from `env.php`. However, you can explicitly specify `connection="amqp"` or `connection="stomp"` when you want a particular module or functionality to use a specific broker, even when multiple brokers are configured. - -### Update `queue_consumer.xml` Files - -The first column in the following table lists parameters in 2.4.5+ `queue_consumer.xml` files. The second column shows the equivalent in 2.4.4. - -| 2.4.5+ Attribute | 2.4.4 Equivalent | Notes | -| ----------------- | ----------------- | ----- | -| `/name` | `/name` | No change | -| `/queue` | `/queue` | No change | -| `/handler` | `/handler` | No change | -| `/consumerInstance` | `/consumerInstance` | No change | -| `/connection` | `/connection` | Optional in both versions, auto-detected from env.php. In 2.4.5+ also supports STOMP. Use explicitly to force specific broker selection. | -| `/maxMessages` | `/maxMessages` | No change | - -**2.4.4 Example:** - -```xml - -``` - -**2.4.5+ Example (Uses default broker from env.php):** - -```xml - -``` - -**2.4.5+ Example (Explicitly specifies broker):** - -```xml - - - - - -``` - -### Update `queue_publisher.xml` Files - -The first column in the following table lists parameters in 2.4.5+ `queue_publisher.xml` files. The second column shows the equivalent in 2.4.4. - -| 2.4.5+ Attribute | 2.4.4 Equivalent | Notes | -| ----------------- | ----------------- | ----- | -| `/topic` | `/topic` | No change | -| `/queue` | Not available | Available in 2.4.5+ for ActiveMQ Artemis | -| `/disabled` | `/disabled` | No change | -| `//name` | `//name` | Can specify `stomp` for ActiveMQ (2.4.5+) | -| `//exchange` | `//exchange` | Not used with STOMP | -| `//disabled` | `//disabled` | Enhanced in 2.4.5+ for multiple connections | - -**2.4.4 Example (RabbitMQ only):** - -```xml - - - -``` - -**2.4.5+ Example (RabbitMQ):** - -```xml - - - - -``` - -**2.4.5+ Example (ActiveMQ Artemis):** - -```xml - - - - -``` - -### Update `queue_topology.xml` Files - -The first column in the following table lists parameters in 2.4.5+ `queue_topology.xml` files. The second column shows the equivalent in 2.4.4. - -| 2.4.5+ Attribute | 2.4.4 Equivalent | Notes | -| ----------------- | ----------------- | ----- | -| `/name` | `/name` | No change | -| `/type` | `/type` | No change | -| `/connection` | `/connection` | Optional in both versions, auto-detected from env.php. In 2.4.5+ also supports STOMP. Use explicitly to force specific broker selection. | -| `/durable` | `/durable` | No change | -| `/autoDelete` | `/autoDelete` | No change | -| `//id` | `//id` | No change | -| `//topic` | `//topic` | No change | -| `//destinationType` | `//destinationType` | No change | -| `//destination` | `//destination` | No change | - -**2.4.4 Example:** - -```xml - - - -``` - -**2.4.5+ Example (Uses default broker from env.php):** - -```xml - - - -``` - -**2.4.5+ Example (Explicitly specifies broker):** - -```xml - - - - - - - - - -``` - - - -Connection detection has always been dynamic based on your `env.php` configuration. If AMQP is configured in deployment configuration, the AMQP connection is used automatically. In 2.4.5+, this same dynamic detection was extended to support STOMP connections. This allows you to omit connection declarations in XML configuration files. - - - -ActiveMQ Artemis (STOMP) was backported to Adobe Commerce versions 2.4.5, 2.4.6, 2.4.7, and 2.4.8. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. -## Migrate from 2.1 to 2.2 - -To upgrade the message queues for Adobe Commerce or Magento Open Source 2.1, you must create the following files in the `/etc` directory for each module that will use the message queue framework. - -- `queue_consumer.xml` - Defines the relationship between an existing queue and its consumer. -- `queue_topology.xml`- Defines the message routing rules and declares queues and exchanges. -- `queue_publisher.xml` - Defines the exchange where a topic is published. - -The existing `queue.xml` file is deprecated. - -For complete details about these files, see [Configure message queues](configuration.md) - - - -The Adobe Commerce and Magento Open Source 2.1 `communication.xml` file has not changed for Adobe Commerce and Magento Open Source 2.2. - -### Create the `queue_consumer.xml` file - -The first column in the following table lists the all the parameters in the `queue_consumer.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.1 `queue.xml` file the equivalent parameters are located. - -| 2.2 Attribute | 2.1 queue.xml source | -| ---------------- | ----------- | -`/name` | `//consumer` -`/queue` | `//name` -`/handler` | `//handler` -`/consumerInstance` | `//consumerInstance` -`/connection` | `/type` -`/maxMessages` | `//maxMessages` - -### Create the `queue_topology.xml` file - -The first column in the following table lists the all the parameters in the `queue_topology.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.1 `queue.xml` file the equivalent parameters are located. - -| 2.2 Attribute | 2.1 queue.xml source | -| ---------------- | -----------| -`/name` | `/exchange` -`/type` | Not present in 2.1. Set this value to `topic`. -`/connection` | `/type` -`/durable` | Not present in 2.1. Omit this parameter to accept the default value. -`/autoDelete` | Not present in 2.1. Omit this parameter to accept the default value. -`/internal` | Not present in 2.1. Omit this parameter to accept the default value. -`//id` | Not present in 2.1. It is recommended that you concatenate the 2.1 exchange name, topic name, and queue name to create a value for the `id` parameter. -`//topic` | `/topic` -`//destinationType` | Not present in 2.1. This value must be set to `queue`. -`//destination` | `//name` -`//disabled` | Not present in 2.1. Omit this parameter to accept the default value. -`/` and `//` | Not present in 2.1. Omit this element. - -### Create the `queue_publisher.xml` file - -The first column in the following table lists the all the parameters in the `queue_publisher.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.1 `queue.xml` file the equivalent parameters are located. - -| 2.2 Attribute | 2.1 queue.xml source | -| ---------------- | ----------- | -`/topic` | `/topic` -`/disabled` | Not present in 2.1. Omit this parameter to accept the default value. -`//name` | `/type` -`//exchange` | `exchange` -`//disabled` | Not present in 2.1. Omit this parameter to accept the default value. - -## Migrate from 2.0 to 2.2 - -To upgrade from Adobe Commerce or Magento Open Source 2.0, you must create the following files in the `/etc` directory for each module that will use the message queue framework. - -- `queue_consumer.xml` - Defines the relationship between an existing queue and its consumer. -- `queue_topology.xml`- Defines the message routing rules. -- `queue_publisher.xml` - Defines the relationship between a topic and its publisher. - -The existing `queue.xml` file is deprecated. - -For complete details about these files, see [Configure message queues](configuration.md) - -### Create the `queue_consumer.xml` file - -The first column in the following table lists the all the parameters in the `queue_consumer.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.0 `queue.xml` file the equivalent parameters are located. - -2.2 Attribute | 2.0 queue.xml Source ----------------- | ----------- -`/name` | `/name` -`/queue` | `/queue` -`/handler` | Use the values from `/class` and `/method` in the format `\Module\::`. -`/consumerInstance` | `/executor` -`/connection` | `/connection` -`/maxMessages` | `/max_messages` - -### Create the `queue_topology.xml` file - -The first column in the following table lists the all the parameters in the `queue_topology.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.0 `queue.xml` file the equivalent parameters are located. - -| 2.2 Attribute | 2.0 queue.xml Source | -| ---------------- | -----------| -`/name` | `/exchange` -`/type` | Not present in 2.0. Set this value to `topic`. -`/connection` | `/connection` -`/durable` | Not present in 2.0. Omit this parameter to accept the default value. -`/autoDelete` | Not present in 2.0. Omit this parameter to accept the default value. -`/internal` | Not present in 2.0. Omit this parameter to accept the default value. -`//id` | Not present in 2.0. It is recommended that you concatenate the 2.1 exchange name, topic name, and queue name to create a value for the `id` parameter. -`//topic` | `/topic` -`//destinationType` | Not present in 2.0. This value must be set to `queue`. -`//destination` | `/queue` -`//disabled` | Not present in 2.0. Omit this parameter to accept the default value. -`` | Not present in 2.0. Omit this element. - -### Create the `queue_publisher.xml` file - -The first column in the following table lists the all the parameters in the `queue_publisher.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.0 `queue.xml` file the equivalent parameters are located. - -| 2.2 Attribute | 2.0 queue.xml Source | -| ---------------- | ----------- | -`/topic` | `/name` -`/disabled` | Not present in 2.0. Omit this parameter to accept the default value. -`//name` | `/connection` -`//exchange` | `/exchange` -`//disabled` | Not present in 2.0. Omit this parameter to accept the default value. diff --git a/src/pages/development/components/message-queues/required b/src/pages/development/components/message-queues/required new file mode 100644 index 000000000..8b500cf91 --- /dev/null +++ b/src/pages/development/components/message-queues/required @@ -0,0 +1,312 @@ +--- +title: Migrate message queue configuration +description: Learn how to migrate message queue configuration between Adobe Commerce versions, including support for RabbitMQ (AMQP) and ActiveMQ Artemis (STOMP). +keywords: + - Configuration + - Message Queue + - Migration +--- + +# Migrate message queue configuration + +This guide provides migration instructions for message queue configuration across Adobe Commerce versions. Use these examples to update your `env.php` and XML configuration files when upgrading. + +## Migrate from 2.4.4 to 2.4.5+ + +Adobe Commerce 2.4.5 and later versions support Apache ActiveMQ Artemis (STOMP) as an alternative message broker to RabbitMQ (AMQP). When upgrading from 2.4.4 or earlier, you can continue using RabbitMQ or migrate to ActiveMQ Artemis. + +### Key changes in 2.4.5+ + +- **ActiveMQ Artemis (STOMP) support**—New message broker option alongside RabbitMQ +- **Extended dynamic connection detection**—Supports STOMP in addition to AMQP +- **Enhanced SSL configuration**—Improved SSL options for both brokers +- **Multiple named connections**—Configure multiple broker connections simultaneously + +For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. + +### Configuration File Changes + +The following table shows the key differences between 2.4.4 and 2.4.5+ configurations: + +| Configuration Area | 2.4.4 | 2.4.5+ | +| ------------------ | ----- | ------ | +| `env.php` default_connection | Optional when single broker configured | Optional when single broker configured; required when multiple brokers (can be `'amqp'`, `'stomp'`, or `'db'`) | +| `env.php` broker configuration | RabbitMQ (AMQP) only | RabbitMQ (AMQP) and/or ActiveMQ Artemis (STOMP) | +| `queue_consumer.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.5+) | +| `queue_publisher.xml` connection element | Optional for AMQP, supports multiple connections | Optional for AMQP/STOMP, enhanced multiple connections | +| `queue_topology.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.5+) | + +### Update `env.php` Configuration + +**For RabbitMQ (AMQP) - No Changes Required:** + +```php +'queue' => [ + 'amqp' => [ + 'host' => 'rabbitmq.example.com', + 'port' => '5672', + 'user' => 'magento', + 'password' => 'magento', + 'virtualhost' => '/', + 'ssl' => false + ] +] +``` + +**For ActiveMQ Artemis (STOMP):** + +```php +'queue' => [ + 'stomp' => [ + 'host' => 'activemq.example.com', + 'port' => '61613', + 'user' => 'artemis', + 'password' => 'artemis', + 'ssl' => false + ] +] +``` + +**For both brokers (requires `default_connection`):** + +```php +'queue' => [ + 'default_connection' => 'amqp', // Required when multiple brokers are configured + 'amqp' => [ + 'host' => 'rabbitmq.example.com', + 'port' => '5672', + 'user' => 'magento', + 'password' => 'magento', + 'virtualhost' => '/', + 'ssl' => false + ], + 'stomp' => [ + 'host' => 'activemq.example.com', + 'port' => '61613', + 'user' => 'artemis', + 'password' => 'artemis', + 'ssl' => false + ] +] +``` + + + +The `default_connection` parameter is required only when multiple brokers are configured. When only one broker is configured, the system uses it automatically. The `connection` attribute in XML configuration files is optional—omit it to use the default broker, or specify `connection="amqp"` or `connection="stomp"` to force a specific broker. + +### Update `queue_consumer.xml` files + +All `` attributes (`name`, `queue`, `handler`, `consumerInstance`, `maxMessages`) remain unchanged. The only difference is the `connection` attribute: + +| Attribute | Change in 2.4.5+ | +| --- | --- | +| `connection` | Now also supports `stomp` value. Optional in both versions—auto-detected from `env.php`. Specify explicitly to force a specific broker. | + +**2.4.4 Example:** + +```xml + +``` + +**2.4.5+ Example (Uses default broker from env.php):** + +```xml + +``` + +**2.4.5+ Example (Explicitly specifies broker):** + +```xml + + + + + +``` + +### Update `queue_publisher.xml` files + +The `topic` and `disabled` attributes remain unchanged. Key differences in 2.4.5+: + +| Attribute | Change in 2.4.5+ | +| --- | --- | +| `/queue` | New attribute for ActiveMQ Artemis | +| `/name` | Can now specify `stomp` for ActiveMQ | +| `/exchange` | Not used with STOMP connections | +| `/disabled` | Enhanced support for multiple connections | + +**2.4.4 Example (RabbitMQ only):** + +```xml + + + +``` + +**2.4.5+ Example (RabbitMQ):** + +```xml + + + + +``` + +**2.4.5+ Example (ActiveMQ Artemis):** + +```xml + + + + +``` + +### Update `queue_topology.xml` files + +All `` and `` attributes (`name`, `type`, `durable`, `autoDelete`, `id`, `topic`, `destinationType`, `destination`) remain unchanged. The only difference is the `connection` attribute: + +| Attribute | Change in 2.4.5+ | +| --- | --- | +| `connection` | Now also supports `stomp` value. Optional in both versions—auto-detected from `env.php`. Specify explicitly to force a specific broker. | + +**2.4.4 Example:** + +```xml + + + +``` + +**2.4.5+ Example (Uses default broker from env.php):** + +```xml + + + +``` + +**2.4.5+ Example (Explicitly specifies broker):** + +```xml + + + + + + + + + +``` + + + +Connection detection is dynamic based on your `env.php` configuration. In 2.4.5+, this detection supports both AMQP and STOMP, allowing you to omit connection declarations in XML files. + +## Legacy migrations + +The following sections document migration paths for older Adobe Commerce versions. These are provided for reference when upgrading from legacy installations. + +### Migrate from 2.1 to 2.2 + +To upgrade the message queues for Adobe Commerce or Magento Open Source 2.1, you must create the following files in the `/etc` directory for each module that will use the message queue framework. + +- `queue_consumer.xml`—Defines the relationship between an existing queue and its consumer. +- `queue_topology.xml`—Defines the message routing rules and declares queues and exchanges. +- `queue_publisher.xml`—Defines the exchange where a topic is published. + +The existing `queue.xml` file is deprecated. + +For complete details about these files, see [Configure message queues](configuration.md) + + + +The Adobe Commerce and Magento Open Source 2.1 `communication.xml` file has not changed for Adobe Commerce and Magento Open Source 2.2. + +#### Create the `queue_consumer.xml` file + +| 2.2 Attribute | 2.1 queue.xml source | +| --- | --- | +| `/name` | `//consumer` | +| `/queue` | `//name` | +| `/handler` | `//handler` | +| `/consumerInstance` | `//consumerInstance` | +| `/connection` | `/type` | +| `/maxMessages` | `//maxMessages` | + +#### Create the `queue_topology.xml` file + +| 2.2 Attribute | 2.1 queue.xml source | +| --- | --- | +| `/name` | `/exchange` | +| `/type` | Not present in 2.1. Set this value to `topic`. | +| `/connection` | `/type` | +| `/durable` | Not present in 2.1. Omit this parameter to accept the default value. | +| `/autoDelete` | Not present in 2.1. Omit this parameter to accept the default value. | +| `/internal` | Not present in 2.1. Omit this parameter to accept the default value. | +| `//id` | Not present in 2.1. Concatenate the 2.1 exchange name, topic name, and queue name to create a value for the `id` parameter. | +| `//topic` | `/topic` | +| `//destinationType` | Not present in 2.1. This value must be set to `queue`. | +| `//destination` | `//name` | +| `//disabled` | Not present in 2.1. Omit this parameter to accept the default value. | +| `/` and `//` | Not present in 2.1. Omit this element. | + +#### Create the `queue_publisher.xml` file + +| 2.2 Attribute | 2.1 queue.xml source | +| --- | --- | +| `/topic` | `/topic` | +| `/disabled` | Not present in 2.1. Omit this parameter to accept the default value. | +| `//name` | `/type` | +| `//exchange` | `/exchange` | +| `//disabled` | Not present in 2.1. Omit this parameter to accept the default value. | + +### Migrate from 2.0 to 2.2 + +To upgrade from Adobe Commerce or Magento Open Source 2.0, you must create the following files in the `/etc` directory for each module that will use the message queue framework. + +- `queue_consumer.xml` - Defines the relationship between an existing queue and its consumer. +- `queue_topology.xml`—Defines the message routing rules. +- `queue_publisher.xml`—Defines the relationship between a topic and its publisher. + +The existing `queue.xml` file is deprecated. + +For complete details about these files, see [Configure message queues](configuration.md) + +#### Create the `queue_consumer.xml` file + +| 2.2 Attribute | 2.0 queue.xml source | +| --- | --- | +| `/name` | `/name` | +| `/queue` | `/queue` | +| `/handler` | Use the values from `/class` and `/method` in the format `\Module\::`. | +| `/consumerInstance` | `/executor` | +| `/connection` | `/connection` | +| `/maxMessages` | `/max_messages` | + +#### Create the `queue_topology.xml` file + +| 2.2 Attribute | 2.0 queue.xml source | +| --- | --- | +| `/name` | `/exchange` | +| `/type` | Not present in 2.0. Set this value to `topic`. | +| `/connection` | `/connection` | +| `/durable` | Not present in 2.0. Omit this parameter to accept the default value. | +| `/autoDelete` | Not present in 2.0. Omit this parameter to accept the default value. | +| `/internal` | Not present in 2.0. Omit this parameter to accept the default value. | +| `//id` | Not present in 2.0. Concatenate the exchange name, topic name, and queue name to create a value for the `id` parameter. | +| `//topic` | `/topic` | +| `//destinationType` | Not present in 2.0. This value must be set to `queue`. | +| `//destination` | `/queue` | +| `//disabled` | Not present in 2.0. Omit this parameter to accept the default value. | +| `` | Not present in 2.0. Omit this element. | + +#### Create the `queue_publisher.xml` file + +| 2.2 Attribute | 2.0 queue.xml source | +| --- | --- | +| `/topic` | `/name` | +| `/disabled` | Not present in 2.0. Omit this parameter to accept the default value. | +| `//name` | `/connection` | +| `//exchange` | `/exchange` | +| `//disabled` | Not present in 2.0. Omit this parameter to accept the default value. | From e80edfdd21fde083d3096ef109240d9b2fff7667 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 21:35:12 -0600 Subject: [PATCH 34/43] Update index.md Refactor message queues doc for clarity and conciseness - Convert broker list to comparison table - Simplify consumer instantiation sections - Consolidate duplicate config examples into parameterized template - Add inline alert callout for MySQL scalability warning --- .../components/message-queues/index.md | 121 ++++++++---------- 1 file changed, 52 insertions(+), 69 deletions(-) diff --git a/src/pages/development/components/message-queues/index.md b/src/pages/development/components/message-queues/index.md index ffb1895b8..e0ed2451e 100644 --- a/src/pages/development/components/message-queues/index.md +++ b/src/pages/development/components/message-queues/index.md @@ -1,40 +1,57 @@ --- title: Message Queues | Commerce PHP Extensions -description: Review an introduction to the message queue system in Adobe Commerce and Magento Open Source. +description: Learn about the Message Queue Framework (MQF) for asynchronous communication in Adobe Commerce and how to configure different messaging brokers. +role: Admin, Developer keywords: - Extensions --- # Message queues -Message queues provide an asynchronous communications mechanism in which the sender and the receiver of a message do not contact each other, nor do they need to communicate with the message queue at the same time. When a sender places a message onto a queue, it is stored until the recipient receives them. +Message queues provide an asynchronous communications mechanism in which the sender and the receiver of a message do not contact each other directly. When a sender places a message onto a queue, the message is stored until the recipient receives it. -In Adobe Commerce and Magento Open Source, the Message Queue Framework (MQF) is a fully-functional system that allows a module to publish messages to queues. It also creates consumers to receive them asynchronously. The MQF supports multiple messaging brokers: +## Message Queue Framework overview -- **[RabbitMQ](http://www.rabbitmq.com)** - The primary messaging broker, which provides a scalable platform for sending and receiving messages. It includes a mechanism for storing undelivered messages and is based on the Advanced Message Queuing Protocol (AMQP) 0.9.1 specification. -- **[Apache ActiveMQ Artemis](https://activemq.apache.org/components/artemis/)** - An alternative messaging broker that uses STOMP (Simple Text Oriented Messaging Protocol) for reliable and scalable messaging, offering flexibility for STOMP-based integrations. +The Adobe Commerce Message Queue Framework (MQF) is a fully-functional system that allows a module to publish messages to queues and create consumers to receive them asynchronously. -A basic message queue system can also be set up without using external message brokers. In this system, a MySQL adapter stores messages in the database. Three database tables (`queue`, `queue_message`, and `queue_message_status`) manage the message queue workload. Cron jobs ensure the consumers are able to receive messages. This solution is not very scalable. External message brokers like RabbitMQ or ActiveMQ Artemis should be used whenever possible. +The MQF supports the following messaging brokers: + +| Broker | Protocol | Description | +| --- | --- | --- | +| [RabbitMQ](http://www.rabbitmq.com) | AMQP 0.9.1 | The primary messaging broker with a scalable platform for sending and receiving messages. Includes a mechanism for storing undelivered messages. | +| [Apache ActiveMQ Artemis](https://activemq.apache.org/components/artemis/) | STOMP | An alternative messaging broker using Simple Text Oriented Messaging Protocol (STOMP) for reliable and scalable messaging. | +| MySQL adapter | Database | A basic message queue system that stores messages in the database using three tables: `queue`, `queue_message`, and `queue_message_status`. Cron jobs ensure consumers receive messages. | + + + +The MySQL adapter is not scalable. Use an external message broker like RabbitMQ or ActiveMQ Artemis for production environments whenever possible. See [Configure message queues](configuration.md) for information about setting up the message queue system. -## Send a message from the publisher to a queue +## Publish messages to a queue -The following code sends a message to the queue. The `publish` method is defined in `PublisherInterface` +Use the `publish` method defined in `PublisherInterface` to send a message to the queue: ```php -$publisher->publish($topic, $message) +$publisher->publish($topic, $message); ``` -In a MySQL adapter environment, a message that is published to multiple queues creates a single record in `queue_message` and multiple records in `queue_message_status`: one for each queue. (A join on the `queue`, `queue_message`, and `queue_message_status` tables is required). +When using the MySQL adapter, a message published to multiple queues creates: + +- A single record in `queue_message` +- Multiple records in `queue_message_status` (one for each queue) + +Retrieving these messages requires a join on the `queue`, `queue_message`, and `queue_message_status` tables. -## Instantiate a consumer +## Instantiate consumers -The procedure for instantiating a consumer differs, depending on which message queue system is being used. +The procedure for instantiating a consumer differs depending on the message queue system. -### RabbitMQ +### RabbitMQ and ActiveMQ Artemis -This instantiates a consumer that is defined in a [`queue_consumer.xml`](configuration.md#queue_consumerxml) file. The consumer (`customer_created_listener`) listens to the queue and receives all new messages. For every message, it invokes `Magento\Some\Class::processMessage($message)` +For external brokers, consumers are defined in a [`queue_consumer.xml`](configuration.md#queue_consumerxml) file. The consumer listens to the queue, receives messages, and invokes a callback method for each one. + +The following example instantiates the `customer_created_listener` consumer, which calls `Magento\Some\Class::processMessage($message)` for each message: ```php $this->consumerFactory->get('customer_created_listener') @@ -43,36 +60,37 @@ $this->consumerFactory->get('customer_created_listener') ### MySQL adapter -Implement `\Magento\Framework\MessageQueue\ConsumerInterface::process($maxNumberOfMessages)` to instantiate a consumer. - -Perform the following actions: +For the MySQL adapter, implement `ConsumerInterface::process($maxNumberOfMessages)` and perform the following steps: -1. Define the queue name associated with current consumer using `\Magento\Framework\MessageQueue\ConsumerConfigurationInterface::getQueueName`. -1. Select `$maxNumberOfMessages` message records, filtering on the `queue_name` field. You must join on all 3 tables. To accomplish this, you may want to extract fewer records at a time to improve load distribution between multiple consumers. -1. Decode the message using topic name taken from the `\Magento\Framework\MessageQueue\ConsumerConfigurationInterface`. -1. Invoke callback `Magento\Framework\MessageQueue\ConsumerConfigurationInterface::getCallback` and pass the decoded data as an argument. +1. Get the queue name using `ConsumerConfigurationInterface::getQueueName`. +1. Select `$maxNumberOfMessages` records, filtering on `queue_name`. Join all three tables (`queue`, `queue_message`, `queue_message_status`). Extract fewer records at a time to improve load distribution across consumers. +1. Decode the message using the topic name from `ConsumerConfigurationInterface`. +1. Invoke `ConsumerConfigurationInterface::getCallback` with the decoded data. -### ActiveMQ Artemis (STOMP) +## Switch from MySQL to an external broker -Similar to RabbitMQ, ActiveMQ Artemis instantiates a consumer that is defined in a [`queue_consumer.xml`](configuration.md#queue_consumerxml) file. The consumer (`customer_created_listener`) listens to the queue and receives all new messages. For every message, it invokes `Magento\Some\Class::processMessage($message)` +You can switch from the MySQL adapter to an external message broker by adding runtime configuration to redefine the adapter for a topic. The configuration disables the `db` connection and enables the external broker connection. -## Change message queue from MySQL to external brokers +The following example shows how to switch a topic to an external broker. Replace the placeholder values based on your broker: -The following sample introduces a runtime configuration that allows you to redefine the adapter for a topic. +| Broker | Publisher value | Connection name | +| --- | --- | --- | +| RabbitMQ | `amqp-magento` | `amqp` | +| ActiveMQ Artemis | `stomp-magento` | `stomp` | ```php 'queue' => [ 'topics' => [ - 'product_action_attribute.update' => [ - 'publisher' => 'amqp-magento' + '' => [ + 'publisher' => '' ] ], 'config' => [ 'publishers' => [ - 'product_action_attribute.update' => [ + '' => [ 'connections' => [ - 'amqp' => [ - 'name' => 'amqp', + '' => [ + 'name' => '', 'exchange' => 'magento', 'disabled' => false ], @@ -86,46 +104,11 @@ The following sample introduces a runtime configuration that allows you to redef ] ], 'consumers' => [ - 'product_action_attribute.update' => [ - 'connection' => 'amqp', - ], - ], -], -``` - -### Switch from MySQL to STOMP (ActiveMQ Artemis) - -The following configuration shows how to configure a topic to use STOMP instead of MySQL: - -```php -'queue' => [ - 'topics' => [ - 'inventory.update' => [ - 'publisher' => 'stomp-magento' - ] - ], - 'config' => [ - 'publishers' => [ - 'inventory.update' => [ - 'connections' => [ - 'stomp' => [ - 'name' => 'stomp', - 'exchange' => 'magento', - 'disabled' => false - ], - 'db' => [ - 'name' => 'db', - 'exchange' => 'magento', - 'disabled' => true - ] - ] - ] + '' => [ + 'connection' => '', ] - ], - 'consumers' => [ - 'inventory.update' => [ - 'connection' => 'stomp', - ], ] ], ``` + +For example, to switch the `product_action_attribute.update` topic to RabbitMQ, use `amqp-magento` as the publisher and `amqp` as the connection name. From 1b51a6f871641e71963a1b9662206843c9ee5ffa Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 21:40:44 -0600 Subject: [PATCH 35/43] Rename required to migration.md Fix filename --- .../components/message-queues/{required => migration.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/pages/development/components/message-queues/{required => migration.md} (100%) diff --git a/src/pages/development/components/message-queues/required b/src/pages/development/components/message-queues/migration.md similarity index 100% rename from src/pages/development/components/message-queues/required rename to src/pages/development/components/message-queues/migration.md From ad7fce2ca2dcbb21bd10cee42b0c299186111f20 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 21:43:58 -0600 Subject: [PATCH 36/43] Rename `consumer` element to configuration.md --- .../message-queues/{`consumer` element => configuration.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/pages/development/components/message-queues/{`consumer` element => configuration.md} (100%) diff --git a/src/pages/development/components/message-queues/`consumer` element b/src/pages/development/components/message-queues/configuration.md similarity index 100% rename from src/pages/development/components/message-queues/`consumer` element rename to src/pages/development/components/message-queues/configuration.md From 62a7f8bff2ef39037010ed23b0e90f6557049ad7 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 22:17:13 -0600 Subject: [PATCH 37/43] Update bulk-operations-example.md Refactor bulk-operations-example documentation - Update frontmatter description to be action-oriented - Simplify section introductions and descriptions - Remove redundant "Create" prefix from XML config subsections - Fix grammar in cross-reference link text - Merge two InlineAlert blocks into single consolidated note --- .../message-queues/bulk-operations-example.md | 74 +++++++++---------- 1 file changed, 36 insertions(+), 38 deletions(-) diff --git a/src/pages/development/components/message-queues/bulk-operations-example.md b/src/pages/development/components/message-queues/bulk-operations-example.md index 6ff437da2..5c4249746 100644 --- a/src/pages/development/components/message-queues/bulk-operations-example.md +++ b/src/pages/development/components/message-queues/bulk-operations-example.md @@ -1,27 +1,29 @@ --- -title: Bulk operations implementation | Commerce PHP Extensions -description: Use this example to create your own bulk operation in Adobe Commerce or Magento Open Source. +title: Example bulk operations implementation | Commerce PHP Extensions +description: Learn how to implement bulk operations for asynchronous processing in Adobe Commerce. keywords: - Extensions --- # Example bulk operations implementation -This document describes how bulk operations can be implemented. There are three primary tasks to accomplish this: +This topic explains how to implement bulk operations in Adobe Commerce. Bulk operations allow you to process large sets of data asynchronously using message queues. -* Create a publisher that sends messages to the message queue -* Create a consumer that receives and processes messages -* Configure the message queues +Implementation requires three components: + +* **Publisher** - Sends messages to the message queue +* **Consumer** - Receives and processes messages from the queue +* **Message queue configuration** - Defines the queue topology and routing ## Create a publisher -A publisher is responsible for scheduling a bulk operation that performs the following tasks: +The publisher schedules bulk operations by performing these tasks: -* Generate a bulkUuid for each operation -* Publish each operation to the message queue -* Track and report the status of each operation +* Generating a unique `bulkUuid` for the operation +* Publishing each operation to the message queue +* Tracking and reporting operation status -The following example defines a publisher that implements these responsibilities. +The following example demonstrates a publisher implementation: ```php //etc` directory. +Configure the message queue topology by creating or editing the following files in the `app/code///etc` directory: -* `communication.xml` -* `di.xml` -* `queue_consumer.xml` -* `queue_publisher.xml` -* `queue_topology.xml` +* `communication.xml` +* `di.xml` +* `queue_consumer.xml` +* `queue_publisher.xml` +* `queue_topology.xml` -For more information about the `di.xml` file, see [Dependency Injection](../dependency-injection.md). For information the other files, see [Configure message queues](configuration.md). +For more information about `di.xml`, see [Dependency Injection](../dependency-injection.md). For information about the other files, see [Configure message queues](configuration.md). -### Create `communication.xml` +### communication.xml -The `communication.xml` file defines aspects of the message queue system that apply to all topics for the module. Create this file with the following contents: +The `communication.xml` file defines message queue topics for the module: ```xml @@ -303,9 +305,9 @@ The `communication.xml` file defines aspects of the message queue system that ap ``` -### Create `di.xml` +### di.xml -Add the following type to the module's `di.xml` file. +Add the following type to the module's `di.xml` file: ```xml @@ -317,9 +319,9 @@ Add the following type to the module's `di.xml` file. ``` -### Create `queue_consumer.xml` +### queue_consumer.xml -The `queue_consumer.xml` file defines the relationship between a queue and its consumer. Create this file with the following contents: +The `queue_consumer.xml` file defines the relationship between a queue and its consumer: ```xml @@ -327,13 +329,13 @@ The `queue_consumer.xml` file defines the relationship between a queue and its c ``` -The connection name (AMQP or STOMP) is determined automatically based on the configuration in the `env.php` file. +The connection type (AMQP or STOMP) is determined automatically from the `env.php` configuration. -### Create `queue_publisher.xml` +### queue_publisher.xml -The `queue_publisher.xml` file defines the exchange where a topic is published. Create this file with the following contents: +The `queue_publisher.xml` file defines the exchange where a topic is published. -**For RabbitMQ (AMQP):** +**RabbitMQ (AMQP):** ```xml @@ -343,7 +345,7 @@ The `queue_publisher.xml` file defines the exchange where a topic is published. ``` -**For ActiveMQ Artemis (STOMP):** +**ActiveMQ Artemis (STOMP):** ```xml @@ -353,11 +355,11 @@ The `queue_publisher.xml` file defines the exchange where a topic is published. -For ActiveMQ Artemis, the `` element is not required because the connection type is determined by the configuration in the `env.php` file. If the topic name and queue name differ, you must specify the `queue` attribute in the `` element. +For ActiveMQ Artemis, the `` element is not required because the connection type is determined from `env.php`. If the topic name and queue name differ, specify the `queue` attribute in the `` element. -### Create `queue_topology.xml` +### queue_topology.xml -The `queue_topology.xml` file defines the message routing rules and declares queues and exchanges. Create this file with the following content: +The `queue_topology.xml` file defines message routing rules and declares queues and exchanges: ```xml @@ -369,8 +371,4 @@ The `queue_topology.xml` file defines the message routing rules and declares que -Message queue connections are resolved dynamically from the deployment configuration in the `env.php` file. If the queue is configured to use AMQP or STOMP, the corresponding connection is applied. Otherwise, the database connection is used. Therefore, when AMQP or STOMP is specified in the deployment configuration, you can omit connection declarations from `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml` files.(See [Message queue configuration files](./configuration.md). - - - -ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.5 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. +Message queue connections are resolved dynamically from `env.php`. When AMQP or STOMP is configured, the corresponding connection is applied; otherwise, the database connection is used. You can omit connection declarations from `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml` when using AMQP or STOMP. ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.5 and uses ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. See [Message queue configuration files](configuration.md). From ec6fe8a3e5a84ab99c465f9af26e54cc95a1a904 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 22:23:34 -0600 Subject: [PATCH 38/43] Update async-configuration.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refactor async-configuration.md for clarity and consistency - Fix typos: ampqp→amqp, queue_customer→queue_consumer - Correct heading hierarchy for queue_topology.xml section - Remove redundant config file listing in introduction - Improve sentence structure and documentation style --- .../message-queues/async-configuration.md | 31 ++++++++----------- 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index 9a9d10d48..9cc1c0c5d 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -1,6 +1,6 @@ --- title: Asynchronous Configuration | Commerce PHP Extensions -description: Learn about the important configuration files that you must configure in your Adobe commerce and Magento Open Source extensions. +description: Learn about the message queue configuration files for asynchronous and bulk API operations in Adobe Commerce. contributor_name: comwrap GmbH contributor_link: https://www.comwrap.com keywords: @@ -9,21 +9,16 @@ keywords: # Asynchronous configuration -When using the message queue, four configuration files in your component must be updated: +When using the message queue, four configuration files are required in your component: -* communication.xml -* queue_consumer.xml -* queue_topology.xml -* queue_publisher.xml +* `communication.xml` +* `queue_consumer.xml` +* `queue_topology.xml` +* `queue_publisher.xml` -More information can be found in [Configure message queues](configuration.md). +For more information, see [Configure message queues](configuration.md). -Asynchronous and Bulk APIs are built on top of the usual REST API and use the Message Queue Framework for processing messages. To ease development efforts, the Asynchronous API pre-generates the following configuration files: - -* communication.xml -* queue_publisher.xml - -and provides the `queue_topology.xml` and `queue_consumer.xml` files within the `Magento/WebapiAsync` module. +Asynchronous and Bulk APIs are built on top of the REST API and use the Message Queue Framework for processing messages. To simplify development, the Asynchronous API auto-generates `communication.xml` and `queue_publisher.xml`. The `Magento/WebapiAsync` module provides `queue_topology.xml` and `queue_consumer.xml`. ## communication.xml @@ -46,7 +41,7 @@ The `queue_publisher.xml` file is generated by the `\Magento\WebapiAsync\Code\Ge The sort order is set to 0 and allows developers to change some aspects of the generated configuration in configuration readers such as `queue_publisher.xml` and `env.php`. -`\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of REST API routes that can be executed asynchronously. Then, it dynamically resolves the connection name (`db` (default), `ampqp` or `stomp` for ActiveMQ Artemis) based on the `env.php` deployment configuration and defines the exchange as `magento` for each generated topic name. +The `\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` method calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of REST API routes that can be executed asynchronously. It then dynamically resolves the connection name (`db` (default), `amqp`, or `stomp` for ActiveMQ Artemis) based on the `env.php` deployment configuration and defines the exchange as `magento` for each generated topic name. ## queue_consumer.xml @@ -59,9 +54,9 @@ The asynchronous/bulk API has one defined consumer which processes all asynchron The connection type (AMQP or STOMP) is determined automatically based on your `env.php` configuration. -### queue_topology.xml +## queue_topology.xml -The message queue topology configuration links all auto-generated topic names with prefix `async.` to the `magento` exchange and defines the queue named `async.operations.all` as the destination for all messages. +The message queue topology configuration links all auto-generated topic names with the `async.` prefix to the `magento` exchange. It defines the queue named `async.operations.all` as the destination for all messages. ```xml @@ -71,8 +66,8 @@ The message queue topology configuration links all auto-generated topic names wi -The message queues connection is defined dynamically based on deployment configuration in `env.php`. If AMQP or STOMP is configured in the deployment configuration for the queue, the respective connection is used. Otherwise, the database connection is used. Because the connection is resolved using the configuration, explicit declarations are unnecessary in the [message queue configuration files](./configuration.md): `queue_customer.xml`, `queue_publisher.xml`, `queue_topology.xml`. +The message queue connection is defined dynamically based on the deployment configuration in `env.php`. If AMQP or STOMP is configured for the queue, that connection is used. Otherwise, the database connection is used. Because the connection is resolved dynamically, explicit declarations are unnecessary in the [message queue configuration files](./configuration.md): `queue_consumer.xml`, `queue_publisher.xml`, `queue_topology.xml`. -ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.5 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. +ActiveMQ Artemis (STOMP) support was introduced in Adobe Commerce 2.4.5. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. From 12fd22caed4aa1e4e46f73dd612d2db519384aa7 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Mon, 2 Feb 2026 22:37:54 -0600 Subject: [PATCH 39/43] Update configuration.md Fix markdown error. --- src/pages/development/components/message-queues/configuration.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index 0e48085e3..d04654bca 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -244,7 +244,6 @@ The `queue_publisher.xml` file defines which connection and exchange to use to p The `connection` element is a subnode of the `publisher` element. Only one enabled connection can be defined for a publisher at any given time. If you omit the `connection` element, the connection is resolved automatically and `magento` is used as the exchange. See [Connection resolution](#connection-resolution). - | Attribute | Description | | --- | --- | | `name` | The connection name. For explicit values, use `amqp`, `stomp`, or `db`. See [Connection resolution](#connection-resolution). | From 6944d9e645ddf7fe7b936ebd3714dc8e410426a1 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Tue, 3 Feb 2026 05:00:43 -0600 Subject: [PATCH 40/43] Update bulk-operations-example.md --- .../components/message-queues/bulk-operations-example.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/bulk-operations-example.md b/src/pages/development/components/message-queues/bulk-operations-example.md index 5c4249746..cbbaa0c9c 100644 --- a/src/pages/development/components/message-queues/bulk-operations-example.md +++ b/src/pages/development/components/message-queues/bulk-operations-example.md @@ -1,5 +1,5 @@ --- -title: Example bulk operations implementation | Commerce PHP Extensions +title: Example bulk operations implementation description: Learn how to implement bulk operations for asynchronous processing in Adobe Commerce. keywords: - Extensions From 88084e83e6cfe7d6d15c9d9228f91a9d392a5c7c Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Tue, 3 Feb 2026 05:01:54 -0600 Subject: [PATCH 41/43] Update migration.md --- src/pages/development/components/message-queues/migration.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/pages/development/components/message-queues/migration.md b/src/pages/development/components/message-queues/migration.md index 8b500cf91..9a9a1c2e3 100644 --- a/src/pages/development/components/message-queues/migration.md +++ b/src/pages/development/components/message-queues/migration.md @@ -3,8 +3,6 @@ title: Migrate message queue configuration description: Learn how to migrate message queue configuration between Adobe Commerce versions, including support for RabbitMQ (AMQP) and ActiveMQ Artemis (STOMP). keywords: - Configuration - - Message Queue - - Migration --- # Migrate message queue configuration From e179ca1f3f1c595923b857b46216836cff2cd82e Mon Sep 17 00:00:00 2001 From: "sandesh.as" Date: Wed, 4 Feb 2026 14:11:44 +0530 Subject: [PATCH 42/43] AC-16115: Adobe Development Doc - Message Queues - ActiveMq (Artemis) updates 2.4.5 --- .../message-queues/bulk-operations-example.md | 15 +++- .../message-queues/configuration.md | 82 +++++++++++++++++++ 2 files changed, 94 insertions(+), 3 deletions(-) diff --git a/src/pages/development/components/message-queues/bulk-operations-example.md b/src/pages/development/components/message-queues/bulk-operations-example.md index cbbaa0c9c..1cfcd1022 100644 --- a/src/pages/development/components/message-queues/bulk-operations-example.md +++ b/src/pages/development/components/message-queues/bulk-operations-example.md @@ -335,17 +335,26 @@ The connection type (AMQP or STOMP) is determined automatically from the `env.ph The `queue_publisher.xml` file defines the exchange where a topic is published. -**RabbitMQ (AMQP):** +**For RabbitMQ (AMQP):** + +```xml + + + + +``` + +Alternatively, you can explicitly specify the connection and exchange: ```xml - /> + ``` -**ActiveMQ Artemis (STOMP):** +**For ActiveMQ Artemis (STOMP):** ```xml diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index d04654bca..dfe6d258d 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -324,6 +324,88 @@ The default global value is `1`. To override for a specific consumer, set the `o * **Infrequent consumers**—Combine `onlySpawnWhenMessageAvailable` with `maxIdleTime`. The consumer spawns only when needed and terminates after a period of inactivity. * **Resource optimization**—Combine the global `only_spawn_when_message_available` setting with `consumers-wait-for-messages` set to `false`. Consumers run only when messages exist and exit when the queue is empty. +## `env.php` Configuration + +The message queue connection configuration is defined in the `app/etc/env.php` file. When `connection` elements are omitted from `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml` files, the system automatically uses the connection configured in `env.php`. + +### Example configurations + +**For RabbitMQ (AMQP) only:** + +```php +return [ + // ... other configuration + 'queue' => [ + 'amqp' => [ + 'host' => 'localhost', + 'port' => '5672', + 'user' => 'guest', + 'password' => 'guest', + 'virtualhost' => '/' + ], + 'consumers_wait_for_messages' => 1 + ] +]; +``` + +**For ActiveMQ Artemis (STOMP) only:** + +```php +return [ + // ... other configuration + 'queue' => [ + 'stomp' => [ + 'host' => 'localhost', + 'port' => '61613', + 'user' => 'admin', + 'password' => 'admin' + ], + 'consumers_wait_for_messages' => 1 + ] +]; +``` + +**For MySQL (Database) only:** + +```php +return [ + // ... other configuration + 'queue' => [ + 'consumers_wait_for_messages' => 1 + ] + // Database connection uses existing 'db' configuration +]; +``` + +**When multiple connection types are configured:** + +If you have both AMQP and STOMP configured, you must specify `default_connection` to indicate which one the system should use: + +```php +return [ + // ... other configuration + 'queue' => [ + 'amqp' => [ + 'host' => 'localhost', + 'port' => '5672', + 'user' => 'guest', + 'password' => 'guest', + 'virtualhost' => '/' + ], + 'stomp' => [ + 'host' => 'localhost', + 'port' => '61613', + 'user' => 'admin', + 'password' => 'admin' + ], + 'default_connection' => 'amqp', // Required when multiple connections exist + 'consumers_wait_for_messages' => 1 + ] +]; +``` + +The `default_connection` value can be `db`, `amqp`, or `stomp`. When only one connection type is configured in `env.php`, the system automatically uses that connection and `default_connection` is not required. If `queue/default_connection` is specified, that connection is used for all message queues unless a specific connection is defined in a module's `queue_topology.xml`, `queue_publisher.xml`, or `queue_consumer.xml` file. + ## ActiveMQ Artemis (STOMP) support From 71f46db99066578d00ef92db7b9da9e96d554487 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Thu, 5 Feb 2026 11:05:01 -0600 Subject: [PATCH 43/43] Update src/pages/development/components/message-queues/configuration.md --- .../development/components/message-queues/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index dfe6d258d..8aa9204bb 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -246,7 +246,7 @@ The `connection` element is a subnode of the `publisher` element. Only one enabl | Attribute | Description | | --- | --- | -| `name` | The connection name. For explicit values, use `amqp`, `stomp`, or `db`. See [Connection resolution](#connection-resolution). | +| `name` | The connection name. For explicit values, use `amqp`, `stomp`, or `db`. If you omit the `connection` element, the [connection is resolved automatically](#connection-resolution). | `exchange` | The name of the exchange to publish to. The default system exchange name is `magento`. | | `disabled` | Determines whether this queue is disabled. The default value is `false`. |