Feature Pack 4 or later

Customizing promotion error messages in the storefront

You can customize some promotion error messages that display to shoppers to provide shoppers with more information to resolve errors that they encounter while shopping in your store.

Before you begin

Ensure that you install the interim fix for APAR JR54737.

If your site uses a customized promotion engine, ensure that your promotion engine extends the DefaultPromotionEngine class.

About this task

When a shopper enters a unique promotion code in an order, a default error message can display if that code is already entered for another order. The default error message that displays might not provide all of the information that you want to display to the shopper. You can change the default message that displays to the shopper by creating and registering your own custom error message. To customize the promotion engine to retrieve and display your custom message, you must extend the DefaultPromotionExceptionHandler class and configure the engine to use your message instead of the default message. You can configure the promotion engine by changing the configured setting within the WCSPromotionEngine.xml promotion engine configuration file.

As an example, this task demonstrates how to create a custom error message for when a shopper enters an promotion code that is already entered for another order. When a unique promotion code is entered for an order, the code can be locked so that the shopper or another shopper cannot use that same code in another order. This locked promotion code is still a valid code until it is redeemed, but the code cannot be applied to another order until the system releases the code. The system can release the code for use within another order when the order with the applied and locked code is cancelled or abandoned for a specific amount of time. By default, when a shopper enters a promotion code that is already entered within another order and is locked, the following error message is displayed: Error: CMN3101E The system is unavailable due to "Promotion code "ABC" is invalid."

After you complete this task, the following custom error message is displayed instead of the preceding default error message: Error: CMN3101E The system is unavailable due to "The promotion code "ABC" that you entered is already applied to another order."

Procedure

  1. Start WebSphere Commerce Developer and switch to the Enterprise Explorer view.
  2. Create a custom properties files to include your custom promotion error message.
    1. Expand WebSphereCommerceServerExtensionsLogic > src > com.mycompany.commerce.promotions.custom.properties. If this directory structure does not exist, create the directory structure, where mycompany is the name of your company.
    2. Within the com.mycompany.commerce.promotions.custom.properties package, create a file to define your custom error message, such as CustomWcPromotionMessages_locale.properties.
    3. Within your new properties file, define the text for your custom error message.
      For example, your error message can resemble the following message key and text value:
      ERR_PROMOTION_CODE_UNRELEASABLE.-1201 = The promotion code "{0}" that you entered is already applied to another order.
  3. Register your custom error message by creating a custom class to register the constant values that form the new exception.
    1. Expand WebSphereCommerceServerExtensionsLogic > src > com.mycompany.commerce.promotions.custom. If this directory structure does not exist, create the directory structure, where mycompany is the name of your company.
    2. Within the com.mycompany.commerce.promotions.custom package, create a file to define your new Java class, such as MyCustomMessageConstants.java.
    3. Within your new file, define the constant values that form your cust exception.
      A custom error message requires three corresponding constants:
      • A String object that specifies the variable in CustomWcPromotionMessages.properties
      • An int representing the error code defined in CustomWcPromotionMessages.properties
      • An ECMessage object that specifies the resource bundle and error string
      Your custom MyCustomMessageConstants.java file can resemble the following class:
      
      import com.ibm.commerce.ras.ECMessage;
      import com.ibm.commerce.ras.ECMessageSeverity;
      import com.ibm.commerce.ras.ECMessageType;
      
      public class MyCustomMessageConstants {
      
        public final static String USER_RESOURCE_BUNDLE = "com.mycompany.commerce.promotions.custom.properties.CustomWcPromotionMessages";
        public static final int ERR_MAJ_PROMOTION_CODE_UNRELEASABLE = -1201;
        public static final String ERR_PROMOTION_CODE_UNRELEASABLE = "ERR_PROMOTION_CODE_UNRELEASABLE." + ERR_MAJ_PROMOTION_CODE_UNRELEASABLE;
      
        public static final ECMessage ECMESSAGE_PROMOTION_CODE_UNRELEASABLE = new ECMessage(
          ECMessageSeverity.ERROR,
          ECMessageType.USER,
          ERR_PROMOTION_CODE_UNRELEASABLE ,
          USER_RESOURCE_BUNDLE);
      
      }
  4. Create a custom exception handler class that extends the DefaultPromotionExceptionHandler.java class for retrieving your custom error message.
    1. Expand WebSphereCommerceServerExtensionsLogic > src > com.mycompany.commerce.promotions.custom.
    2. Within the com.mycompany.commerce.promotions.custom package, create a file to define your new Java class, such as MyPromotionExceptionHandler.java.
    3. Within your new file, define your exception handler class.
      Ensure that your custom class extends the DefaultPromotionExceptionHandler class and overrides the getPromotionCodeUnreleasableException() exception method.

      Within the getPromotionCodeUnreleasableException(HashMap params) method, the parameter "params" is a HashMap that contains some some of the information that is available when the method is called. The information that is stored in params might be usefult to include within your error message. For instance, the entered promotion code can be retrieved in params by using the PromotionExceptionHandler.PARAMETER_KEY_PROMOTION_CODE key. The retrieved code can then be used as a parameter in your custom error message. The params might not contain the same set of information for all exception methods. Only the values that are available at the time that the exception method is called is stored inside the params.

      Your custom MyPromotionExceptionHandler.java can resemble the following class:
      
      public class MyPromotionExceptionHandler extends DefaultPromotionExceptionHandler{
        
        private static final String CLASSNAME = MyPromotionExceptionHandler.class.getName();
        
        protected ECApplicationException getPromotionCodeUnreleasableException(HashMap params){
        
          final String METHODNAME = "getPromotionCodeUnreleasableException";
        
          ECMessage errorMessage = MyCustomMessageConstants.ECMESSAGE_PROMOTION_CODE_UNRELEASABLE;
          String errorCode = String.valueOf(MyCustomMessageConstants.ERR_MAJ_PROMOTION_CODE_UNRELEASABLE);
          String code = (String)params.get(PromotionExceptionHandler.PARAMETER_KEY_PROMOTION_CODE);
        
          TypedProperty hshNVPs = new TypedProperty();
          hshNVPs.put(ECConstants.EC_ERROR_CODE,errorCode);
          ECApplicationException e = new ECApplicationException(
            errorMessage, CLASSNAME, METHODNAME,
            new Object[]{code},
            hshNVPs);
        
          return e;
        
        }
      }
  5. Configure the promotion engine to use your new exception handler class by updating the WCSPromotionEngineConfig.xml configuration file.
    1. Expand WC > xml > PromotionEngineConfiguration.
    2. Open the WCSPromotionEngineConfig.xml file for editing.
    3. Add the following configuration to change the default implementation for the PromotionExceptionHandler configuration to point to your custom com.mycompany.commerce.promotions.custom.MyPromotionExceptionHandler class.
      <PromotionExceptionHandler impl="com.mycompany.commerce.promotions.custom.MyPromotionExceptionHandler"/> 
  6. Save and close your new custom files.
  7. Restart the WebSphere Commerce Test Server.
  8. Open your storefront in a web browser. Add products to your cart that meet the promotion purchase conditions and enter a promotion code that into second order without submitting the first order to trigger the error message. After you trigger the message, ensure that you see an error message that resembles the following message:

    Error: CMN3101E The system is unavailable due to "The promotion code "ABC" that you entered is already applied to another order."