Promotion events and listeners

PromotionEngine generates a number of events during its normal operation. They are contained in the following table:


Event


When Event is Triggered


Attributes


PromotionCreatedEvent


When a promotion is created


The promotion, the actor, and the time of action.


PromotionDeployedEvent


When a promotion is deployed (activated)


The promotion, the actor, and the time of action.


PromotionChangedEvent


When a promotion is changed


The promotion, the actor, and the time of action.


PromotionSuspendedEvent


When a promotion is suspended


The promotion, the actor, and the time of action.


PromotionResumedEvent


When a promotion is resumed


The promotion, the actor, and the time of action.


PromotionWithdrawnEvent


When a promotion is withdrawn


The promotion, the actor, and the time of action.


PromotionResetEvent


When a promotion's statistics are reset.


The promotion, the actor, and the time of action.


PromotionRemovedEvent


When a promotion is marked for deletion.


The promotion, the actor, and the time of action.


PromotoinAssessedEvent


When a promotion is evaluated, and all of the conditions are satisfied.


The PromotionContext at the time of action.

PromotionEliminatedEvent


When a promotion is eliminated due to policy violations.


PromotionExecutionRecords


PromotionQualifiedEvent


When a promotion is qualified.


PromotionExecutionRecords


PromotionRejectedEvent


When a promotion reward is rejected by the customer.


PromotionExecutionRecords


PromotionAppliedEvent


When a promotion is applied to the order.


PromotionExecutionRecords

PromotionErrorEvent When an error occurs.
PromotionTraceEvent

PromotionLogEvent When the promotion engine writes to the log.
PromotionDebugEvent

Listeners must implement the com.ibm.commerce.marketing.promotion.event.PromotionEventListener interface, and be registered with the promotion engine. They are registered when the promotion engine starts and are specified as part of the engine configuration. Listeners can be registered to listen for specific types of event by providing an event mask at registration time. The following list includes the default listeners:

PrintPromotionLifeCycleEventListener

Listens for the Created, Changed, Deployed, Suspended, Resumed, Withdrawn, Reset, and Removed events, and logs the events to standard out.

PrintPromotionExecutionEventListener

Listens for the Assessed, Eliminated, Qualified, Rejected, and Applied events, and logs the events to standard out.

PrintPromotionDefaultRASEventListener

Listens for the Log, Trace, and Error events and logs the events to standard out.

PrintPromotionDefaultDebugEventListener

Listens for the Log, Trace, Error, and Debug events, and logs the events to a file as specified by the "promotion.debug" system attribute. If no such attribute is specified, all events will be logged to standard out.

PromotionLogEventCommerceListener

Listens for the PromotionLogEvent and logs the event to the WebSphere Commerce log file, if WebSphere Commerce logging is enabled.

PromotionTraceEventCommerceListener

Listens for the PromotionTraceEvent and logs the event to WebSphere Commerce trace file, if WebSphere Commerce tracing is enabled.

PromotionErrorEventCommerceListener

Listens for the PromotionErrorEvent and logs the event to both the WebSphere Commerce log file and trace file, if WebSphere Commerce logging and tracing are enabled.

The following XML fragment in the promotion engine configuration configures event listeners for the promotion engine. Note that there are three system listeners that should not be changed:

  1. A debug daemon listener that listens for the debug events.

  2. A coupon daemon that issues coupon whenever a VoucherAdjustment is applied to an order.

  3. A suspension helper listen that helps process suspended promotions. 

<PromotionEventListenerRegistry impl="com.ibm.commerce.marketing.promotion.event.ListenerRegistry">
   <!-- DO NOT MODIFY THE SECTION BELOW -->

   <Listener impl="com.ibm.commerce.marketing.promotion.event.PrintPromotionDebugEventListener">
      <Name>[SYSTEM]DEBUGDAEMON</Name>
      <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionDebugEvent</ListensFor>
   </Listener>
   <Listener impl="com.ibm.commerce.marketing.promotion.coupon.CouponDaemon">
      <Name>[SYSTEM]COUPONDAEMON</Name>
      <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionAppliedEvent</ListensFor>
   </Listener>
   <Listener impl="com.ibm.commerce.marketing.promotion.event.WCSPromotionSuspendedEventListener">
      <Name>[SYSTEM]PROMOTIONSUSPENDHELPER</Name>
      <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionSuspendedEvent</ListensFor>
   </Listener>
   <!-- DO NOT MODIFY THE SECTION ABOVE -->

   <!--

   <Listener impl="com.ibm.commerce.marketing.promotion.event.PrintPromotionLifeCycleEventListener">
      <Name>PrintLifeCycleEventListener</Name>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionChangedEvent</ListensFor>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionCreatedEvent</ListensFor>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionDeployedEvent</ListensFor>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionRemovedEvent</ListensFor>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionResetEvent</ListensFor>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionResumedEvent</ListensFor>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionSuspendedEvent</ListensFor>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionWithdrawnEvent</ListensFor>
   </Listener>
   <Listener impl="com.ibm.commerce.marketing.promotion.event.PrintPromotionExecutionEventListener">
      <Name>PrintExecutionEventListener</Name>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionAssessedEvent</ListensFor>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionAppliedEvent</ListensFor>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionEliminatedEvent</ListensFor>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionQualifiedEvent></ListensFor>
         <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionRejectedEvent</ListensFor>
   </Listener>
   <Listener impl="com.ibm.commerce.marketing.promotion.event.PrintPromotionRASEventListener">
      <Name>PrintRASEventListener</Name>
      <StoreKey>
         <DN>ou=BlueMall B2C Organization, o=Seller Organization, o=Root Organization</DN>
         <Identifier>BlueStore 201</Identifier>
      </StoreKey>
      <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionDebugEvent</ListensFor>
      <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionErrorEvent</ListensFor>
      <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionLogEvent</ListensFor>
      <ListensFor>com.ibm.commerce.marketing.promotion.event.PromotionTraceEvent</ListensFor>
   </Listener>
   -->

</PromotionEventListenerRegistry>

Usually, the most interesting evens to listen for are the PromotionQualifiedEvent and the PromotionAppliedEvent. The first is raised when a promotion is deemed applicable to an order, and it has been determined that applying this promotion does not violate any policy. This is usually when an order item is added to the shop cart and the shop cart is re-evaluated together with applicable promotions. The second event is raised when the order is finalized (that is, confirmed and submitted). The promotion engine uses this event to issue coupons that are results of offering VoucherAdjustments to a shopper.

Related concepts