Promotion events and listeners

The promotion engine generates a number of events during its normal operation. Listeners wait for specific types of events to occur and then log the events.

Promotion engine events
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.
PromotionAssessedEvent 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 HCL Commerce log file, if HCL Commerce logging is enabled.
PromotionTraceEventCommerceListener
Listens for the PromotionTraceEvent and logs the event to HCL Commerce trace file, if HCL Commerce tracing is enabled.
PromotionErrorEventCommerceListener
Listens for the PromotionErrorEvent and logs the event to both the HCL Commerce log file and trace file, if HCL 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 listener 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 events 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.