Creating the child object definition for the new promotion type

1. In the Enterprise Explorer view, navigate to the LOBTools > WebContent > WEB-INF > src > lzx > mycompany > promotion > objectDefinitions > elements directory.
2. Right-click the elements directory; then click New > File.
3. Name your new file ProductLevelFreeGiftPurchaseConditionObjectDefinition.lzx.
4. Click Finish to save the file. The file opens in the default XML editor.

1. In the Enterprise Explorer view, navigate to the LOBTools > WebContent > config directory.
2. Right-click the config directory; then click New > Folder.
3. Specify 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.def.
6. Click Finish to create the file. The file opens in the default XML editor.

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

   
   <library>
     <class name="extProductLevelFreeGiftPurchaseConditionObjectDefinition" extends="proPurchaseConditionObjectDefinition"
          1 objectType="ProductLevelFreeGiftPurchaseCondition">
          3 <proIdentifierCatalogEntryObjectDefinition>
             <dataset name="template">
                  2 <elementType>IncludeCatalogEntryIdentifier</elementType>
             </dataset> 
          </proIdentifierCatalogEntryObjectDefinition> 
   
          <proIdentifierInheritedCatalogEntryObjectDefinition>
             <dataset name="template">
                  <elementType>IncludeCatalogEntryIdentifier</elementType>
             </dataset> 
          </proIdentifierInheritedCatalogEntryObjectDefinition> 
   
          <!-- property definition: The total price threshold for the promotion condition -->
          <wcfPropertyDefinition propertyName="BaseItemTotalPrice" required="true" minValue="1"
                   displayName="${extPromotionResources.promotion_Minimum_purchase_TotalPrice.string}" />   
   
          4 <proIdentifierGiftCatalogEntryObjectDefinition>
              <dataset name = "template">
                  <elementType>GiftCatalogEntryIdentifier</elementType>
              </dataset>
              <!--property definition: the quantity of each gift -->
              <wcfPropertyDefinition
                  propertyName = "giftQuantity"
                  required = "true"
                  minValue = "1"
                  displayName = "${extPromotionResources.promotion_Free_gift_qty.string}"/>
          </proIdentifierGiftCatalogEntryObjectDefinition>
   
          <proIdentifierInheritedGiftCatalogEntryObjectDefinition>
              <dataset name = "template">
                  <elementType>GiftCatalogEntryIdentifier</elementType>
              </dataset>
              <!--property definition: the quantity of each gift -->
              <wcfPropertyDefinition
                  propertyName = "giftQuantity"
                  required = "true"
                  minValue = "1"
                  displayName = "${extPromotionResources.promotion_Free_gift_qty.string}"/>
                 </proIdentifierInheritedGiftCatalogEntryObjectDefinition>
   
          <!-- Validator definition: The condition catentry set cannot be empty, at least one catentry should be assigned --> 
          <wcfRequiredChildObjectValidator validatorId="reqChildValidator1" objectPath="Identifier_CatalogEntry" errorMessage="${promotionResources.promotion_error_AtLeastOneProduct.string}"/>
   
          <!-- Validator definition: The gift set cannot be empty, at least one gift should be assigned -->
          <wcfRequiredChildObjectValidator validatorId="reqChildValidator2" objectPath="Identifier_GiftCatalogEntry" errorMessage="${promotionResources.promotion_error_AtLeastOneGift.string}"/>  
     </class>
   </library>
   

   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 classes.

   2 <elementType>

   This element is contained within the <proIdentifierCatalogEntryObjectDefinition> 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.

   3 <proIdentifierCatalogEntryObjectDefinition>

   This element 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. A <proIdentifierInheritedCatalogEntryObjectDefinition> element is also included to support catalog entries inherited from a master catalog.

   4 <proIdentifierGiftCatalogEntryObjectDefinition>

   This element also references the catalog entry object; in this case, the catalog entry is the free gift. A <proIdentifierInheritedGiftCatalogEntryObjectDefinition> element is also included to support gift catalog entries inherited from a master catalog.

2. Save and close the file.

The new object extends the existing proPurchaseConditionObjectDefinition subclass.

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

   <Definitions>
       <PromotionElementObjectDefinition
           baseDefinitionName="proPurchaseConditionObjectDefinition"
           definitionName="extProductLevelFreeGiftPurchaseConditionObjectDefinition"
           1 objectType="ProductLevelFreeGiftPurchaseCondition" package="pro">
           3 <PromotionElementReferenceObjectDefinition
               baseDefinitionName="proIdentifierCatalogEntryObjectDefinition" package="pro">
               <Xml name="template">
                   2 <elementType>IncludeCatalogEntryIdentifier</elementType>
               </Xml> 
           </PromotionElementReferenceObjectDefinition>
   
           3 <PromotionElementReferenceObjectDefinition
               baseDefinitionName="proIdentifierInheritedCatalogEntryObjectDefinition"
               package="pro">
               <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"/>
                      
           3 <PromotionElementReferenceObjectDefinition
               baseDefinitionName="proIdentifierGiftCatalogEntryObjectDefinition"
               package="pro">
          	    <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> 
   
           3 <PromotionElementReferenceObjectDefinition
               baseDefinitionName="proIdentifierInheritedGiftCatalogEntryObjectDefinition"
               package="pro">
               <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_CatalogEntry" validatorId="reqChildValidator1"/>
   
           <!--
               Validator definition: The gift set cannot be empty, at least one gift should
               be assigned
           -->
           <RequiredChildObjectValidator
               errorMessage="${promotionResources.promotion_error_AtLeastOneGift}"
               objectPath="Identifier_GiftCatalogEntry" validatorId="reqChildValidator2"/>
       </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 <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.

   3 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.

2. Save and close the file.

The new object extends the existing proPurchaseConditionObjectDefinition definition.

1. In the Enterprise Explorer view, navigate to the LOBTools > WebContent > WEB-INF > src > lzx > commerce > promotion > objectDefinitions directory.
2. Open the PromotionPrimaryObjectDefinition.lzx file. This primary object contains all the information about a promotion in the Management Center. Observe the services, properties and child objects defined here.
3. Locate the following lines, which are instances of other purchase condition object definitions:

       <proProductLevelSameItemPercentDiscountPurchaseConditionObjectDefinition/>
       <proProductLevelValueDiscountPurchaseConditionObjectDefinition/>
       <proProductLevelPWPPercentDiscountPurchaseConditionObjectDefinition/>
   

4. Create an instance of your custom purchase condition by inserting the following code under the previous section:

   <!-- Customization: New Promotion Type -->
   <extProductLevelFreeGiftPurchaseConditionObjectDefinition/>
   <!-- Customization End -->
   

5. Save and close the file.
6. Right-click the PromotionPrimaryObjectDefinition.lzx. file; then click Build OpenLaszlo Project on the context menu.

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:

1. The WebSphere Commerce Server reads the data stored in the PX_ELEMENT and PX_ELEMENTNVP tables and constructs the authoring promotion XML.
2. 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.)
3. The runtime promotion XML is saved to the PX_PROMOTION table.
4. The promotion engine then uses the runtime promotion XML to evaluate promotions during the shopping flow.

<PurchaseCondition>
      <Data>
             <Currency>USD</Currency>
             <BaseItemTotalPrice>1000</BaseItemTotalPrice>
      </Data>
      <GiftCatalogEntryIdentifier>
                 <Data>
                        <giftQuantity>3</giftQuantity>
                        <Id>10276</Id>
                        <DN>ou=b2c,o=seller organization,o=root organization</DN>
                        <SKU>FUCO-0101</SKU>
                 </Data>
      </GiftCatalogEntryIdentifier>
      <IncludeCatalogEntryIdentifier>
                 <Data>
                        <Id>10251</Id>
                        <DN>ou=b2c,o=seller organization,o=root organization</DN>
                        <SKU>FULO-01</SKU>
                 </Data>
      </IncludeCatalogEntryIdentifier>
</PurchaseCondition>

1. In the Enterprise Explorer view, navigate to the LOBTools > WebContent > config > commerce > promotion > objectDefinitions directory.
2. Open the PromotionPrimaryObjectDefinition.def file. This primary object contains all the information about a promotion in the Management Center. Observe the services, properties and child objects defined here.
3. Locate the following lines, which are declarations of other purchase condition object definitions:

   <PromotionElementObjectDefinition baseDefinitionName="proCategoryLevelPerItemPercentDiscountPurchaseConditionObjectDefinition" package="pro"/>
   <PromotionElementObjectDefinition baseDefinitionName="proProductLevelPerItemValueDiscountPurchaseConditionObjectDefinition" package="pro"/>		
   <PromotionElementObjectDefinition baseDefinitionName="proCategoryLevelPerItemValueDiscountPurchaseConditionObjectDefinition" package="pro"/>

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

   <!-- Customization: New Promotion Type -->
   <PromotionElementObjectDefinition baseDefinitionName="extProductLevelFreeGiftPurchaseConditionObjectDefinition" package="pro"/>
   <!-- Customization End -->

5. 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:

1. The WebSphere Commerce Server reads the data stored in the PX_ELEMENT and PX_ELEMENTNVP tables and constructs the authoring promotion XML.
2. 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.)
3. The runtime promotion XML is saved to the PX_PROMOTION table.
4. The promotion engine then uses the runtime promotion XML to evaluate promotions during the shopping flow.

<PurchaseCondition>
      <Data>
             <Currency>USD</Currency>
             <BaseItemTotalPrice>1000</BaseItemTotalPrice>
      </Data>
      <GiftCatalogEntryIdentifier>
                 <Data>
                        <giftQuantity>3</giftQuantity>
                        <Id>10276</Id>
                        <DN>ou=b2c,o=seller organization,o=root organization</DN>
                        <SKU>FUCO-0101</SKU>
                 </Data>
      </GiftCatalogEntryIdentifier>
      <IncludeCatalogEntryIdentifier>
                 <Data>
                        <Id>10251</Id>
                        <DN>ou=b2c,o=seller organization,o=root organization</DN>
                        <SKU>FULO-01</SKU>
                 </Data>
      </IncludeCatalogEntryIdentifier>
</PurchaseCondition>