Modeling the runtime promotion XML for the new promotion type

In this lesson, you learn about how to model the runtime promotion XML for a new promotion type titled "Spend $ on catalog entry X, get catalog entry Y free." During the shopping flow, the promotion engine parses and processes the runtime promotion XML to evaluate whether a shopper qualifies for a promotion.

About this task

For background information related to this first lesson, read:

Typically, to create a new customized promotion type, you start with the runtime promotion XML from a promotion based on a similar promotion type. You then analyze the runtime promotion XML to determine how the runtime promotion XML for your custom promotion type differs. In most cases, the differences are within the purchase condition and reward sections. Once you model your custom runtime promotion XML, use the model to identify the data that must be managed through the Management Center user interface.

For this lesson, a sample instance of the complete runtime promotion XML for your new promotion type is provided; therefore, you do not need to model it yourself. In this lesson, you examine the contents of the supplied runtime promotion XML and learn about its key sections.

To create a new customized promotion type, you do not need to redefine the whole runtime promotion XML; instead, you need to define a new purchase condition in the XML. Typically, the purchase condition has two parts: the Pattern for the promotion condition and the Distribution for the promotion reward. In this lesson, you learn how to model the <Pattern> and <Distribution> elements.

Procedure

In the following sample, observe the <Pattern> element for the new promotion type.

The key element in the <Pattern> element is the <filter> element. 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 more information, see Custom filters. For this promotion, you use an existing filter, MultiSKUFilter, which filters the LineItemSet based on the CatalogEntry and parent CatalogEntry of the LineItems, and returns all the LineItems whose CatalogEntry or parent CatalogEntry belongs to the Inclusion List and not the Exclusion List of the filter. The following code sample is an instance of the <Pattern> element in the runtime promotion XML:


<Pattern impl="com.ibm.commerce.marketing.promotion.condition.Pattern">
<Constraint impl="com.ibm.commerce.marketing.promotion.condition.Constraint">
<WeightedRange impl="com.ibm.commerce.marketing.promotion.condition.WeightedRange">
<LowerBound>1</LowerBound>
<UpperBound>-1</UpperBound>
<Weight>1</Weight>
</WeightedRange>
<FilterChain impl="com.ibm.commerce.marketing.promotion.condition.FilterChain">
<Filter impl="com.ibm.commerce.marketing.promotion.condition.MultiSKUFilter">
<xsl:for-each select="PromotionData/Elements/PurchaseCondition/IncludeCatalogEntryIdentifier">
<IncludeCatEntryKey>
<xsl:call-template name="CatalogEntryKeyTemplate">
<xsl:with-param name="dn" select="Data/DN" />
<xsl:with-param name="sku" select="Data/SKU" />
</xsl:call-template>
</IncludeCatEntryKey>
</xsl:for-each>
<xsl:for-each select="PromotionData/Elements/PurchaseCondition/ExcludeCatalogEntryIdentifier">
<ExcludeCatEntryKey>
<xsl:call-template name="CatalogEntryKeyTemplate">
<xsl:with-param name="dn" select="Data/DN" />
<xsl:with-param name="sku" select="Data/SKU" />
</xsl:call-template>
</ExcludeCatEntryKey>
</xsl:for-each>
</Filter>
</FilterChain>
</Constraint>
</Pattern>

In the previous sample, the elements in boldface text are those that the user interface manages. For this instance, the business user has specified that customers must have either the TAPL-02 or TAPL-01 category entry in their shopping cart to be eligible for this promotion.

In the following sample, observe the <Distribution> element for the new promotion type.

The key element in the <Distribution> element is the <Adjustment> element. Adjustments are incentives offered to customers. Adjustments can be either applied to one or more order items in the matched pattern, or the entire order. For more information, see Custom adjustments. For this promotion, you use an existing adjustment, FreePurchasableGiftAdjustment. It offers a free gift as the reward of a promotion. The following code sample is an instance of the <Distribution> element in the runtime promotion XML:


<Distribution impl="com.ibm.commerce.marketing.promotion.reward.Distribution">
<Type>Volume</Type>
<Base>Cost</Base>
<Currency>USD</Currency>
<Range impl="com.ibm.commerce.marketing.promotion.reward.DistributionRange">
<UpperBound>-1</UpperBound>
<LowerBound><xsl:value-of select="PromotionData/Elements/PurchaseCondition/Data/BaseItemTotalPrice" /></LowerBound>
<UpperBoundIncluded>true</UpperBoundIncluded>
<LowerBoundIncluded>true</LowerBoundIncluded>
<RewardChoice>
<Reward impl="com.ibm.commerce.marketing.promotion.reward.DefaultReward">
<xsl:for-each select="PromotionData/Elements/PurchaseCondition/GiftCatalogEntryIdentifier">
<AdjustmentFunction impl="com.ibm.commerce.marketing.promotion.reward.AdjustmentFunction">
<FilterChain impl="com.ibm.commerce.marketing.promotion.condition.FilterChain">
<Filter impl="com.ibm.commerce.marketing.promotion.condition.DummyFilter" />
</FilterChain>
<Adjustment impl="com.ibm.commerce.marketing.promotion.reward.FreePurchasableGiftAdjustment">
<GiftItem>
<xsl:call-template name="CatalogEntryKeyTemplate">
<xsl:with-param name="dn" select="Data/DN" />
<xsl:with-param name="sku" select="Data/SKU" />
</xsl:call-template>
</GiftItem>
<Quantity><xsl:value-of select="Data/giftQuantity" /></Quantity>
<AddStrategy>1</AddStrategy>
<AdjustmentType>wholeOrder</AdjustmentType>
</Adjustment>
</AdjustmentFunction>
</xsl:for-each>
</Reward>
</RewardChoice>
</Range>
<PatternFilter impl="com.ibm.commerce.marketing.promotion.condition.DummyPatternFilter" />
</Distribution>

In the previous sample, the elements in boldface text are those that the user interface manages. For this particular instance, the business user has specified that if customers spend $200 or more on the catalog entries listed in <Pattern> element, they receive a gift.

Results

This lesson introduced the two key sections of the runtime promotion XML. In the next lesson, you begin planning the Management Center user interface changes you require to support your new promotion type.