Creating the child object definition for the new promotion type

In this lesson, you define a new child object definition to represent the new purchase condition promotion element.

About this task

The child object definition defines a purchase condition for the new promotion type. This object definition is one of the root element definitions that extends the promotion purchase condition root element, and it includes all the sub-elements of the promotion, such as the purchase condition and reward. In the Promotions tool, each promotion type has its own object definition. This object definition must be an extension of the PurchaseConditionObjectDefinition definition.

The purchase condition defines what criteria a customer must meet to qualify for a promotion and receive the reward. For this new promotion type, the purchase condition is "Spend $ on catalog entry X." A business user could then use this new promotion type to create a promotion that requires customers to "Spend $200 or more on dinnerware catalog entries" to qualify for the reward.

Procedure

Create a new definition file for the promotion element object definition:
1. In the Enterprise Explorer view, expand LOBTools > WebContent > WEB-INF > src > xml.
2. Right-click the xml directory; then click New > Folder.
3. Create the following directory structure: mycompany > promotion > objectDefinitions > elements and click Finish.
4. Right-click the elements directory; then click New > File.
5. Name your new file ProductLevelFreeGiftPurchaseConditionObjectDefinition.xml.
6. Click Finish to create the file. The file opens in the default XML editor.

Define the promotion element object definition file, ProductLevelFreeGiftPurchaseConditionObjectDefinition.xml.

Copy and paste the following object definition sample into this definition file.


<?xml version="1.0" encoding="UTF-8"?>
<Definitions>

<PromotionElementObjectDefinition baseDefinition="cmc/promotion/PurchaseConditionObjectDefinition" 
 definitionName="cmc/promotion/ExtProductLevelFreeGiftPurchaseConditionObjectDefinition" 
1 objectType="ProductLevelFreeGiftPurchaseCondition" package="cmc/promotion">
<dependency localName="promotionResources" moduleName="cmc/promotion/PromotionResources"/>
<dependency localName="ExtPromotionResources" moduleName="cmc/promotion/ExtPromotionResources"/>
2<PromotionElementReferenceObjectDefinition baseDefinition="cmc/promotion/IdentifierCatalogEntryObjectDefinition" 
 package="cmc/promotion">
<Xml name="template">
3<elementType>IncludeCatalogEntryIdentifier</elementType>
</Xml> 
</PromotionElementReferenceObjectDefinition> 

<PromotionElementReferenceObjectDefinition baseDefinition="cmc/promotion/IdentifierInheritedCatalogEntryObjectDefinition" package="cmc/promotion">
<Xml name="template">
<elementType>IncludeCatalogEntryIdentifier</elementType>
</Xml> 
</PromotionElementReferenceObjectDefinition> 

<!-- property definition: The total price threshold for the promotion condition -->
<PropertyDefinition displayName="${ExtPromotionResources.promotion_Minimum_purchase_TotalPrice}" minValue="1" 
 propertyName="BaseItemTotalPrice" required="true"/>

<PromotionElementReferenceObjectDefinition baseDefinition="cmc/promotion/IdentifierGiftCatalogEntryObjectDefinition" package="cmc/promotion">
<Xml name="template">
<elementType>GiftCatalogEntryIdentifier</elementType>
</Xml>	
<!-- property definition: the quantity of each gift -->
<PropertyDefinition displayName="${ExtPromotionResources.promotion_Free_gift_qty}" minValue="1" propertyName="giftQuantity" required="true"/> 
</PromotionElementReferenceObjectDefinition> 

<PromotionElementReferenceObjectDefinition baseDefinition="cmc/promotion/IdentifierInheritedGiftCatalogEntryObjectDefinition" 
 package="cmc/promotion">
<Xml name="template">
<elementType>GiftCatalogEntryIdentifier</elementType>
</Xml>
<!-- property definition: the quantity of each gift -->
<PropertyDefinition displayName="${ExtPromotionResources.promotion_Free_gift_qty}" minValue="1" propertyName="giftQuantity" required="true"/> 
</PromotionElementReferenceObjectDefinition> 

<!-- Validator definition: The condition catentry set cannot be empty, at least one catentry should be assigned --> 
<RequiredChildObjectValidator errorMessage="${promotionResources.promotion_error_AtLeastOneProduct}" 
 objectPath="Identifier_CatalogEntryGroup" validatorId="reqCatValidator"/>

<!-- Validator definition: The gift set cannot be empty, at least one gift should be assigned -->
<RequiredChildObjectValidator errorMessage="${promotionResources.promotion_error_AtLeastOneGift}" 
 objectPath="Identifier_GiftCatalogEntryGroup" validatorId="reqGiftValidator"/>  
</PromotionElementObjectDefinition>
</Definitions>

1 objectType: This attribute defines the name of the user interface element for this purchase condition, and it is stored in the SUBTYPE column of the PX_ELEMENT table. The purchase condition is composed of child promotion elements including the predefined purchase and reward promotion element definitions.
2 PromotionElementReferenceObjectDefinition: The first instance of this element in the code sample references the catalog entry object. For this promotion type, this catalog entry is what the customer is required to purchase to qualify for the promotion. The second instance of the PromotionElementReferenceObjectDefinition element is included to support catalog entries inherited from a master catalog asset store. The third instance of this element also references the catalog entry object; in this case, the catalog entry is the free gift. The last instance of the PromotionElementReferenceObjectDefinition element is included to support gift catalog entries inherited from a master catalog asset store.
3 <elementType>: This element is contained within the XML element. It is stored in the TYPE column of the PX_ELEMENT table when the promotion is created, and it will be used to compose the authoring promotion XML when the promotion is activated.

Save and close the file.
The new object extends the existing PurchaseConditionObjectDefinition definition.

Now that your custom purchase condition has been defined, Add the new object definition to the Promotion primary object.

Expand LOBTools > WebContent > WEB-INF > src > xml > commerce > promotion > objectDefinitions directory.
Open the PromotionPrimaryObjectDefinition.xml file. This primary object definition file contains all the information about a promotion in the Management Center. Observe the services, properties and child objects defined here.

Locate the following lines, which are declarations of other purchase condition object definitions:


<PromotionElementObjectDefinition baseDefinition="cmc/promotion/ProductLevelFixedCostDiscountPurchaseConditionObjectDefinition" 
 package="cmc/promotion"/>
<PromotionElementObjectDefinition baseDefinition="cmc/promotion/ProductLevelPerItemFixedCostDiscountPurchaseConditionObjectDefinition" 
 package="cmc/promotion"/>

Add your custom purchase condition by inserting the following code under the previous section:


<!-- Customization: New Promotion Type -->
<PromotionElementObjectDefinition baseDefinition="cmc/promotion/ExtProductLevelFreeGiftPurchaseConditionObjectDefinition" 
 package="cmc/promotion"/>

Save and close the file.

You have now created the promotion element object definition. When business users create new promotions in the Management Center, the promotion element object definition will enable promotion element data to be stored in two tables: PX_ELEMENT and PX_ELEMENTNVP. The data stored in these two tables are in tree structure. When the business user activates the promotion, the following takes place:

The HCL Commerce Server reads the data stored in the PX_ELEMENT and PX_ELEMENTNVP tables and constructs the authoring promotion XML.
XSL templates transform the authoring promotion XML into the runtime promotion XML. (You learn more about these XSL templates in the lesson Creating and registering the XSL template.)
The runtime promotion XML is saved to the PX_PROMOTION table.
The promotion engine then uses the runtime promotion XML to evaluate promotions during the shopping flow.

The authoring promotion XML is a simplified representation of a promotion in the Management Center. A sample authoring promotion XML looks like this:


<PurchaseCondition 
  impl="com.ibm.commerce.marketing.promotion.condition.PurchaseCondition">
  <Pattern impl="com.ibm.commerce.marketing.promotion.condition.Pattern">
  <UniqueConstraints>false</UniqueConstraints>
  <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>HKT030_3001</SKU>
  <DN>ou=asset store organization,o=extended sites organization,o=root organization</DN>
  </CatalogEntryKey>
  </IncludeCatEntryKey>
  <IncludeCatEntryKey>
  <CatalogEntryKey>
  <SKU>HKT030_3002</SKU>
  <DN>ou=asset store organization,o=extended sites organization,o=root organization</DN>
  </CatalogEntryKey>
  </IncludeCatEntryKey>
  </Filter>
  </FilterChain>
  </Constraint>
  </Pattern>
  <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>HTA029_291001</SKU>
  <DN>ou=asset store organization,o=extended sites 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>
</PurchaseCondition>

Results

In this lesson, you created the object definition for the new promotion type. In the next lesson, you create the template for the promotion user interface.