Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Configuring Event Message Channels

Configuring Event Message Channels

Overview

By default, Elastic Path Commerce publishes event messages to ActiveMQ virtual destinations, which is also called Virtual Topics, with separate consumer queues for each function that wants to get the message. This method supports competing consumers, does not lose messages if subscribers are offline, and does not require configuration on ActiveMQ for both development and production.

The recommended approaches to configure event message channels are:
  • Use ActiveMQ virtual destinations. This is the default method and Elastic Path recommends this method when using ActiveMQ.
  • Implement a recipient list consumer to forward messages to multiple queues. Elastic Path recommends this method when virtual destinations are unavailable.

Virtual Destinations

The advantages of virtual destinations are decoupled publisher/subscriber architecture and reliable load-balancing of message processors.

The following example demonstrates a cluster of two identical integration servers, integration server1 and integration server 2, where each contains two JMS consumers A and B that subscribe to the order message channel:


Virtual Topic example

To utilize virtual destinations, register each subscriber component within the Commerce Engine as an individual output queue within the virtual topic. For example, to accommodate the message consumer that creates order confirmation emails and the message consumer that creates order shipment confirmation emails, the order message channel is configured with a producer topic of VirtualTopic.ep.orders and multiple consumer queues including Consumer.orderconfirmationEmailHandler.VirtualTopic.ep.orders and Consumer.orderShipmentShippedEmailHandler.VirtualTopic.ep.orders. Each of these consumers exist as a JMS queue to which all messages on the VirtualTopic.ep.orders topic are published.

Be default, Elastic Path uses ActiveMQ default naming conventions to enable Virtual Destinations. For other messaging brokers, Virtual Destinations might need different configuration. For more information, see the documentation for the specific messaging broker.

Configuration of Virtual Destination Queues

The following table provides the default Elastic Path configuration of the event message channels to enable ActiveMQ Virtual Destinations:

Table 1.
Producer Description Setting Producer URI(Default Value) Subscriber Description Context Consumer URL(Context Value)
Change Set Event Messages COMMERCE/SYSTEM/MESSAGING/CHANGESETS/channelUri jms:queue:ep.changesets N/A N/A (This queue is not configured with Virtual Destinations by default since there is only one anticipated consumer.) N/A
Commerce Manager User Event Messages COMMERCE/SYSTEM/MESSAGING/CMUSERS/channelUri jms:topic:VirtualTopic.ep.cmusers CM User Created Email handler cmUserCreatedEmailHandler jms:queue:Consumer.cmUserCreatedEmailHandler.VirtualTopic.ep.cmusers
Commerce Manager User Events COMMERCE/SYSTEM/MESSAGING/CMUSERS/channelUri jms:topic:VirtualTopic.ep.cmusers CM User Password Changed Email handler cmUserPasswordChangedEmailHandler jms:queue:Consumer.cmUserPasswordChangedEmailHandler.VirtualTopic.ep.cmusers
Commerce Manager User Event Messages COMMERCE/SYSTEM/MESSAGING/CMUSERS/channelUri jms:topic:VirtualTopic.ep.cmusers CM User Password Reset Email handler cmUserPasswordResetEmailHandler jms:queue:Consumer.cmUserPasswordResetEmailHandler.VirtualTopic.ep.cmusers
Customer Event Messages COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri jms:topic:VirtualTopic.ep.customers Anonymous Customer Registration Email handler anonymousCustomerRegisteredEmailHandler jms:queue:Consumer.anonymousCustomerRegisteredEmailHandler.VirtualTopic.ep.customers
Customer Event Messages COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri jms:topic:VirtualTopic.ep.customers Customer Registration Email handler customerRegistrationEmailHandler jms:queue:Consumer.customerRegistrationEmailHandler.VirtualTopic.ep.customers
Customer Event Messages COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri jms:topic:VirtualTopic.ep.customers CM User Password Changed Email handler passwordChangedEmailHandler jms:queue:Consumer.passwordChangedEmailHandler.VirtualTopic.ep.customers
Customer Event Messages COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri ms:topic:VirtualTopic.ep.customers Customer Password Forgotten Email handler passwordForgottenEmailHandler jms:queue:Consumer.passwordForgottenEmailHandler.VirtualTopic.ep.customers
Customer Event Messages COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri jms:topic:VirtualTopic.ep.customers Shared Wish List Email handler wishListSharedEmailHandler jms:queue:Consumer.wishListSharedEmailHandler.VirtualTopic.ep.customers
Data Import Event Messages COMMERCE/SYSTEM/MESSAGING/DATAIMPORT/channelUri jms:topic:VirtualTopic.ep.dataimport CSV Import Job Completed Email handler importJobCompletedEmailHandler jms:queue:Consumer.importJobCompletedEmailHandler.VirtualTopic.ep.dataimport
Gift Certificate Event Messages COMMERCE/SYSTEM/MESSAGING/GIFTCERTIFICATES/channelUri jms:topic:VirtualTopic.ep.giftcertificates Gift Certificate Purchased Email handler giftCertificateCreatedEmailHandler jms:queue:Consumer.giftCertificateCreatedEmailHandler.VirtualTopic.ep.giftcertificates
Order Event Messages COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri jms:topic:VirtualTopic.ep.orders Gift Certificate Purchased handler giftCertificateCreatedMessageProducer jms:queue:Consumer.giftCertificateCreatedMessageProducer.VirtualTopic.ep.orders
Order Event Messages COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri jms:topic:VirtualTopic.ep.orders Order Confirmation Email handler orderConfirmationEmailHandler jms:queue:Consumer.orderConfirmationEmailHandler.VirtualTopic.ep.orders
Order Event Messages COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri jms:topic:VirtualTopic.ep.orders Order Shipment Created handler orderShipmentCreatedMessageProducer jms:queue:Consumer.orderShipmentCreatedMessageProducer.VirtualTopic.ep.orders
Order Event Messages COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri jms:topic:VirtualTopic.ep.orders Order Shipment Release Failed Email handler orderShipmentReleaseFailedEmailHandler jms:queue:Consumer.orderShipmentReleaseFailedEmailHandler.VirtualTopic.ep.orders
Order Event Messages COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri jms:topic:VirtualTopic.ep.orders Order Shipment Shipped Email handler orderShipmentShippedEmailHandler jms:queue:Consumer.orderShipmentShippedEmailHandler.VirtualTopic.ep.orders
Order Event Messages COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri jms:topic:VirtualTopic.ep.orders Return or Exchange Email handler returnExchangeEmailHandler jms:queue:Consumer.returnExchangeEmailHandler.VirtualTopic.ep.orders
For sample queue names, see sample context values in the table. Elastic Path uses ActiveMQ default naming conventions to enable Virtual Destinations, but other brokers might need to be configured differently.

Recipient List Message Forwarder

If the JMS broker doesn't support virtual destinations, you can implement a recipient list consumer to replicate the functionality of virtual destinations. You must configure the recipient list with a list of the output JMS queue endpoints and publish all messages on the incoming queue to each of the required queues. In the following example, each recipient list consumer forwards every incoming message on the ep.orders queue to ep.orders.A and ep.orders.B queues.


Recipient List

Configuration of Recipient List

For the recipient list consumer, follow the same configuration settings of virtual destinations as described in the virtual destinations section except for the producer URI by defining it as queues instead of topics. You can also remove the VirtualTopic and Consumer prefixes, because Elastic Path does not follow naming convention to define this functionality.

Recipient List Consumer Sample Implementation

The following example describes a sample recipient list message forwarding route builder and its Spring XML configuration:

public class SampleRecipientListMessageForwardingRouteBuilder extends RouteBuilder {
 
	private Endpoint incomingEndpoint;
	private Collection<Endpoint> outgoingEndpoints;

	@Override
	public void configure() throws Exception {
		from(incomingEndpoint)
			.transacted()
			.to(outgoingEndpoints);
	}
 
	// getters and setters
 
}
<beans
        xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:camel="http://camel.apache.org/schema/spring"
		xmlns:util="http://www.springframework.org/schema/util"
        xsi:schemaLocation="
                http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.0.xsd
				http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.0.xsd
                http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
        ">
 
    <camel:camelContext id="sample-recipient-list-forwarder" xmlns="http://camel.apache.org/schema/spring">
		<routeBuilder ref="sampleRecipientListMessageForwardingRouteBuilder"/commerce-legacy/>
    </camel:camelContext>
  
	<bean id="sampleRecipientListMessageForwardingRouteBuilder" class="com.example.SampleRecipientListMessageForwardingRouteBuilder">
		<property name="incomingEndpoint">
			<bean class="org.apache.camel.spring.CamelEndpointFactoryBean">
				<property name="camelContextId" value="sample-recipient-list-forwarder" />
				<property name="uri" value="jms:ep.eventmessagetype"/commerce-legacy/>
			</bean>
		</property>
		<property name="outgoingEndpoints">
			<util:list>
				<bean class="org.apache.camel.spring.CamelEndpointFactoryBean">
					<property name="camelContextId" value="sample-recipient-list-forwarder" />
					<property name="uri" value="jms:ep.eventmessagetype.Queue1"/commerce-legacy/>
				</bean>
				<bean class="org.apache.camel.spring.CamelEndpointFactoryBean">
					<property name="camelContextId" value="sample-recipient-list-forwarder" />
					<property name="uri" value="jms:ep.eventmessagetype.Queue2"/commerce-legacy/>
				</bean>
				<bean class="org.apache.camel.spring.CamelEndpointFactoryBean">
					<property name="camelContextId" value="sample-recipient-list-forwarder" />
					<property name="uri" value="jms:ep.eventmessagetype.Queue3"/commerce-legacy/>
				</bean>
				<!-- etc. -->
			</util:list>
		</property>
	</bean>
 
</beans>


The outgoing queues for each Commerce Engine event message channel are listed in the virtual destination configuration table.