How promotion data is stored and managed

If you are creating a new custom promotion type for Management Center, you should understand how the Management Center interacts with the promotion component, and how promotions are stored in the database.

Promotion XML

There are two types of promotion XML:

The authoring promotion XML contains the data about a promotion that business users input into the Promotions tool user interface when authoring promotions. The authoring promotion XML was introduced with Management Center Version 6 Feature Pack 4 to make promotions customization easier.
The runtime promotion XML is used by the server to evaluate promotions during the shopping flow. The runtime promotion XML has not changed from previous Management Center feature packs.

When a business user activates a promotion, the following process transforms the authoring promotion XML into the runtime promotion XML:

The promotion activation logic builds the authoring promotion XML from data stored in the Management Center promotion authoring tables. These tables contain the business user input about a promotion.
A set of XSLT templates transform the authoring promotion XML into the runtime promotion XML that the promotion engine requires to evaluate promotions. The transformation involves several steps:
1. The XSLT template files transform the authoring promotion XML to create four sections of the runtime promotion XML: the basePromotion section, the purchaseCondition section, the customCondition section, and the targetingCondition section.
2. The transformation process uses the fromXML interface to initialize a promotion object.
3. The transformation process uses the toXML interface to generate the runtime promotion XML and store it in the PX_PROMOTION table in the XMLPARAM column.

The following diagram illustrates this process:

Note that until a promotion is activated, only placeholder promotion XML is stored in the PX_PROMOTION table.

XSLT templates

To add a new promotion type, developers can design widgets that gather the required input and save the input to the promotion authoring tables. As shown in the previous diagram, XSLT templates then transform the authoring promotion XML into the runtime promotion XML. Therefore, customizing the runtime support for a new promotion type only requires a custom XSLT template to support the user interface widgets; developers do not need to make backend Java code changes to compose the runtime promotion XML. This makes customizing Management Center promotion types simpler than customizing WebSphere Commerce Accelerator promotion types.

Each promotion type defined in the Management Center Promotions tool is configured to work with certain XSLT templates. The Promotions tool provides the set of XSLT templates that transform the default promotions types. When you create a custom promotion type, you must create a new custom XSLT template; however, you can copy the content of an existing XSLT template into your new file and then customize only the sections that are different.

Promotion elements and variables

Promotion elements and their variables allow the Management Center Promotions tool to manage the authoring data for the purchaseCondition section, the customCondition section, and the targetingCondition section of the runtime promotion XML in a generic framework.

Information about a promotion element and its variables are saved in the PX_ELEMENT and PX_ELEMENTNVP tables. To illustrate this relationship, consider the following sample data.

Sample PX_ELEMENT table content
PX_ELEMENT_ID	PX_PROMOTION_ID	NAME	TYPE	SubType	Parent	Sequence
1001	10101	Name1001	PurchaseCondition	UI_PurchaseCondition	NULL	0
1002	10101	Name1002	DiscountRange	UI_DiscountRange	Name1001	0
1003	10101	Name1003	DiscountRange	UI_DiscountRange	Name1001	1

Sample PX_ELEMENTNVP table content
PX_ELEMENTNVP_ID	PX_ELEMENT_ID	NAME	VALUE	Note
1000000	1001	Currency	USD	The currency is USD
1000001	1002	LowerBound	100	For range of Name1002 , the lowerbound=100
1000002	1002	Percentage	10	For range of Name1002, the Percentage=10
1000003	1003	LowerBound	500	For range of Name1003, the lowerbound=500
1000004	1003	Percentage	50	For range of Name1003, the Percentage=50

In the previous example, the promotion element is used to describe a unit of a promotion rule. The TYPE column of the PX_ELEMENT table can be mapped to a promotion concept that is used in the runtime promotion XML. For example, a PurchaseCondition element type is mapped to the PurchaseCondition node in the runtime promotion XML. Likewise, the DiscountRange type is mapped to the DistributionRange nodes in the runtime promotion XML. The SUBTYPE column of the PX_ELEMENT table is used by the Management Center Promotions tool to identify a specific widget that handles the input from a business user. The parent-child relationship information in the PARENT and SEQUENCE columns of the PX_ELEMENT table allows the promotion activation logic to build the XML tree structure of the authoring promotion XML. Here is an example:

<PurchaseCondition>
   <DiscountRange></DiscountRange>
   <DiscountRange></DiscountRange>
</PurchaseCondition>

A promotion element variable describes the optional data value associated with a promotion element. When a business user activates a promotion, the promotion activation logic builds the authoring promotion XML and inserts a data node under the appropriate promotion element node, followed by text nodes that are built according to the name and value from the PX_ELEMENTNVP table for the element. Here is an example:

<PurchaseCondition>
   <Data>
     <Currency>USD</Currency>
   </Data>
   <DiscountRange>
     <Data>
       <LowerBound>100</LowerBound>
       <Percentage>10</Percentage>
     </Data>
   </DiscountRange>
   <DiscountRange>
     <Data>
       <LowerBound>500</LowerBound>
       <Percentage>50</Percentage>
     </Data>
   </DiscountRange> 
</PurchaseCondition>

Predefined element types

In the runtime promotion XML, a business entity key is defined with external identifiers. Here is an example of a targeted customer profile key:

<TargetedProfile>
   <CustomerProfileKey>
      <ProfileName>Customers who are under 40 years of age</ProfileName>
      <OwnerDN>ou=b2c,o=seller organization,o=root organization</OwnerDN> 
   </CustomerProfileKey>  
</TargetedProfile>

To simplify the design of the Management Center Promotions tool and to improve performance, there are several predefined element types that allow such business entities to be managed with only the primary key (ID). The promotion activation service then uses this ID to resolve external identifier information that is required in the runtime promotion XML and then add that information to the authoring promotion XML as if the information was gathered from the user interface. This resolved external identifier information is inserted into the data node of the element so that it is available for transformation.

The following example is a piece of the authoring promotion XML, which is based on element data with the external identifiers resolved (the complete authoring promotion XML is used for the XSL transformation process):

<TargetingCondition>
   <IncludeMemberGroupIdentifier>
      <Data>
         <Id>8000000000000000551</Id>
         <DN>ou=b2c,o=seller organization,o=root organization</DN>
         <Name>Registered Customers</Name>
      </Data>
   </IncludeMemberGroupIdentifier>
   <ExcludeMemberGroupIdentifier>
      <Data>
         <Id>8000000000000000555</Id>
         <DN>ou=b2c,o=seller organization,o=root organization</DN>
         <Name>Female Customers</Name>
      </Data>
   </ExcludeMemberGroupIdentifier>
   <ExcludeMemberGroupIdentifier>
      <Data>
         <Id>8000000000000000553</Id>
         <DN>ou=b2c,o=seller organization,o=root organization</DN>
         <Name>Guest Shoppers</Name>
      </Data>
   </ExcludeMemberGroupIdentifier>
   <IncludeMemberGroupIdentifier>
      <Data>
         <Id>8000000000000000554</Id>
         <DN>ou=b2c,o=seller organization,o=root organization</DN>
         <Name>Male Customers</Name>
      </Data>
   </IncludeMemberGroupIdentifier> 
</TargetingCondition>

The list of predefined element types includes the following items. While not all of these predefined elements are currently used by the default promotion types, they are provided to support customization.

IncludeMemberGroupIdentifier: A member group that is part of an inclusion condition in the rule.
ExcludeMemberGroupIdentifier: A member group that is part of an exclusion condition in the rule.
IncludeCategoryIdentifier: A category that is part of an inclusion condition in the rule.
ExcludeCategoryIdentifier: A category that is part of an exclusion condition in the rule.
IncludeCatalogEntryIdentifier: A catalog entry that is part of an inclusion condition in the rule.
ExcludeCatalogEntryIdentifier: A catalog entry that is part of an exclusion condition in the rule.
GiftCatalogEntryIdentifier: A catalog entry that is a free gift in the rule.
IncludePromotionIdentifier: A promotion that is part of an inclusion condition in the rule.
ExcludePromotionIdentifier: A promotion that is part of an exclusion condition in the rule.
IncludeShipModeIdentifier: A ship mode that is part of an inclusion condition in the rule.
ExcludeShipModeIdentifier: A ship mode that is part of an exclusion condition in the rule.
IncludeStoreIdentifier: A store that is part of an inclusion condition in the rule.
ExcludeStoreIdentifier: A store that is part of an exclusion condition in the rule.
IncludeUserIdentifier: A user that is part of an inclusion condition in the rule.
ExcludeUserIdentifier: A user that is part of an exclusion condition in the rule.

To use these predefined element types, use an element name-value pair using the name Id and the appropriate value as the primary key. Use these predefined element types whenever possible. When a promotion is activated, the Id values are also used to populate the CATENCALCD and CATGPCALCD tables to support the ShopcartDrivenAgendaBuilder.