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
-
Start WebSphere Commerce Developer and switch to the Enterprise Explorer view.
-
Create a custom properties files to include your custom promotion error message.
-
Expand . If this directory structure does not exist, create the directory structure, where
mycompany is the name of your company.
-
Within the com.mycompany.commerce.promotions.custom.properties package,
create a file to define your custom error message, such as
CustomWcPromotionMessages_locale.properties.
-
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.
-
Register your custom error message by creating a custom class to register the constant values
that form the new exception.
-
Expand . If this directory structure does not exist, create the directory structure, where
mycompany is the name of your company.
-
Within the com.mycompany.commerce.promotions.custom package, create a
file to define your new Java class, such as
MyCustomMessageConstants.java.
-
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);
}
-
Create a custom exception handler class that extends the
DefaultPromotionExceptionHandler.java class for retrieving your custom error
message.
-
Expand .
-
Within the com.mycompany.commerce.promotions.custom package, create a
file to define your new Java class, such as
MyPromotionExceptionHandler.java.
-
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;
}
}
-
Configure the promotion engine to use your new exception handler class by updating the
WCSPromotionEngineConfig.xml configuration file.
-
Expand .
-
Open the WCSPromotionEngineConfig.xml file for editing.
-
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"/>
-
Save and close your new custom files.
-
Restart the WebSphere Commerce Test Server.
-
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."