Load promotions with the Data Load utility

Load promotions with the Data Load utility
We can configure the Data Load utility to load promotion data in an XML input file to create or change promotions in a store. By using the Data Load utility to load promotions, we can quickly create or change multiple promotions in a single operation.

Task info

When you load promotion data with the Data Load utility, the utility uses the DOMXmlHandler class to convert the promotion input XML data into a DOM object. The utility then passes the object to the PromotionDOMMediator business object mediator, which converts the object into a list of table data objects. The table data objects are then persisted into the database. After the load process completes, the promotions can be available for business users to view and manage in the Promotions tool.
The Data Load utility does not support loading promotion data into a workspace.
Note: We cannot use the Data Load utility to set or change the state for a promotion.

If we are creating a promotion with the Data Load utility, the promotion is always inactive when the load process completes. For example, if we are loading an extracted promotion into a test environment, the created promotion is inactive even if the promotion was active when it was extracted.
If we are changing a promotion with the Data Load utility, the current promotion state does not change. For example, if we are changing an active promotion, the promotion remains active after the load process completes. The changes for active promotions might not display in the storefront when the load process completes. We need to deactivate and reactivate the promotion to enable the promotion updates on the storefront.

Procedure
Create your input XML file. We can only load promotion data that is in an XML formatted file. For an example of the supported XML format, view the sample Promotion.xml input file that is in the following directory.

(Developer) WCDE_installdir\samples\DataLoad\Promotion
(Linux) utilities_root/samples/DataLoad/Promotion
If we are creating your input file manually, copy and edit the sample Promotion.xml file to help us create your input file.Tip: We can use the Data Extract utility to help you generate your input file. If we are creating the same promotion in multiple environments, such as for testing purposes, create the promotion in one environment with the Promotions tool. Then, extract that promotion and use the generated output file as the input file for the Data Load utility to load the promotion into your other environments. For more information, see Extracting promotion data with the Data Extract utility In your input file, include the following information for each promotion:
The identifying and general properties for a promotion inside an XML element named <Base>. This information includes any data about the promotion codes for the promotions, such as the type of promotions codes for the promotion. We can specify a public promotion code or pattern for generating advanced unique promotion codes, but do not include any unique promotion codes. We cannot load unique promotions codes with the Data Load utility. The Data Load utility loads the data in the <Base> element into the following database tables:

PX_PROMOTION
PX_PROMOAUTH
PX_GROUP
CALCODE
PX_CDSPEC

The promotion description information inside an XML element named <Description>. Include a separate <Description> for each defined language that the store supports for the promotion. The Data Load utility loads this data into the PX_DESCRIPTION database table.
The promotion purchase condition and reward information inside an XML element named <Elements>. The Data Load utility loads this data into the PX_ELEMENT and PX_ELEMENTNVP database tables. Include each name-value pair that must be loaded into the PX_ELEMENTNVP table as a separate XML element inside a parent element, which is to be loaded into the PX_ELEMENT table. For example, the following code demonstrates the structure for the <Elements> element in an input file.
<Elements>
  <Type>
    <SubType>...</SubType>
    <Sequence>...</Sequence>
    <Data> 
      <name>value</name>
      <name>value</name>
    </Data>
    <Type>
	      <SubType>...</SubType>
      <Sequence>...</Sequence>
      <Data> 
        <name>value</name>
        <name>value</name>
      </Data>
    </Type>
    ...
  </Type>
<Elements>
Where
Elements

Indicates that the child XML elements are purchase condition and reward information. Each direct child element in the <Elements> element is a separate type of condition or reward. Does not map to any column. This element is for use by the Data Load utility to read the promotion input file XML.

Type
The name of a promotion condition or reward. Your input XML can include multiple <Type> elements. A <Type> element can be nested within another <Type> element. For example, the following code includes a <Type> element called <IncludePaymentTypeIdentifier>, which is nested inside a <Type> element called <PurchaseCondition>.
<Elements>
  <PurchaseCondition>
    ...
    <IncludePaymentTypeIdentifier>
	  ...
    </IncludePaymentTypeIdentifier>
  </PurchaseCondition>
  ...
  <Elements>
Maps to PX_ELEMENT.TYPE.
SubType

The subtype of a promotion element <Type>. Each <Type> can have a <SubType>. For example, a <Type> element that is named <PurchasingCondition> might have a <SubType> element called <OrderLevelPercentDiscountPurchaseCondition>. Maps to PX_ELEMENT.SUBTYPE

Sequence

The sequence that the promotion purchase condition or reward element, <Type>, displays for a promotion. Each <Type> element can include a <Sequence> element. Maps to PX_ELEMENT.SEQUENCE

Data

Indicates that the child XML elements are name-value pair information for a parent element (purchase condition or reward). Include each name-value pair as a separate element within a <Data> element. Each <Type> element can include a <Data> element. Does not map to any column. This element is for use by the Data Load utility to read the promotion input file XML.

name

The name of a name-value pair. Maps to PX_ELEMENTNVP.NAME

value

The value for a name-value pair. Maps to PX_ELEMENTNVP.VALUE
Important: The names of the XML elements in your input file, other than the root element and the elements for name-value pairs, must use specific names. For a list of the XML elements that we can include in your input file and the specific names for you to use for the elements, see Promotions XML input file.
To load data to change data for a promotion, we must configure your input file to include the unique ID for the promotion. Include the ID as the value for an element named, <PromotionId>. The utility compares the ID in the input file to the promotion ID values in the database. If the ID exists in the database, the utility updates the existing promotion with the information in the input file. For example, the following code snippet sets the unique ID, "10001", for a promotion named "Free Ground Shipping":
<?xml version="1.0" encoding="UTF-8"?>
<Promotions>
<PromotionData>
  <Base>
    <PromotionId>10001</PromotionId>
    <AdministrativeName>Free Ground Shipping</AdministrativeName>
    ...
  </Base>
    ...
  <Elements>
    <PurchaseCondition>
      <SubType>OrderLevelFixedShippingDiscountPurchaseCondition</SubType>
      <Sequence>0.0</Sequence>
      <Data>
        <Currency>USD</Currency>
        <MinimumPurchase>70</MinimumPurchase>
        <FixedCost>0</FixedCost>
        <AdjustmentType>IndividualAffectedItems</AdjustmentType>
      </Data>
    </PurchaseCondition>
  </Elements>
</PromotionData>
</Promotions>
Create the Data Load utility configuration files that you need to load your promotion data.

Go to the following directory, which contains the sample configuration files for loading promotion data:

(Developer) WCDE_installdir\samples\DataLoad\Promotion
(Linux) utilities_root/samples/DataLoad/Promotion

Create a backup of the following configuration files in the sample Promotion directory.

wc-loader-xml-promotion.xml

The business object configuration file.

wc-dataload-env.xml

The environment configuration file.

wc-dataload.xml

The data load order configuration file.
Optional: Open the business object configuration file (wc-loader-xml-promotion.xml) for editing and configure the settings for loading your promotion data.
Configure the Data Load utility to allow the load process to create a promotion that has an administrative name that is a duplicate of an existing promotion name. To configure this behavior, include the following property in the <_config:BusinessObjectMediator> element configuration.
allowDuplicateAdministrativeName
This property configures the Data Load utility to create a promotion instead of skipping the promotion when the promotion has the same administrative name as an existing promotion. We can set the following values for this property.

true

The Data Load utility creates a promotion in the store for each promotion in the input file regardless of whether a duplicate administrative name exists. By setting this value, the Data Load utility creates all promotions that are in the input file. By enabling this property, the load process can create duplicate promotions in a store.

false

The default value. If a duplicate administrative name is encountered during the load operation, the Data Load utility does not load the promotion with the duplicate name. The Data Load summary report does report that a promotion did not load.

For example, the following code snippet configures the enabling of this property:
<_config:BusinessObjectMediator className="com.ibm.commerce.promotion.dataload.mediator.PromotionDOMMediator" >
  ...
  <_config:property name="allowDuplicateAdministrativeName" value="true" >
</_config:BusinessObjectMediator>
Configure the Data Load utility to use a custom XSLT script to convert your input file XML. If your input file is in a different XML format than the supported format, create an XSLT script for the utility to use to convert your input XML. Include the attribute xslt in the <_config:DataReader> element configuration and specify your XSLT script as the value for the attribute. For example, the following configuration, specifies that the utility must use the customPromotion.xsl XSLT script to convert the input file XML.
<_config:DataReader className="com.ibm.commerce.foundation.dataload.datareader.XmlReader" xslt="customPromotion.xsl" >
  <_config:XmlHandler className="com.ibm.commerce.foundation.dataload.xmlhandler.DOMXmlHandler" />
</_config:DataReader>
Save and close the configuration file.
Open the data load environment configuration file (wc-dataload-env.xml) for editing and update the configured settings to match the environment settings.
Open the data load order configuration file (wc-dataload.xml) for editing and configure the settings to load your promotion data.

In the <_config:DataLoadEnvironment> element, ensure that the value of the configFile attribute identifies the environment configuration file. If the file is not in the same directory as the data load order configuration file, include the relative path to the file.
In the <_config:LoadItem> element, ensure that the value for the name attribute is PromotionXml and that the value for the businessObjectConfigFile attribute identifies the business object configuration file. If the file is not in the same directory as the data load order configuration file, include the relative path to the file.
In the <_config:DataSourceLocation> element, ensure that the value of the location attribute identifies the input XML file that we are loading. If the file is not in the same directory as the data load order configuration file, include the relative path to the file.
Save and close the configuration file.

Run the Data Load utility.
Verify that the promotion data is loaded by reviewing the data load summary report. For more information about the location and contents of this summary report, see Verify that the Data Load utility loaded the promotion data successfully.
We can also verify that the promotion data is loaded by running the following SQL statements against the WebSphere Commerce database:
select * from PX_PROMOTION;
Ensure that the data within the sample input files exists within the appropriate database tables.
In Management Center, verify that we can view the newly loaded promotions or promotion changes in the Promotions tool.