Importing Data
Before importing 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 import data from an exported XML package are:
- Configure the environment settings.
- Configure the import options.
- Run the command line utility.
To import data from an Elastic Path deployment, you must create an XML file containing the import configuration. Then, you launch the Import-Export batch script.
If you are importing data into an Elastic Path instance where Change Sets are enabled, it’s important to note that the Import-Export tool can modify objects that are not in Change Sets. Adding objects to a Change Set during import is optional. For information on importing objects into a Change Set, see Running the Batch Script to Import Data.
Configure the environment settings
Edit the importexporttool.config
file and configure the environment settings for the system to which you are importing data. For more information, see Configuring Environment Settings for Data Export.
Configure the import options
The Import-Export tool reads import options from an import configuration file. This XML file specifies:
- What type of data to import
- How the target system should resolve import conflicts
- Where the import data package is located
The default import configuration file importconfiguration.xml
is located in the Import-Export Tool’s installation directory. You can change the settings in this file to meet your import 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 an import configuration file:
<?xml version="1.0"?>
<importconfiguration>
<xmlvalidation>true</xmlvalidation>
<importstrategy>
...
<importer type="PRODUCT">
<importstrategy>INSERT_OR_UPDATE</importstrategy>
<dependentelements>
<!-- FOR SINGLE AND MULTI-SKU PRODUCTS -->
<dependentelement type="PRODUCT_ASSOCIATIONS">CLEAR_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_CATEGORY_ASSIGNMENTS">CLEAR_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_ATTRIBUTES">CLEAR_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_CATALOG_PRICES">RETAIN_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_PRICE_CURRENCIES">RETAIN_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_PRICE_TIERS">CLEAR_COLLECTION</dependentelement>
<!-- FOR MULTI-SKU PRODUCTS ONLY. NOT TO BE EDITED WHEN IMPORTING SINGLE SKU PRODUCTS -->
<dependentelement type="SKU_CATALOG_PRICES">RETAIN_COLLECTION</dependentelement>
<dependentelement type="SKU_PRICE_CURRENCIES">RETAIN_COLLECTION</dependentelement>
<dependentelement type="SKU_PRICE_TIERS">CLEAR_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_SKUS">RETAIN_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_SKU_PRICING">CLEAR_COLLECTION</dependentelement>
<dependentelement type="SKU_ATTRIBUTES">CLEAR_COLLECTION</dependentelement>
</dependentelements>
</importer>
...
</importstrategy>
<packager type="ZIP" />
<retrieval>
<method>FILE</method>
<source>c:/temp/importexport/export.zip</source>
</retrieval>
<transformerschain/>
</importconfiguration>
The import configuration file contains four sections:
- XML Validation Configuration
- Import Strategy Configuration
- Packager Configuration (Import)
- Retrieval Configuration
XML Validation Configuration
The xmlvalidation
element sets the Import-Export Tool to validate XML files before importing them. The value must be either true
or false
.
<xmlvalidation>true</xmlvalidation>
Import Strategy Configuration
<importstrategy>
The importstrategy
element contains one or more importer
elements and one or more dependentelements
.
...
<importer type="PRODUCT">
<importstrategy>INSERT_OR_UPDATE</importstrategy>
<dependentelements>
<!-- FOR SINGLE AND MULTI-SKU PRODUCTS -->
<dependentelement type="PRODUCT_ASSOCIATIONS">CLEAR_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_CATEGORY_ASSIGNMENTS">CLEAR_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_ATTRIBUTES">CLEAR_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_CATALOG_PRICES">RETAIN_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_PRICE_CURRENCIES">RETAIN_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_PRICE_TIERS">CLEAR_COLLECTION</dependentelement>
<!-- FOR MULTI-SKU PRODUCTS ONLY. NOT TO BE EDITED WHEN IMPORTING SINGLE SKU PRODUCTS -->
<dependentelement type="SKU_CATALOG_PRICES">RETAIN_COLLECTION</dependentelement>
<dependentelement type="SKU_PRICE_CURRENCIES">RETAIN_COLLECTION</dependentelement>
<dependentelement type="SKU_PRICE_TIERS">CLEAR_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_SKUS">RETAIN_COLLECTION</dependentelement>
<dependentelement type="PRODUCT_SKU_PRICING">CLEAR_COLLECTION</dependentelement>
<dependentelement type="SKU_ATTRIBUTES">CLEAR_COLLECTION</dependentelement>
</dependentelements>
</importer>
...
Each importer
element contains information about what data to import. The type
attribute specifies the type of object to import. Supported type
attributes are:
CUSTOMERPROFILE_ATTRIBUTE
CMUSER
USER_ROLE
CUSTOMER
PROMOTION
COUPONSET
SYSTEMCONFIGURATION
PRICELISTDESCRIPTOR
GIFT_CERTIFICATE
SHIPPING_SERVICE_LEVEL
SHIPPING_REGION
SAVED_CONDITION
CM_IMPORT_JOB
CUSTOMER_CONSENT
DATA_POLICY
The importstrategy
element within the importer
element specifies how to handle conflicts during the import. The following values are supported:
INSERT
Only new objects are imported. If an object with the same identifier exists in the target system, the object is not imported.
UPDATE
Only updated objects are imported. If an imported object does not exist in the target system, the object is not imported.
INSERT_OR_UPDATE
Both new and updated objects are imported. If no import strategy is specified, the default is
INSERT_OR_UPDATE
<dependentelements>
The optional dependentelements
element lets you configure conflict resolution for dependencies. The dependentelements
element can contain one or more dependentelement
elements. The dependentelement
element’s type attribute specifies the type of dependency. Supported type
attributes are:
PRODUCT_CATEGORY_ASSIGNMENTS
PRODUCT_ATTRIBUTES
PRODUCT_SKUS
SKU_ATTRIBUTES
PRODUCT_SKU_PRICING
PRODUCT_CATALOG_PRICES
PRODUCT_PRICE_CURRENCIES
PRODUCT_PRICE_TIERS
SKU_CATALOG_PRICES
SKU_PRICE_CURRENCIES
SKU_PRICE_TIERS
SETTING_VALUES
SETTING_METADATA
BASE_AMOUNTS
Each dependentelement
contains either CLEAR_COLLECTION
or RETAIN_COLLECTION
, to indicate how dependencies of the specified type are handled in the event of a conflict during import.
note
The Retain collection option is not available for Product Bundles. Product Bundles must use Clear collection to ensure that the ordering of bundle constituents is maintained.
Packager Configuration (Import)
The packager
element specifies how the data being imported is packaged. The type attribute must be set to either ZIP
or NONE
. If the type is ZIP
, the Retrieval Configuration must specify a zip file. If the type is NONE
, the retrieval method must specify a directory.
<packager type="ZIP" />
Retrieval Configuration
The retrieval
element specifies how to retrieve the import data.
The
method
element must always be set toFILE
The
source
element must contain the path to the packageIf the Packager Configuration (Import) element’s
type
isZIP
, the source must specify a zip file. Iftype
isNONE
,source
must specify a directory
<retrieval>
<method>FILE</method>
<source>c:/temp/importexport/export.zip</source>
</retrieval>
note
Use the forward slash as the path separator inside the source element.
Run the command line utility
Importing Data Using Maven
The Import-Export tool provides a maven profile, do-import
, to import data easily.
Importing 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 importconfiguration.xml
files if needed. When using the maven profile, there is no need to specify database connection details.
To import data via maven, use the following command from the target directory:
mvn package -Pdo-import
Optionally, you can specify the directory to retrieve the exported data from 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 ./../
) to the target directory or as an absolute path.
Importing Data Using Batch Script
To import data via the batch script, navigate to the directory you extracted the Import-Export tool distributable to and run the following command:
note
Before running the batch script, make sure the Elastic Path database server and web applications are running.
importexport.bat -i -c <import_config_file> [-g <change_set_guid> [-s {stage1|stage2}]]
<import_config_file>
is the path to the file that contains the import configuration<change_set_guid>
is the GUID of the Change Set into which you want to import the data
During the import 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 import, see Troubleshooting.
Importing Data into a Change Set
You can import data directly into a Change Set. To do this, you must include the -g
command line option and specify the GUID of the target Change Set.
Importing data into a Change Set is a two-stage process. In the first stage, the target system verifies that the data can be imported into the Change Set. (It verifies that a Change Set with the specified GUID exists, that it is in the open state, and that the objects you are importing are not already in another Change Set.) If all requirements are met, the objects are added to the Change Set.
In the second stage, the data is imported into system.
You can include the -s
option if you want to control execution of the import. The -s
option has two possible values:
stage1
Only adds the objects to the list of objects in the Change Set without actually importing them. This option is useful if you want to prevent objects from being added to other Change Sets while you continue to make changes.
stage2
Only imports the data. This may only be used if the objects have already been added to the Change Set, either using the
stage1
option or through the Commerce Manager
If you do not specify the -s
option, both stage 1 and stage 2 are performed.
note
If an object was only added to the Change Set (only stage 1 was executed), it will appear in the list of objects when viewing the Change Set in the Commerce Manager. However, if you try to launch the editor for that object, it will not open because the object does not exist in the system. The stage 2 must be executed in order to import the object into the target system.