Extracting promotion data with the Data Extract utility

You can configure and run the Data Extract utility from a command line utility to extract the promotion data for a store into an XML file. You can then use the Data Load utility to load the promotion XML file into stores in other environments, such as for testing the promotion in multiple test environments.

About this task

When you run the Data Extract utility to extract promotion data, the utility uses the PromotionToDomTransformMediator mediator to retrieve promotion data from the database and build a DOM object for the promotions. The DOM object is then passed to the data writer, which generates the output XML file that includes the extracted data. The generated promotion XML format is completely different from the promotion runtime XML. The generated promotion XML format is similar to the promotion authoring XML. The generated output XML differs from the authoring XML in that during the extraction process, the Data Extract utility replaces some primary key values (for example, for categories, catalog entries, customer segments) with the corresponding unique identifier value. The utility outputs the identifier value instead of the unique ID, since the unique ID can be different between environments. When you load the XML into a store with the Data Load utility, the utility resolves the unique ID for the promotions from the identifier value.

To use the Data Extract utility promotions, sample configuration files are provided for you to edit and use to quickly configure the utility. These files configure the utility to extract data for all promotions in the configured store.

WebSphere Commerce Enterprise WebSphere Commerce Professional Extracting promotion data from workspaces is not supported.

Procedure

Configure the Data Extract utility.
When you are configuring the utility copy and edit the sample configuration files for extracting marketing data. These files are in the following directory and subdirectories:
- WC_installdir/components/foundation/samples/DataExtract/Promotion
- WC_installdir\components\foundation\samples\DataExtract\Promotion
- WCDE_installdir\components\foundation\samples\DataExtract\Promotion
Optional: When you are configuring the utility, open the business object configuration file (wc-extract-xml-promotion.xml) for editing and configure the settings for extracting promotion data.
By default the Data Extract utility uses the PromotionToDomTransformMediator mediator to extract and output the following information for a promotion:
- The identifying and general properties for a promotion. These properties include the promotion name, start date, end date, priority, exclusivity, and more. The information is included within the <Base> XML element of the generated output file. If the promotion that is being extracted has a public promotion code, that code is included in this section of the output file. No information about any generated unique promotion codes is included.
  The configuration to extract this information is defined in the <_config:BusinessObjectMediator> element of the business object configuration file.
- The promotion description, which is included in the <Description> XML element in the generated output file. A separate <Description> element is included for each defined language for the promotion. The utility extracts this information from the PX_DESCRIPTION database table.
  The PromotionToDomTransformMediator mediator includes the configuration to extract this type of data. You cannot customize the data that returns in this group of information.
- The promotion target and purchase conditions, which are included in the <Elements> XML element in the generated output file. The utility extracts this information from the PX_ELEMENT and PX_ELEMENTNVP database tables. Each name-value pair for a promotion from the PX_ELEMENTNVP table is included as a separate XML element name and value. This name-value pair XML element is within the appropriate parent XML element from the extracted PX_ELEMENT data.
  The PromotionToDomTransformMediator mediator includes the configuration to extract this type of data. You cannot customize the data that returns in this group of information.
For the full list of properties that can be extracted for a promotion, see Promotions XML input file. The generated output file for an extracted promotion can include the same properties that as an input file for loading a promotion with the Data Load utility.
1. To extract more or custom data for a promotion, update the <_config:BusinessObjectMediator> element configuration.
  You can customize the SQL queries in the <_config:BusinessObjectMediator> element to add data to the <Base> XML element in the generated output file. Each <_config:Query> element in the business object mediator configuration includes an SQL statement to retrieve data. The query element also includes the column mappings for how the retrieved data is to be written to the generated XML file. The value for each column mapping is used as the name of the XML element that includes the value for that database column in the generated output file.
2. To extract data for only specific promotions, update the <_config:DataReader> element configuration.
  You can customize the SQL query in the data reader configuration to define which promotions that the utility extracts. By default, the sample business object configuration file is configured to extract data for all promotions with status 0 and 1 for the store that is configured in the environment configuration file.
3. Configure the formatting of the XML elements in the generated output XML file. You can configure the formatting of the generated file by including the following properties in the <_config:DataWriter> element configuration.
  
  rootElemenetName
  
  Specifies the name of the root XML element in the generated file. The value can be any name that you want.
  
  indent
  
  Indicates whether the XML in the generated file is to be formatted. You can set the following values for this parameter:
  
  true
  
  The XML in the generated file is formatted so that each XML element is on a separate line. This configuration can help improve the readability of the generated output file. The property indentAmount indicates how many spaces each element is indented from the parent element.
  
  false
  
  The default value. The XML in the generated file is two lines. The first line is the XML header and the second line is the serialized XML string of promotion data.
  
  indentAmount
  
  Indicates how many spaces each element is indented from the parent element.
  For example, the following code snippet includes all of these properties.
```
<_config:DataWriter className="com.ibm.commerce.foundation.dataload.datawriter.DomXmlWriter">
  <_config:property name="rootElemenetName" value="Promotions" />
  <_config:property name="indent" value="true" />
  <_config:property name="indentAmount" value="2" />
</_config:DataWriter>
```
4. Save and close the configuration file.
Run the Data Extract utility to extract the promotion data for the configured store.
1. Open a command line utility and go to the appropriate directory:
  - WC_installdir/bin
  - WC_installdir\bin
  - WCDE_installdir\bin
2. Enter the following command to run the sample data load order file and load the information that included in this sample:
  - ./dataextract.sh ../components/foundation/samples/DataExtract/Promotion/wc-dataextract.xml
  - dataextract.bat ..\components\foundation\samples\DataExtract\Promotion\wc-dataextract.xml
  - dataextract ..\components\foundation\samples\DataExtract\Promotion\wc-dataextract.xml
  When the utility completes the extraction process, the utility generates the XML output file in the data output location that you configured in the Data Extract order configuration file. By default, this file is named Promotion.xml
  You can configure the utility by including optional parameters in the command. For more information about the available parameters, see Data Extract utility
Verify that the output XML file generated successfully.
1. Go to the data output location and open the generated XML output file to review the file contents.
2. Compare the contents of the file with the promotion data in the source database tables to verify that the correct data is extracted.

What to do next

You can use the generated XML output file as an input file for loading promotions with the Data Load utility. For example, if business users create promotions in an authoring environment, you can extract the completed promotions and then load the promotions into one or more test environments to test the promotion. By extracting and loading these promotions, you do not need to re-create the promotions with Management Center in each test environment.

You can also edit the promotions in the output file and load the data back into the same store to update the store promotions. For more information about loading a promotion XML input file with the Data Load utility, see Loading promotions with the Data Load utility.