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:

A debug daemon listener that listens for the debug events.
A coupon daemon that issues coupon whenever a VoucherAdjustment is applied to an order.
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.