Importing Data

Before importing 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 import data from an exported XML package are:

1. Configure the environment settings.
2. Configure the import options.
3. 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 to FILE

• The source element must contain the path to the package

  If the Packager Configuration (Import) element’s type is ZIP, the source must specify a zip file. If type is NONE, 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.