Creating the object definitions for the new promotion type

Define new OpenLaszlo promotion element object definitions to collect input from the Management Center. When business users create new promotions in the Management Center, the promotion element object definitions persist promotion element data in two tables: PX_ELEMENT and PX_ELEMENTNVP.

Before you begin

Review the following topics to ensure that you understand object definitions in Management Center and the proPurchaseConditionObjectDefinition class or proPurchaseConditionObjectDefinition definition that you must extend, as well as the database tables that store promotion authoring data:

Object definitions
proPurchaseConditionObjectDefinition class
proPurchaseConditionObjectDefinition definition declared in config/commerce/promotion/objectDefinition/elements/PurchaseConditionObjectDefinition.def
How promotion data is stored and managed
Promotion authoring tables for Management Center:
- PX_ELEMENT
- PX_ELEMENTNVP

About this task

In the Promotions tool, each promotion type has its own object definition. If you are creating a new purchase condition, the object definition defines a purchase condition for the new promotion type and it must be:

an extension class of the proPurchaseConditionObjectDefinition class. This class is one of the root element definitions that extends the promotion purchase condition root element, and it includes all the subelements of the promotion, such as the purchase condition and reward.
a definition that is based on the proPurchaseConditionObjectDefinition definition. This definition is one of the root element definitions that extends the promotion purchase condition root element, and it includes all the subelements of the promotion, such as the purchase condition and reward.

When a business user creates a promotion, the input data about the promotion is persisted in the PX_ELEMENT and PX_ELEMENTNVP tables. When the business user activates the promotion, the input data is used to form the authoring promotion XML; XSLT templates then transform the authoring promotion XML to the runtime promotion XML.

Procedure

Examine the abbreviated XML structure you created in the previous procedure (Identifying the business user input for the new promotion type) and identify each node in the structure as either:
- An element: These are nodes that have child nodes.
- A name-value pair (NVP): These are nodes that do not have child elements and they are used to describe a value.
See the example section after the last step of this procedure.
Now that you have identified the elements and name-value pairs, you can build the object definition to collect information from the Management Center user interface and persist the data in the PX_ELEMENT and PX_ELEMENTNVP tables.
Open WebSphere Commerce Developer and switch to the Enterprise Explorer view.
Create a directory to store your new promotion element object definition.
You can store the file in a directory structure similar to the following example:
- LOBTools/WebContent/WEB-INF/src/lzx/your_company_name/promotion/objectDefinitions/elements/
- LOBTools/WebContent/config/your_company_name/promotion/objectDefinitions/elements
Create a new file for the promotion element object definition:
- OpenLaszlo (.lzx) file
- Definition (.def) file
Define the promotion element object definition.
See the sample promotion element object definition after the last step of this procedure.
Register the OpenLaszlo object in the PromotionExtensionsLibrary.lzx file.
The file is stored at this path:
LOBTools/WebContent/WEB-INF/src/lzx/commerce/promotion/

Complete one of the following steps:

Option	Description
Create an instance of the new object definition in its parent	For example, if the parent file is PromotionPrimaryObjectDefinition.lzx, the file is stored in the LOBTools/WebContent/WEB-INF/src/lzx/commerce/promotion/objectDefinitions directory.
Add the new promotion element object definition to the base promotion primary object definition	The base promotion primary object definition is defined in the PromotionPrimaryObjectDefinition.def file. This file is stored in the LOBTools/WebContent/config/commerce/promotion/objectDefinitions directory.

Example

For your custom promotion type, Customers who purchase two dining chairs (FULO-01) qualify to purchase a dining table (FULO-02) at the reduced price of $200, you must create a purchase condition object definition with the following name: ProductLevelPWPFixedCostPurchaseCondition.

First, you examine the abbreviated XML structure you previously created and identify each node in the structure as either an element or a name-value pair (NVP) as shown here:

For this custom promotion type, you reuse the predefined IncludedCatalogEntryIdentifier to gather the catalog entry ID.

When a business user activates a promotion created with your custom promotion type, the authoring promotion XML will be built from the PX_ELEMENT and PX_ELEMENTNVP tables. The authoring promotion XML looks like the following sample:

<PurchaseCondition> 	
   <Data>
      <Currency>USD<Currency>
  	   <FixedCost>200</FixedCost> 
   </Data>
   <Purchase> 		
      <Data>
         <Quantity>2</Quantity> 		
      </Data>
      <IncludeCatalogEntryIdentifier> 	
         <Data>
            <Id>10251</Id>
            <SKU>FULO-01</SKU>
            <DN>ou=b2c,o=seller organization,o=root organization</DN> 
         </Data>
      </IncludeCatalogEntryIdentifier>
   </Purchase> 
   <Reward> 		
      <Data>
         <Quantity>1</Quantity>
      </Data>		
      <IncludeCatalogEntryIdentifier>
         <Data>
            <Id>10253<Id>
            <SKU>FULO-02</SKU>
            <DN>ou=b2c,o=seller organization,o=root organization</DN> 
         </Data>
      </IncludeCatalogEntryIdentifier> 	
   </Reward> 	
</PurchaseCondition>

The corresponding PX_ELEMENT and PX_ELEMENTNVP tables look like the following examples:

Sample PX_ELEMENT data
PX_ELEMENT_ID	PX_PROMOTION_ID	NAME	TYPE	SUBTYPE	PARENT
65	10002701	'65'	'PurchaseCondition'	'ProductLevelPWPFixedCostPurchaseCondition'	NULL
66	10002701	'66'	'Reward'	'Reward'	'65'
67	10002701	'67'	'IncludeCatalogEntryIdentifier'	'Identifier_CatalogEntry'	'66'
68	10002701	'68'	'Purchase'	'Purchase'	'65'
69	10002701	'69'	'IncludeCatalogEntryIdentifier'	'Identifier_CatalogEntry'	'68'

Sample PX_ELEMENTNVP data
PX_ELEMENTNVP_ID	PX_ELEMENT_ID	NAME	VALUE
65	65	'Currency'	'USD'
66	65	'FixedCost'	'200'
68	66	'Quantity'	'1'
69	67	'Id'	'10253'
70	68	'Quantity'	'2'
71	69	'Id'	'10251'

There are some default predefined element types, such as IncludeCatalogEntryIdentifier, that require an additional process in the Java command to generate the corresponding XML fragment, which contains a unique index such as SKU and distinguished name (DN). This new promotion type in this example uses the predefined IncludedCatalogEntryIdentifier element type.

Next, you create the new ProductLevelPWPFixedCostPurchaseCondition object definition. It looks like the following sample. In this sample, you can see the existing promotion element object definitions proPWPPurchaseItemObjectDefinition and proPWPRewardItemObjectDefinition are reused.

<class name="proProductLevelPWPFixedCostPurchaseConditionObjectDefinition"
      extends="proPurchaseConditionObjectDefinition"
      objectType="ProductLevelPWPFixedCostPurchaseCondition">
   <proPWPPurchaseItemObjectDefinition>
      <dataset name="template">
         <elementType>Purchase</elementType>
      </dataset>
   </proPWPPurchaseItemObjectDefinition>
   <proPWPRewardItemObjectDefinition>
      <dataset name="template">
         <elementType>Reward</elementType>
      </dataset>
   </proPWPRewardItemObjectDefinition>
   <wcfPropertyDefinition propertyName="FixedCost" required="true" minValue="0" 
         displayName="Fixed cost (no translation)" />
</class>

<PromotionElementObjectDefinition
   package="pro"
   definitionName="proProductLevelPWPFixedCostPurchaseConditionObjectDefinition"
   baseDefinitionName="proPurchaseConditionObjectDefinition"
   objectType="ProductLevelPWPFixedCostPurchaseCondition">
   <PromotionElementObjectDefinition
      package="pro"
      baseDefinitionName="proPWPPurchaseItemObjectDefinition">
      <Xml name="template">
         <elementType>Purchase</elementType>
      </Xml>
   </PromotionElementObjectDefinition>
   <PromotionElementObjectDefinition
      package="pro"
      baseDefinitionName="proPWPRewardItemObjectDefinition">
      <Xml name="template">
         <elementType>Reward</elementType>
      </Xml>
   </PromotionElementObjectDefinition>
   <PropertyDefinition propertyName="FixedCost" required="true" minValue="0" 
         displayName="Fixed cost (no translation)" />
</PromotionElementObjectDefinition>

Finally, you complete one of the following steps:

Instantiate the custom object definition under the parent object definition. For this example, the purchase condition is under the base PromotionPrimaryObjectDefinition:

<class name="proBasePromotionPrimaryObjectDefinition" 	
      extends="wcfPrimaryObjectDefinition" 	
      isBaseDefinition="true" 	
      objectType="BasePromotion" ...>
      .
      .
      .
   <proProductLevelPWPFixedCostPurchaseConditionObjectDefinition/>
   .
   .
</class>

Add the custom object definition to the base promotion primary object definition:

<PrimaryObjectDefinition definitionName="proBasePromotionPrimaryObjectDefinition" 	
   isBaseDefinition="true"...>
      .
      .
      .
   <PromotionElementObjectDefinition
      baseDefinitionName="proProductLevelPWPFixedCostPurchaseConditionObjectDefinition"
      package="pro"/>
   .
   .
</PrimaryObjectDefinition>