Promotion anatomy

A promotion is defined as an interface within the promotion engine, which means that different implementations of a promotion can be supplied by the developer who customizes the promotion engine. A default implementation is supplied for the interface, which follows a pattern-based model. This topic explains the model.

Each individual promotion in HCL Commerce can be serialized as an XML document. This document is called the runtime promotion XML. The promotions engine parses and processes the runtime promotion XML when evaluating promotions during the shopping flow. Refer to the sample runtime promotion XML. Also refer to the promotion DTD to view the document type definition (DTD) of the promotion XML. Note that this DTD is used mainly as a reference. No validation against this DTD is performed at promotion engine runtime. Also, this DTD does not specify the details of some of its components, such as filters and adjustments. The content of both elements are marked as ANY. This is because these two components are the most frequently customized components of a promotion. Defining a rigid content model would only limit a developer's ability to customize the system. Sample filter and adjustment XML fragments are also provided in the sample adjustment XML fragments topic. These can be used to construct new promotion types.

Promotion attributes

Promotion Key
A promotion is identified by a key, consists of a reference to a store, a string name, a version number, and a revision number.
Promotion Group Membership
A promotion belongs to one and only one promotion group.
Campaign Membership
Optionally, a promotion can be a member of a marketing campaign.
Description
A promotion can have multiple descriptions in different languages.
Priority
Each promotion has a priority. The higher the priority, the more important the promotion is. This priority is one of the input parameters to the promotion sequence builder in the promotion engine.
Exclusivity
A promotion can be either non-exclusive, exclusive within its own group, or globally exclusive.
Status
A promotion can be active, inactive, obsolete, suspended, or deleted.
Lastupdate
The last time a promotion was updated. This is recorded in the promotion.
Lastupdate By
The ID of the last person who updated the promotion. This is recorded in the promotion.
Redemption Limits
A promotion can have three different redemption limits associated with it:
Per Order Limit
The maximum number of times a promotion can be redeemed within any given order.
Per Shopper Limit
The maximum number of times a promotion can be redeemed by a registered customer. Due to the nature of guest customers, this limit does not apply to any guest customers.
Overall Limit
The maximum number of times a promotion can be redeemed overall.
Schedule
A promotion can be active during a certain period of time. This is defined by a start and end date, a list of week days on which a promotion will be active, and a time period during the day during which a promotion is active.
Coupons
A promotion can be marked as targeted, which means that as long as a customer belongs to a customer segment targeted by this promotion, and does not belong to any customer segment excluded by this promotion, the customer is potentially eligible for a promotion. Conversely, a promotion can also be marked as private, which means that a coupon for this promotion must be issued to this customer before this customer can be eligible for this promotion.
Promotion Code
You can assign one or more promotion codes to a promotion. A simple promotion code application is provided by default. This application only supports assigning a single code per promotion. If the promotion is marked as requiring a promotion code, that code must be entered by the customer before the customer will be considered for this promotion. The code is recorded as the PromotionCodeCue attribute of the promotion. Whether this promotion requires a promotion code or not, it is stored in the PromotionCodeRequired Boolean attribute.

A custom promotion code application is a very important topic, and is covered in customizing the promotion code manager.

Targeting Condition
A promotion can be marked to target only certain customer segments and exclude others. If no customer segments are specified, then it is available to all customers. There are two additional Boolean attributes that control how a TargetingCondition associated with a promotion is applied. The first tells the promotion engine whether the targeting condition should be evaluated during promotion evaluation. If set to false, the targeting condition is ignored at the time the promotion is being evaluated. The second attribute, SkipTargetingConditionOnProperPromotionCodeEntered, directs the promotion engine in the situation when a correct promotion code is entered for a promotion but the promotion also has a targeting condition associated with it. If set to true, the targeting condition is ignored when a correct promotion code is entered for this promotion.
Custom Conditions
Additional custom conditions can be specified in a promotion. The only result a custom condition returns is a Boolean value indicating whether the condition is satisfied or not. If not, the promotion will not be applied. All custom conditions must implement the Condition interface. This topic is discussed further in new conditions.

Purchase Condition

The following diagram shows the building blocks of a Purchase Condition, which is the heart of a promotion. A purchase condition defines the purchases a customer must make to qualify for a promotion. The Purchase Condition is a Condition, that is, it implements the Condition interface. All of the building blocks in the diagram implement the XMLizable interface so that they can be serialized to an XML element, and deserialized from an XML element. The serialized XML fragment of a purchase condition becomes part of the XML document of a promotion.

image goes here

The following section looks at individual building blocks.

Filter
A filter is a set of business logic that is applied to a LineItemSet, and results in a second LineItemSet that is a subset of the original LineItemSet. For example, a filter could return all of the order items in the original LineItemSet that belong to the category "Sweaters." A set of standard filters are provided. This set includes the following filters:
DummyFilter
Does nothing. Returns the original LineItemSet.
CategoryFilter
Returns all order items that belong to the targeted categories, but not the excluded categories.
ManufacturerFilter
Returns all order items whose manufacturer matches the specified target manufacturer.
MultiSKUFilter
Returns all order items for which the item, or the item's parent product's, SKU is in the targeted list, but not in the excluded list.
OrderedQuantityFilter
Returns order items that meet quantity constraints, such as "up to 5 items" or "at least 2 items".
PriceComparisonFilter
This filter is deprecated; instead use OrderedQuantityFilter.
PriceThresholdFilter
Returns order items that exceed the specified price.
ShippingModeFilter
Returns order items that are shipped with the specified shipping mode.

Additional custom filters can be introduced. This is covered further in new filters.

Filter Chain
A FilterChain is a list of filters. All of the filters on the chain are applied contiguously to an input LineItemSet. One filter takes the output of the previous filter as input, and applies its own filtering logic on it. A filter chain can be viewed as a set of filters logically connected with "and."
Weighted Range
A WeightedRange specifies a quantity requirement. It is used to express quantity related conditions like exactly 5, or at least 5. A weighed range has a lower bound and an upper bound, and a weight. In practical application, the weight is usually set to 1.

When the weight is set to 1, and the lower bound is the same as the upper bound, then this weighted range defines a concept of exactly X where X is the value of the lower bound and the upper bound. If the lower bound is not the same as the upper bound, it defines a quantity requirement of "at least M, but no more than N," where M is the value of the lower bound and N is the value of the upper bound. If N is set to unlimited, then the concept is simplified to "at least M, but as many as possible."

Constraint
Constraints combine filter chains and weighed ranges. This combination defines concepts like the following example:

At least X number of order items that satisfy the following conditions....

The "At least X" part is expressed using the weighted range and the "following conditions" is expressed using a filter chain. The entire logical unit composes the semantics of a constraint.

Note: A constraint can contain multiple FilterChains. This arrangement is used to describe a homogeneous list. This concept is rarely used.
Pattern
A Pattern is a collection of constraints, or targeted items. An example of a typical pattern is, 'Purchase 2 pairs of pants and 1 sweater, get 1 belt for 10% off the regular price." In this example, three constraints are used: "2 pairs of pants," "1 sweater," and "1 belt."

All three constraints are considered "targeted" items because all three targeted items must be in the shopping cart before the pattern can be satisfied. Once the pattern is satisfied, the adjustment is applied to the affected item; the belt.

Applying a pattern to a LineItemSet results in zero or more matched patterns. For example, if a shopping cart contains 5 pairs of pants, 2 sweaters, and 3 belts, applying the example pattern results in 2 matches. Each match contains 2 pairs of pants, 1 sweater, and 1 belt. These matched patterns are eligible targets for promotions.

Pattern Filter
Not all patterns can be qualified for promotions; a PatternFilter is a set of logic that eliminates matched patterns that do not satisfy the conditions set out in a pattern filter. A pattern filter is very similar to that of a filter; it only differs in the input and output. Input to a pattern filter is a list of LineItemSets, each LineItemSet is a matched pattern. The output is a subset of the list.
Adjustment
Adjustments are incentives offered to customers. They can be either applied to one or more order items in the matched pattern, or the entire order. When applied to order items, the items are called affected items. The available adjustment types are discussed in the black box view of the promotion engine's architecture.
Adjustment Function
An AdjustmentFunction is made up of a filter chain and an adjustment. The input to an adjustment function is a matched pattern, that is, a LineItemSet. The adjustment function first uses the filter chain to locate a subset of order items in the LineItemSet, and then attaches the adjustment to the subset of order items.
Reward
A Reward is a collection of adjustment functions. The input of a reward is a matched pattern, and the reward attaches various adjustments to various subsets of the matched pattern by calling its member adjustment functions.
Reward Choice
Due to the complexity of this feature, reward choice is unsupported at this time. Currently, a reward choice only contains a single reward. Input to a reward choice is also a matched pattern. A reward choice calls the containing reward to apply adjustments to the matched pattern.
Distribution
Applying patterns to an order, results in zero or more matched patterns. The reward choice and its building blocks attach adjustments to a single matched pattern. The Distribution connects all of the matched patterns with reward choices. Once the matched patterns are found, you can apply distributions on either the total spending on all of the matched patterns, or the total number of matched patterns. When a distribution is applied to the total spending on all matched patterns, the system defines a number of ranges with lower and upper bounds. If the total spending falls into any of the ranges, the reward choice in that range is applied to all of the matched patterns. This is called a cost-based volume distribution. When a distribution is applied to the total number of matched patterns, there are two possible outcomes. The first possible outcome is similar to that of the cost-based volume distribution. This case also defines a number of ranges, each with its upper and lower bounds. The upper and lower bounds in this case define a number of matched patterns, not total spending. If the total number of matched patterns falls into any of the ranges, the reward choice in that range is applied to all matched patterns. This is referred to as the quantity-based volume distribution. The second possible outcome is the quantity-based tiered distributions. In this case, matched patterns are distributed into different ranges, based on their lower and upper bound values, and apply reward choices in these ranges to matched patterns that are distributed to the ranges. For example, in a quantity-based tiered distribution, there are three defined ranges, 1 to 3, 4 to 6 and 7 and up. For each range, a reward choice is defined, named Choice A, B, and C. If the total number of matched patterns is ten, then Choice A will be applied to the first three matched patterns, B to the next three, and C to the remaining four matched patterns.
Purchase Condition
A PurchaseCondition contains a pattern and a distribution. A purchase condition attempts to spot patterns and attaches adjustments to matched patterns.