Customizing the agenda builder

If you want to change the default logic that selects potentially applicable promotions for evaluation, or to improve system performance by screening promotions prior to evaluation to reduce the number of promotions to be evaluated at runtime, you can customize the agenda builder. A HCL Commerce instance has only one agenda builder. Customizations apply to all stores in the same instance.

About this task

The agenda builder searches promotions directly related to shopping cart content rather than all available promotions in the system. The purpose of using this agenda builder is to enhance performance for promotion evaluation at the production environment by only evaluating the promotions related to products purchased. This agenda builder works best with a shopping cart that has small number of items, while the store has a large number of active promotions that are targeting different sets of products or categories. This implementation requires data populated in the CATENCALCD, and CATGPCALCD table during the promotion authoring process that indicates the mapping between promotion and catlogEntry or category. If the store rarely has category-level promotions, then a flag can be set in the promotion engine configuration file for the agenda builder. The name of the flag is PerformCheckForCategoryLevelPromotions and it may have a value of true or false. If the flag is set to true, then a search is performed for any active category-level promotions in the store. If none are found, then no call is made to get the categories of items in the order. This can improve the performance of store-front evaluation of promotions especially if the catalog has a deep category structure. If the flag is set to false, then the default behavior of getting categories of order items is performed.

Procedure

  1. Implement your agenda builder.
    The only requirement is that your agenda builder must implement the com.ibm.commerce.marketing.promotion.runtime.PromotionExecutionAgendaBuilder interface. This interface is also a subclass of XMLizable interface. As a result, you must define the toXML and fromXML methods for your implementation, as well as a serialized XML form for your agenda builder.

    The worker method of the AgendaBuilder interface is the buildAgenda method. It takes two parameters. One is the PromotionArgument with all the input attributes set. The other is the PromotionEngine. Through the PromotionEngine parameter, you have access to useful services like the persistence manager registry and the external entity factory registry. This method returns the PromotionExecutionAgenda once it is built.

  2. Register the custom agenda builder in the promotion engine configuration.
    Locate the following XML fragment:
    
<PromotionExecutionAgendaBuilder impl="com.ibm.commerce.marketing.promotion.runtime.DefaultAgendaBuilder">
.
.
.
   <!-details -->
.
.
.
</PromotionExecutionAgendaBuilder>
    1. Replace the value of the impl attribute with the fully qualified class name of your own implementation.
    2. Replace the content of the XML elements with the serialized XML for your agenda builder.
  3. Restart HCL Commerce.
    Since the agenda builder is initialized during HCL Commerce start up, a restart is required before the changes take effect.