The atg.commerce.pricing.Qualifier
class is a helper class for discount calculators. An instance of the Qualifier
class is sometimes referred to as a qualifier service, because Qualifier
extends atg.nucleus.GenericService
.
Each calculator calls its corresponding helper method in the Qualifier
class to determine the objects to which it should apply the discount. The Qualifier
checks on whether anything qualifies for the discount and then figures out which pieces should receive the discount. The Qualifier
does not modify the actual prices, it only decides what should change. It does not decide how they should change.
The calculator goes through the result set returned by the qualifier, discounting each element with an appropriate value. In addition, the calculator passes to the qualifier the parameters that make up its pricing context. Note, however, that the calculator alone determines the new price.
ItemDiscountCalculator
uses the qualifier’sfindQualifyingItems
method, which returns a list ofQualifiedItems
.findQualifyingItems
returns a Collection. The component type of this collection isQualifiedItem
.QualifiedItem
maps aDetailedItemPriceInfo
to the list of Ranges that qualified for the discount. TheCommerceItem
containing theseDetailedItemPriceInfos
is also stored. For more information, see the QualifiedItem Class.OrderDiscountCalculator
uses the qualifier’sfindQualifyingOrder
method, which returns aMatchingObject
identifying theOrder
to discount.ShippingDiscountCalculator
uses the qualifier’sfindQualifyingShipping
method, which returns aMatchingObject
object identifying theShippingGroup
to discount.
Each method determines it result set by comparing the PMDL rule of a given promotion (a RepositoryItem
) to the input environment. (For more information on promotions and PMDL rules, see Creating Promotions.)
The following steps describe how an existing calculator and its corresponding Qualifier
class method (in this case, ItemDiscountCalculator
and the findQualifyingItems
method) work together to generate a price for an item.
A pricing engine uses its
getPricingModels
method to retrieve a promotion from a customer profile.The promotion contains a PMDL rule that describes the discount. For example, a rule might define a discount in which a customer receives three items for the price of one. The promotion’s
pricingCalculatorService
property specifies the calculator to use to determine the amount of the discount. In this example, the calculator isItemDiscountCalculator
.The
ItemDiscountCalculator
calls thefindQualifyingItems
method in theQualifier
class and passes the current pricing context into the helper method’s input parameters.If the pricing context matches the conditions specified in the PMDL rule, the
findQualifyingItems
method returns a list containing one or moreCommerceItems
to discount.The
ItemDiscountCalculator
inspects the input discount and generates a new price for each item in the returned list.
The Qualifier
class can be extended. If you create a new type of pricing calculator, you may need to extend the Qualifier
class by adding a new helper findQualifyingxxx
method for the new calculator. For more information, refer to Extending the Qualifier Class.
Qualifier Properties
The Qualifier
class contains the following properties:
pmdlCache
: The cache that maps pricing modelRepositoryItems
to their parsed PMDL bean representations.pricingModelProperties
: A list of the names of the properties of a pricing modelRepositoryItem
.
The following Qualifier
class properties determine the objects that the evaluateQualifier
method can use to evaluate the qualifier element of a PMDL rule. (For more information, see Replacing the Way a PMDL Rule Is Evaluated.)
filterShippingForTarget
: Determines whether the shipping group can receive the discount. The default is true. (TheQualifier.filterShippingForTarget
protected method, which is called by theQualifier.findQualifyingShipping
method, checks the value of the promotion’soneUsePerOrder
property. If it istrue
, it then checks to see if the promotion has been used elsewhere in the order. If it has, the method returns false, and the shipping group cannot use the promotion. If theoneUsePerOrder
property isfalse
, or if the promotion hasn’t been used elsewhere in the order, the method returns true. The shipping group can use the promotion.)filterForQualifierNegativePrices
: Determines whether items with negative prices can act as qualifiers. If this property is set totrue
(the default value), negative prices cannot act as qualifiers.filterForQualifierZeroPrices
: Determines whether items with zero prices can act as qualifiers. If this property is set totrue
(the default value), zero prices cannot act as qualifiers.filterForQualifierDiscountedByCurrentDiscountId
: Determines whether items discounted by the current discount can act as qualifiers. If this property is set totrue
(the default value), items discounted by the current discount cannot act as qualifiers.filterForQualifierDiscountedByAnyDiscountId
: Determines whether items discounted by any discount can act as qualifiers. If this property is set totrue
(the default value), it masks thefilterForQualifierDiscountedByCurrentDiscountId
property.The following example demonstrates how the
filterForQualifierDiscountedByAnyDiscountId
works. In this example, the following three promotions are being applied to an order:Promotion #1: Buy 1 orange, get 1 apple for $1
Promotion #2: Buy 1 apple, get 1 banana for $1
Promotion #3: Buy 1 banana, get 1 plum for $1
The order in this example is for one orange, one apple, one banana, and one plum. The value of the
filterQualifierDiscountedByAnyDiscountId
changes the way the promotions are applied in the following ways:If
filterQualifierDiscountedByAnyDiscountId
is false, then the orange is list price discounting the apple, banana and plum to $1 each.If
filterQualifierDiscountedByAnyDiscountId
is true, then the orange is list price, discounting the apple to $1, and the banana is list price (since the apple was discounted), discounting the plum to $1.
filterForQualifierOnSale
: Indicates whether items that were priced with a sale price should be allowed to act as qualifiers. This property is set to False by default.
The following Qualifier
class properties determine the items that the evaluateTarget
method can use to evaluate the target element of a PMDL rule. (For more information, see Replacing the Way a PMDL Rule Is Evaluated.)
filterForTargetNegativePrices
: Determines whether items with negative prices can act as qualifiers. The default value istrue
.filterForTargetZeroPrices
: Determines whether items with zero prices can act as qualifiers. The default value istrue
.filterForTargetDiscountedByCurrentDiscountId
: Determines whether items that have been discounted by the current discount can receive the discount again. The default value istrue
.filterForTargetDiscountedByAnyDiscountId
: Determines whether items that have been discounted by any discount can receive the discount again. The default value istrue
.filterForTargetActedAsQualifierForAnyDiscount
: Determines whether items that have acted as a qualifier for any discount can receive the current discount. The default value istrue
.filterForTargetOnSale
: Indicates whether items that were priced with a sale price should be allowed to receive the current discount. The default value isfalse
.filterForTargetPriceLessThanOrEqualToPromotionPrice
: Determines whether items with prices that are already less than the price that would be granted by a “fixed price” promotion should receive the promotion. The default value istrue
.
Evaluating Qualifiers Example
This section describes how qualifiers are evaluated using a “buy 1 get 1 free” example. This example uses a promotion of type “Item Discount - Fixed price” where the fixed price is $0.00 and the PMDL rule is:
Condition:
When order contains at least 1 (product named Shirt)
Apply discount to:
up to 1 (product named Hat)
If the list price of the shirt is $10.00 and the list price of the hat of $5.00, the following occurs during item pricing:
The
ItemPricingEngine
iterates through each of the pre-calculators:The
ItemListPriceCalculator
looks up the list price of each item in the order. Based on the list prices, the shirt is priced at $10.00 and the hat will be priced at $5.00. This will update theItemPriceInfo
for both theCommerceItem
objects in the order.The
ItemSalePriceCalculator
looks up the sale price of each item in the order. Because neither item is on sale, this has no effect on the price.
The
ItemPricingEngine
iterates through each of the promotions. In this example, the “Buy 1 shirt, get 1 hat free” promotion is the only promotion.The pricing engine calls the calculator specified in the promotion. In this example, the promotion points to the
ItemDiscountCalculator
. ThepriceItems
method of this calculator callsfindQualifyingItems
. This callsQualifierService.findQualifyingItems
.findQualifyingItems
performs the following functions (as well as some standard parameter verification and error checking):wrapCommerceItems
- createsFilteredCommerceItems
for each itemfilterItemsForQualifier
- runs through the list of the qualifier filters. In this example, none of the qualifiers apply.evaluateQualifier
- The following arguments are passed toevaluateQualifier
:Description
Value in this example
priceQuotes
A list of the two
ItemPriceInfo
objects.$10 and $5
items
List of
CommerceItem
objects.Shirt and hat
pricingModel
Current promotion
Buy 1 shirt, get 1 hat free
profile
The current profile object.
locale
The user’s locale.
order
The current order being priced.
This is null if the item price is being retrieved for displaying within the catalog.
orderPriceInfo
The order’s price
The value is null because it has not been calculated yet.
shippingGroup
The shipping group that is being priced.
The value is null because it’s not pricing a shipping group.
shippingPriceInfo
The costs associated with the shipping group that is being priced.
The value is null because it’s not pricing a shipping group.
In this example, this method returns
Boolean.TRUE
. The reason this is a boolean value is because this is a when rule. There are three choices for the condition: always, when, and for. In the case of always and when,evaluateQualifier
returns a boolean value.Note: If the rule were a for rule, then
evaluateQualifier
would return the list of items that triggered the promotion. If the promotion was “For next 1 (product named shirt)” then this method would return a List containing oneMatchingObject
that wrapped the “shirt”CommerceItem
and had quantity 1.Because the promotion is valid, we must determine which items will receive the discount. The first step is to filter the items for the target. (
filterItemsForTarget
).Note: Because this promotion involves a when rule, we can immediately evaluate the target. If this was a for rule, we would first determine which
DetailedItemPriceInfo
(s) acted as the qualifier.Call
evaluateTarget
. Assuming none of the target filters applied, the list of arguments here will be the same as the list passed toevaluteQualifier
. In this example, one item should be discounted so this method will return a List with one item in it. The item will be aMatchingObject
whosematchingObject
property is the hatCommerceItem
and whosequantity
property is 1.The calculator now knows which items should receive the discount, so it calls
priceQualifyingItems
. This method goes through each detail of each item that qualifies (there is only one in our case) and updates the price. Item pricing is now complete.