Exporting Data
Before exporting data from Elastic Path, read the Concepts and Supported Object Types.
Before you begin
Ensure that you start ActiveMQ before performing the following steps. However, you can run database migration without ActiveMQ, by using the -Dspring.profiles.active=non-xa
Maven property. For example, to run reset without ActiveMQ, run the command mvn clean install - Preset-db -Dspring.profiles.active=non-xa
.
The basic steps to export data from an Elastic Path deployment are:
- Configure the environment settings.
- Configure the export options.
- Create a search query to export object or objects.
- Run the command line utility.
Configure the environment settings
Edit the importexporttool.config
file and configure the environment settings for the system from which you are exporting data.
For example, for a MySQL database named commercedb
on the local machine running on port 3306
, your settings should look similar to this:
db.connection.url=jdbc:mysql://localhost:3306/commercedb?AutoReconnect=true&useUnicode=true&characterEncoding=utf-8
db.connection.username=root
db.connection.password=root
db.connection.driver_class=com.mysql.jdbc.Driver
Configure the export options
The Import-Export tool reads export options from an export configuration file. This XML file specifies:
- What type of data to export
- How to package the exported data
- Where to store the exported data
The default export configuration file exportconfiguration.xml
is located in the Import-Export Tool’s installation directory. You can modify the settings in this file to meet your export requirements. Alternatively, you can make a copy of this file, change the settings in the copy, and specify the copy’s filename when you run the batch script.
The export configuration file contains three main types of XML elements:
- Exporter Configuration
- Packager Configuration
- Delivery Configuration
Exporter Configuration
The exporter
element specifies the type of object you want to export. See Supported Object Types for the list objects you can export.
To include optional dependencies, add include
elements to the exporter
element. For example, the following configuration exports products, including their associated assets and product merchandising associations (direct only):
<exporter type="PRODUCT">
<include type="PRODUCTASSOCIATION">
<option key="DIRECT_ONLY" value="true"/>
</include>
<include type="INVENTORY"/>
<include type="PRICING"/>
<include type="ASSETS"/>
</exporter>
The type of dependencies you can include depends on the type of object you are exporting. --For the list of supported include types, see the description of the include element in Appendix A - Export Configuration.--
Packager Configuration
The packager
element specifies how the exported data is packaged. The type attribute can be set to:
ZIP
- creates a zip archive of the exported dataNONE
- stores the data in a directory
The packagename
attribute specifies the name of the exported zip file. This attribute is only required if the type is set to ZIP
.
<packager type="ZIP" packagename="products.zip" />
Delivery Configuration
The target
element under the delivery
element specifies the directory where data is exported to.
<delivery>
<method>FILE</method>
<!-- Specify target directory in the file system:
"." - current directory, ".." - parent directory -->
<target>./</target>
</delivery>
Create a search query to export object or objects
The search configuration file contains the criteria that determines which data to export. The default search configuration file searchconfiguration.xml
is located in the Import-Export tool’s installation directory. This file contains an epql
query that defines the search criteria for fetching objects from the Elastic Path database.
You can change the query to meet your export requirements. Alternatively, you can make a copy of this file, change the settings in the copy, and specify the filename of the copy when you run the batch script.
The following is an example of a search configuration file containing a query that matches all products associated with the specified catalog:
<?xml version="1.0"?>
<searchconfiguration>
<epql>FIND Product WHERE CatalogCode='SNAPITUP'</epql>
</searchconfiguration>
For a complete description of the query language, see Search Query Language Reference.
tip
You can test product queries in the Commerce Manager’s Advanced Search tool. This will allow you to quickly locate and fix problems and fine tune queries before performing the actual export. (Currently, only product queries are supported in the Advanced Search tool.)
Run the command line utility
Exporting Data Using Maven
The Import-Export tool provides a maven profile, do-export
, to export data easily. Exporting using the maven command is preferable in a local development environment. The maven profile allows for debugging of the Import-Export tool using mvnDebug
and the creation of environment specific exportconfiguration.xml
and searchconfiguration.xml
files if needed. When using the maven profile, there is no need to specify database connection details.
To export data via maven, use the following command from the target directory:
mvn clean package -Pdo-export
Optionally, you can specify:
A directory to exported data into using the
data.location
system propertymvn package -Pdo-import -Ddata.location=./exported-data
Where
./exported-data
is the directory containing exported data. The directory can be specified as relative path (i.e., using./
or../
) to the target directory or as an absolute path.The search server URL using the
ep.search.default.url
system propertyIf not specified, then the default URL from the
COMMERCE/SYSTEM/SEARCH/searchHost
setting is used.mvn package -Pdo-import -Dep.search.default.url=SEARCH_HOST_URL
Exporting Data Using Batch Script
note
Before running the batch script, ensure that the Elastic Path database server and web applications are running.
To export data via the batch script, navigate to the directory you extracted the Import-Export tool distributable to and run the following command:
importexport.bat -e <search_config_file> [-c <export_config_file>] [-l <locale>]
<search_config_file>
is the path to the file that contains the search criteria<export_config_file>
is the path to the file that contains the export configurationThis parameter is optional. If it is not specified, the Import-Export tool will look for a file named
exportconfiguration.xml
in the Import-Export tool installation directory.<locale>
is the code of the locale for which you want to export dataThis only affects localized data. If no locale is specified, the corresponding data for all locales is exported
During the export operation, information and error messages are printed to the console. Errors are also logged in a file in the logs directory.
If you experience problems during export, see Troubleshooting.