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.
Note: 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 promotion data. These files are in the following directory and subdirectories:
- WCDE_installdir\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 as an input file for loading a promotion with the Data Load
utility.
-
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.
-
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.
-
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>
-
Save and close the configuration file.
-
Run the Data Extract utility to extract the promotion data for the configured
store.
-
Verify that the Promotion.xml output XML file generated
successfully.
-
Go to the data output location and open the generated XML output file to review the file
contents.
-
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 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 for testing the
promotion data. 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.