Loading promotions with the Data Load utility

You 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, you can quickly create or change multiple promotions in a single operation.

About this task

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: You cannot use the Data Load utility to set or change the state for a promotion.

If you are creating a promotion with the Data Load utility, the promotion is always inactive when the load process completes. For example, if you 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 you are changing a promotion with the Data Load utility, the current promotion state does not change. For example, if you 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. You need to deactivate and reactivate the promotion to enable the promotion updates on the storefront.

Procedure

Create your input XML file.
You 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.
- WC_installdir/samples/DataLoad/Promotion
- WC_installdir\samples\DataLoad\Promotion
- WCDE_installdir\samples\DataLoad\Promotion
If you are creating your input file manually, copy and edit the sample Promotion.xml file to help you create your input file.
Tip: You can use the Data Extract utility to help you generate your input file. If you 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 that is named <Base>. This information includes any data about the promotion codes for the promotions, such as the type of promotions codes for the promotion. You can specify a public promotion code or pattern for generating advanced unique promotion codes, but do not include any unique promotion codes. You 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:
- The promotion description information inside an XML element that is named <Description>. Include a separate <Description> for each defined language that your 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 that is 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 that is called <IncludePaymentTypeIdentifier>, which is nested inside a <Type> element that is 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 that is 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 you can include in your input file and the specific names for you to use for the elements, see Promotions XML input file.
If you want to load data to change data for a promotion, you must configure your input file to include the unique ID for the promotion. Include the ID as the value for an element that is 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 that is 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.
1. Go to the following directory, which contains the sample configuration files for loading promotion data:
  - WC_installdir/samples/DataLoad/Promotion
  - WC_installdir\samples\DataLoad\Promotion
  - WCDE_installdir\samples\DataLoad\Promotion
2. 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.
1. 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. You 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>
2. 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>
```
3. 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 your environment settings.
Open the data load order configuration file (wc-dataload.xml) for editing and configure the settings to load your promotion data.
1. 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.
2. 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.
3. In the <_config:DataSourceLocation> element, ensure that the value of the location attribute identifies the input XML file that you 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.
4. 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.
- You can also verify that the promotion data is loaded by running the following SQL statements against your 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 you can view the newly loaded promotions or promotion changes in the Promotions tool.