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 will differ. In most cases, the differences are within the purchase condition and reward sections. Once you have modeled 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. You need this knowledge for the lessons Planning the user interface customization and Creating and registering the XSL template later in this tutorial.

To create a new customized promotion type, you do not need to redefine the whole runtime promotion XML; instead, you need only 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

  1. 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 will use an existing filter, MultiSKUFilter. It 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">
                <IncludeCatEntryKey>
                    <CatalogEntryKey>
                        <SKU>TAPL-02</SKU>
                        <DN>
                            ou=madisons,o=seller organization,o=root
                            organization
                        </DN>
                    </CatalogEntryKey>
                </IncludeCatEntryKey>
                <IncludeCatEntryKey>
                    <CatalogEntryKey>
                        <SKU>TAPL-01</SKU>
                        <DN>
                            ou=madisons,o=seller organization,o=root
                            organization
                        </DN>
                    </CatalogEntryKey>
                </IncludeCatEntryKey>
            </Filter>
        </FilterChain>
    </Constraint>
</Pattern>
    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 customers must have either the TAPL-02 or TAPL-01 category entry in their shopping cart to be eligible for this promotion.
  2. 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>200</LowerBound>
        <UpperBoundIncluded>true</UpperBoundIncluded>
        <LowerBoundIncluded>true</LowerBoundIncluded>
        <RewardChoice>
            <Reward impl = "com.ibm.commerce.marketing.promotion.reward.DefaultReward">
                <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>
                            <CatalogEntryKey>
                                <SKU>TATA-0101</SKU>
                                <DN>
                                    ou=madisons,o=seller
                                    organization,o=root organization
                                </DN>
                            </CatalogEntryKey>
                        </GiftItem>
                        <Quantity>4</Quantity>
                        <AddStrategy>1</AddStrategy>
                        <AdjustmentType>wholeOrder</AdjustmentType>
                    </Adjustment>
                </AdjustmentFunction>
                <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>
                            <CatalogEntryKey>
                                <SKU>TAWI-0301</SKU>
                                <DN>
                                    ou=madisons,o=seller
                                    organization,o=root organization
                                </DN>
                            </CatalogEntryKey>
                        </GiftItem>
                        <Quantity>4</Quantity>
                        <AddStrategy>1</AddStrategy>
                        <AdjustmentType>wholeOrder</AdjustmentType>
                    </Adjustment>
                </AdjustmentFunction>
                <RewardPolicy>ALL</RewardPolicy>
            </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 will receive a gift of four TAWI-0301 catalog entries and four TATA-0101 catalog entries.

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.