Exporting Data

Before exporting data from Elastic Path, read the Concepts and Supported Object Types.

Before you begin

Ensure that ActiveMQ is running.

note

In a development environment, you can run a database migration without ActiveMQ. You can use the mvn clean install -Dspring.profiles.active=non-x parameter with the Maven build.

The basic steps to export data from an Elastic Path deployment are:

1. Configure the environment settings.
2. Configure the export options.
3. Create a search query to export object or objects.
4. 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 data
• NONE - 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 property

  mvn 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 property

  If 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 configuration

  This 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 data

  This 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.