Creating the child object definition for the new promotion type

In this lesson, you define a new OpenLaszlo child object definition class or a new Management Center 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:

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

  1. Create a new file for the promotion element object definition:
    OptionDescription
    WebSphere Commerce Version 7.0.0.0Feature Pack 1Create a new OpenLaszlo file WebSphere Commerce Version 7.0.0.0Feature Pack 1
    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.
    Introduced in Feature Pack 2Create a new definition file Introduced in Feature Pack 2
    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.
  2. Define the promotion element object definition:
    OptionDescription
    WebSphere Commerce Version 7.0.0.0Feature Pack 1ProductLevelFreeGiftPurchaseConditionObjectDefinition.lzx WebSphere Commerce Version 7.0.0.0Feature Pack 1
    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.

    Introduced in Feature Pack 3Feature Pack 2ProductLevelFreeGiftPurchaseConditionObjectDefinition.def Introduced in Feature Pack 3Feature Pack 2
    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.

  3. WebSphere Commerce Version 7.0.0.0Feature Pack 1Register the OpenLaszlo object in the promotion extensions library:
    1. In the PromotionExtensionsLibrary.lzx file, which should still be open from a previous step, add the following include statement within the <library> element:
      <include href="../../mycompany/promotion/objectDefinitions/elements/ProductLevelFreeGiftPurchaseConditionObjectDefinition.lzx"/>
    2. Save the file.
  4. Now that your custom purchase condition has been defined, complete one of the following steps:
    OptionDescription
    WebSphere Commerce Version 7.0.0.0Feature Pack 1Create an instance of the new object definition for use in the Promotions tool WebSphere Commerce Version 7.0.0.0Feature Pack 1
    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.
    The authoring promotion XML is a simplified representation of a promotion in the Management Center. A sample authoring promotion XML looks like this:
    
    <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>
    
    Introduced in Feature Pack 3Feature Pack 2Add the new object definition to the Promotion primary object Introduced in Feature Pack 3Feature Pack 2
    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.
    The authoring promotion XML is a simplified representation of a promotion in the Management Center. A sample authoring promotion XML looks like this:
    
    <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>
    
  5. WebSphere Commerce Version 7.0.0.0Feature Pack 1Right-click the LobTools project; then click Build OpenLaszlo Project on the context menu.

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.