Qualifier Class

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’s findQualifyingItems method, which returns a list of QualifiedItems. findQualifyingItems returns a Collection. The component type of this collection is QualifiedItem. QualifiedItem maps a DetailedItemPriceInfo to the list of Ranges that qualified for the discount. The CommerceItem containing these DetailedItemPriceInfos is also stored. For more information, see the QualifiedItem Class.
OrderDiscountCalculator uses the qualifier’s findQualifyingOrdermethod, which returns a MatchingObject identifying the Order to discount.
ShippingDiscountCalculator uses the qualifier’s findQualifyingShipping method, which returns a MatchingObject object identifying the ShippingGroup 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 is ItemDiscountCalculator.
The ItemDiscountCalculator calls the findQualifyingItems method in the Qualifier 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 more CommerceItems 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 model RepositoryItems to their parsed PMDL bean representations.
pricingModelProperties: A list of the names of the properties of a pricing model RepositoryItem.

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. (The Qualifier.filterShippingForTarget protected method, which is called by the Qualifier.findQualifyingShipping method, checks the value of the promotion’s oneUsePerOrder property. If it is true, 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 the oneUsePerOrder property is false, 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 to true (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 to true (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 to true (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 to true (the default value), it masks the filterForQualifierDiscountedByCurrentDiscountId 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 is true.
filterForTargetZeroPrices: Determines whether items with zero prices can act as qualifiers. The default value is true.
filterForTargetDiscountedByCurrentDiscountId: Determines whether items that have been discounted by the current discount can receive the discount again. The default value is true.
filterForTargetDiscountedByAnyDiscountId: Determines whether items that have been discounted by any discount can receive the discount again. The default value is true.
filterForTargetActedAsQualifierForAnyDiscount: Determines whether items that have acted as a qualifier for any discount can receive the current discount. The default value is true.
filterForTargetOnSale: Indicates whether items that were priced with a sale price should be allowed to receive the current discount. This property is set to False by default.

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 the ItemPriceInfo for both the CommerceItem 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 above promotion (Buy 1 shirt, get 1 hat free) is the only promotion.

The pricing engine calls the calculator specified in the promotion. In this example, the promotion points to the ItemDiscountCalculator. The priceItems method of this calculator calls findQualifyingItems. This calls QualifierService.findQualifyingItems.

findQualifyingItems performs the following functions (as well as some standard parameter verification and error checking):

wrapCommerceItems - creates FilteredCommerceItems for each item
filterItemsForQualifier - runs through the list of the qualifier filters. In this example, none of the qualifiers apply.

evaluateQualifier - The following arguments are passed to evaluateQualifier:

	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 one MatchingObject 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 to evaluteQualifier. In this example, one item should be discounted so this method will return a List with one item in it. The item will be a MatchingObject whose matchingObject property is the hat CommerceItem and whose quantity 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.

ATG Commerce Programming Guide

Qualifier Class

Qualifier Properties

Evaluating Qualifiers Example