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, the Elastic Path Commerce publishes event messages to JMS Topics and consumes them using nondurable subscribers. This is ideal for development purposes as it requires no configuration. However, this configuration will cause messages to be lost if the subscribers are offline, making it not ideal for production.

In production, you can use one of the following consumption approaches, each with varying benefits:

  1. Configure the event message consumers to be Durable Subscribers
  2. Use virtual destinations (recommended when available)
  3. Implement a recipient list consumer to forward messages to multiple queues (recommended when virtual destinations not available)

Durable Subscribers

You can configure the subscribers to your JMS topics so that subscribers are durable, which allows subscribers to still receive messages while offline. However, durable subscribers don't support competing consumers. This means running multiple instances of each JMS consumer application will result in each message being processed multiple times. For this reason, when using durable subscribers, we advise you to run only a single instance of each JMS consumer application. Consider the other approaches if you want to run multiple instances of each JMS consumer application.

To configure a durable subscriber, you'll need to set two additional identifiers: A clientId, which is a unique identifier at the application level, and a durableSubscriptionName, which identifies each topic subscription.

clientId

The application-level client ID can be configured by overriding the jmsConfig Spring bean in your extension project and adding an additional clientId property.

<bean id="jmsConfig" parent="jmsConfigTemplate">
	<property name="clientId" value="YOUR_APPLICATION_CLIENT_IDENTIFIER"/>
</bean>

durableSubscriptionName

Each topic subscription requires a unique identifier as the application may have multiple subscriptions to the same topic for different purposes. For example, the Commerce Engine has one subscriber to the "ep.orders" topic that sends order confirmation emails, and another subscriber to the same topic that sends order shipment confirmation emails. To use durable subscribers, each of these subscribers must supply a unique durableSubscriptionName.

To add thedurableSubscriptionName property, append it to the Endpoint URI definition as a query parameter in the format jms:topic:ep.messagetopic?durableSubscriptionName=mySubscriber.

You can configure the existing subscribers in the Commerce Engine to support a durableSubscriptionName by adding a context to the relevant settings framework value.

Configuration(durable subscribers)

The following table shows the necessary configuration to utilize durable subscribers with all of the default Commerce Engine message consumers. Note that these context values do not exist by default and will have be created.

Subscriber Setting Context Sample value
CM User Created Email handler COMMERCE/SYSTEM/MESSAGING/CMUSERS/channelUri cmUserCreatedEmailHandler jms:topic:ep.cmusers?durableSubscriptionName=cmUserCreatedEmailHandler
CM User Password Changed Email handler COMMERCE/SYSTEM/MESSAGING/CMUSERS/channelUri cmUserPasswordChangedEmailHandler jms:topic:ep.cmusers?durableSubscriptionName=cmUserPasswordChangedEmailHandler
CM User Password Reset Email handler COMMERCE/SYSTEM/MESSAGING/CMUSERS/channelUri cmUserPasswordResetEmailHandler jms:topic:ep.cmusers?durableSubscriptionName=cmUserPasswordResetEmailHandler
Anonymous Customer Registration Email handler COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri anonymousCustomerRegisteredEmailHandler jms:topic:ep.customers?durableSubscriptionName=anonymousCustomerRegisteredEmailHandler
Customer Registration Email handler COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri customerRegistrationEmailHandler jms:topic:ep.customers?durableSubscriptionName=customerRegistrationEmailHandler
Customer Password Change Email handler COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri passwordChangedEmailHandler jms:topic:ep.customers?durableSubscriptionName=passwordChangedEmailHandler
Customer Password Forgotten Email handler COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri passwordForgottenEmailHandler jms:topic:ep.customers?durableSubscriptionName=passwordForgottenEmailHandler
Shared Wish List Email handler COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri wishListSharedEmailHandler jms:topic:ep.customers?durableSubscriptionName=wishListSharedEmailHandler
CSV Import Job Completed Email handler COMMERCE/SYSTEM/MESSAGING/DATAIMPORT/channelUri importJobCompletedEmailHandler jms:topic:ep.dataimport?durableSubscriptionName=importJobCompletedEmailHandler
Gift Certificate Purchased Email handler COMMERCE/SYSTEM/MESSAGING/GIFTCERTIFICATES/channelUri giftCertificateCreatedEmailHandler jms:topic:ep.giftcertificates?durableSubscriptionName=giftCertificateCreatedEmailHandler
Gift Certificate Purchased Event Message producer COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri giftCertificateCreatedMessageProducer jms:topic:ep.orders?durableSubscriptionName=giftCertificateCreatedMessageProducer
Order Confirmation Email handler COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri orderConfirmationEmailHandler jms:topic:ep.orders?durableSubscriptionName=orderConfirmationEmailHandler
Order Shipment Created Event Message producer COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri orderShipmentCreatedMessageProducer jms:topic:ep.orders?durableSubscriptionName=orderShipmentCreatedMessageProducer
Order Shipment Release Failed Email handler COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri orderShipmentReleaseFailedEmailHandler jms:topic:ep.orders?durableSubscriptionName=orderShipmentReleaseFailedEmailHandler
Order Shipment Shipped Email handler COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri orderShipmentShippedEmailHandler jms:topic:ep.orders?durableSubscriptionName=orderShipmentShippedEmailHandler
Return or Exchange Email handler COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri returnExchangeEmailHandler jms:topic:ep.orders?durableSubscriptionName=returnExchangeEmailHandler

Virtual Destinations

Virtual destinations gives the dual benefits of a decoupled publisher/subscriber architecture and reliable load-balancing of message processors.

We recommend you configure the Commerce Engine to publish messages to virtual destinations instead of standard JMS topics as this allows clusters of competing consumers to each subscribe to queues, which represent the topic, without processing every message multiple times.

The following example demonstrates a cluster of two identical Integration servers 1 and 2 that each contain two JMS consumers A and B that subscribe to the "ep.orders" virtual topic:

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 both the message consumer that creates order confirmation emails and the message consumer that creates order shipment confirmation emails, the "ep.orders" virtual topic should be configured with two virtual destination queues: "ep.orders.OrderConfirmation" and "ep.orders.OrderShipmentConfirmation". Each of these would exist as JMS queues to which all messages on the "ep.orders" topic are published.

Virtual destinations are configured within the JMS Broker; please refer to the broker's documentation for detailed configuration instructions.

Configuration(queue)

After configuring the virtual destinations within the JMS broker, add the following settings context values to configure each subscriber's assigned queue. Refer to the "Suggested value" column for sample queue names.

Subscriber Setting Context Sample value
CM User Created Email handler COMMERCE/SYSTEM/MESSAGING/CMUSERS/channelUri cmUserCreatedEmailHandler jms:queue:ep.cmusers.cmUserCreatedEmailHandler
CM User Password Changed Email handler COMMERCE/SYSTEM/MESSAGING/CMUSERS/channelUri cmUserPasswordChangedEmailHandler jms:queue:ep.cmusers.cmUserPasswordChangedEmailHandler
CM User Password Reset Email handler COMMERCE/SYSTEM/MESSAGING/CMUSERS/channelUri cmUserPasswordResetEmailHandler jms:queue:ep.cmusers.cmUserPasswordResetEmailHandler
Anonymous Customer Registration Email handler COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri anonymousCustomerRegisteredEmailHandler jms:queue:ep.customers.anonymousCustomerRegisteredEmailHandler
Customer Registration Email handler COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri customerRegistrationEmailHandler jms:queue:ep.customers.customerRegistrationEmailHandler
Customer Password Change Email handler COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri passwordChangedEmailHandler jms:queue:ep.customers.passwordChangedEmailHandler
Customer Password Forgotten Email handler COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri passwordForgottenEmailHandler jms:queue:ep.customers.passwordForgottenEmailHandler
Shared Wish List Email handler COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri wishListSharedEmailHandler jms:queue:ep.customers.wishListSharedEmailHandler
CSV Import Job Completed Email handler COMMERCE/SYSTEM/MESSAGING/DATAIMPORT/channelUri importJobCompletedEmailHandler jms:queue:ep.dataimport.importJobCompletedEmailHandler
Gift Certificate Purchased Email handler COMMERCE/SYSTEM/MESSAGING/GIFTCERTIFICATES/channelUri giftCertificateCreatedEmailHandler jms:queue:ep.giftcertificates.giftCertificateCreatedEmailHandler
Gift Certificate Purchased Event Message producer COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri giftCertificateCreatedMessageProducer jms:queue:ep.orders.giftCertificateCreatedMessageProducer
Order Confirmation Email handler COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri orderConfirmationEmailHandler jms:queue:ep.orders.orderConfirmationEmailHandler
Order Shipment Created Event Message producer COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri orderShipmentCreatedMessageProducer jms:queue:ep.orders.orderShipmentCreatedMessageProducer
Order Shipment Release Failed Email handler COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri orderShipmentReleaseFailedEmailHandler jms:queue:ep.orders.orderShipmentReleaseFailedEmailHandler
Order Shipment Shipped Email handler COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri orderShipmentShippedEmailHandler jms:queue:ep.orders.orderShipmentShippedEmailHandler
Return or Exchange Email handler COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri returnExchangeEmailHandler jms:queue:ep.orders.returnExchangeEmailHandler

Recipient List Message Forwarder

If your JMS Broker doesn't support virtual destinations, you can choose to implement a recipient list consumer to replicate the behaviour of virtual destinations.

Your recipient list consumer should be configured with a list of all of the output JMS queue endpoints, as shown in the following section, and should publish all messages on the incoming queue to each of the required queues. In the following example, each recipient list consumer would forward every incoming message on the "ep.orders" queue to queues "ep.orders.A" and "ep.orders.B".

Recipient List

Configuration

When utilizing the recipient list consumer approach, configure the settings outlined for the virtual destinations approach, then reconfigure the input endpoints to be queues rather than topics.

Message Channel Setting Context Sample value
Change Set Event Messages COMMERCE/SYSTEM/MESSAGING/CHANGESETS/channelUri none jms:queue:ep.changesets
Commerce Manager User Event Messages COMMERCE/SYSTEM/MESSAGING/CMUSERS/channelUri none jms:queue:ep.cmusers
Customer Event Messages

COMMERCE/SYSTEM/MESSAGING/CUSTOMERS/channelUri

none jms:queue:ep.customers
Data Import Event Messages

COMMERCE/SYSTEM/MESSAGING/DATAIMPORT/channelUri

none jms:queue:ep.dataimport
Gift Certificate Event Messages

COMMERCE/SYSTEM/MESSAGING/GIFTCERTIFICATES/channelUri

none jms:queue:ep.giftcertificates
Order Event Messages COMMERCE/SYSTEM/MESSAGING/ORDERS/channelUri none jms:queue:ep.orders

Recipient List Consumer sample implementation

The following 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-3.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"/>
    </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"/>
			</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"/>
				</bean>
				<bean class="org.apache.camel.spring.CamelEndpointFactoryBean">
					<property name="camelContextId" value="sample-recipient-list-forwarder" />
					<property name="uri" value="jms:ep.eventmessagetype.Queue2"/>
				</bean>
				<bean class="org.apache.camel.spring.CamelEndpointFactoryBean">
					<property name="camelContextId" value="sample-recipient-list-forwarder" />
					<property name="uri" value="jms:ep.eventmessagetype.Queue3"/>
				</bean>
				<!-- etc. -->
			</util:list>
		</property>
	</bean>
 
</beans>


The list of outgoing queues to create for each Commerce Engine event message channel can be found in the virtual destination configuration table.