Documentation

The documentation below is just a sample of the documentation included with eCommerce Import.  Much more documentation including XML examples is included with the add-on.

eCommerce Import Help

Use the eCommerce Import add-on to import customers, products, order and other data into your Concrete5 web site. This panel explains how to use the import functionality.

Additional detailed information is available for each import object type. Select the object type you want to import and click the 'Begin Import' button above. Detailed help and example XML files are shown at the bottom of the page.

Import

To begin importing select the type of object you want to import and then click the 'Begin Import' button. The eCommerce Import add-on can import the following object types:

  • Customer - import users with pre-filled in billing and shipping address information. Customers can be added to a predefined Concrete5 use group.
  • Order - import entire orders. This may be useful when migrating data from a legacy site. Please note: any products that are part of imported order must already exist or an error will occur and will not be included in the order.
  • Page - import pages with a title, meta keywords, meta description, and optional content.
  • Product - import products complete with all standard attributes, custom attributes, options, and images. Optionally create custom product pages for each product.
  • User - similar to importing customers but only imports username, password and email. Useful for setting up site administrators.

Import Options

Image Directory Path

When you import products you will typically want to import a photograph or image for each product. The eCommerce Import add-on will pull images from a given directory. Follow these steps to set up the images in preparation for your product import:

  1. Choose a location on your web server to upload the images to (e.g. files/import_images). This can either be a path relative to your Concrete5 directory or an absolute path. You may need to create this directory.
  2. Upload your images to the location chosen in the previous step. You can use FTP or a similar tool to do this.
  3. Make sure the file names of your images match the file names specified in your import XML file.
  4. Set the 'Image Directory Path' value to directory in the first step.

Page Content Directory Path

As with product imports and product images, when you import pages you will typically have some basic content you will want to include with each page. Place the content for each page in its own file then upload the content files into a directory. Use the 'Page Content Directory Path' to tell the eCommerce Import add-on where to find these files. Follow these steps to set up the content files:

  1. Choose a location on your web server to upload the content files (e.g. files/import_content). This can either be a path relative to your Concrete5 directory or an absolute path. You may need to create this directory.
  2. Upload your content files to the location chosen in the previous step. You can use FTP or a similar tool to do this.
  3. Make sure the file names of your content files match the file names specified in your import XML file.
  4. Set the 'Page Content Directory Path' value to directory in the first step.

Notes

XML File Format

XML is a very flexible way for describing data, but some characters have a special meaning in XML. Watch out for the following characters in your XML files (especially in product names and descriptions):

Name -- Character -- HTML Entity/Notes
Ampersand -- & -- &
Greater Than -- > -- >
Less Than -- < -- &lt;
Apostrophe -- ' -- &apos;
Quote -- " -- &quot;
Other non-ASCII characters (see notes)

XML only supports the above named entities. All other entities must be encoded numerically. For example, to include the British pound character in your XML you would use the entity &#163;

Another way to prevent problems with the XML parser to enclose your text in a CDATA section. Data in a CDATA will not be parsed by the XML parser. A CDATA section starts with "<![CDATA[" and ends with "]]>". For example:

<product>
<name>Some Product</name>
<description><![CDATA[It's okay to have apostrophes and other special characters.]]></description>
:
</product>

Product Import

Import products by following these steps:

  1. Create an XML file with the import data. Select 'Example XML' above to see an example.
  2. Select a parent page and a custom page type for products you will be importing. All of the products imported in one batch must use the same page type and will have a page created under the same parent. If you don't specify a custom page type, a default product detail page will be created. You can avoid creating a product page altogether by not choosing a parent page and leaving the custom product page type set to none.
  3. Choose whether or not to include the product page in navigation. This is the same as setting the 'Exclude from Nav' attribute in the page properties.
  4. Choose whether or not to create new product select options if the import data contains new values not already defined. If this option is not selected options for which there are no matching values will be ignored.
  5. Click the 'Import Products' button.

Products may be safely imported even if the product already exists in the database. When products are imported the eCommerce Import add-on checks to see if a product with a matching name or other attribute value already exists. If the product exists, only the attributes specified in the import file are used to overwrite the existing settings. You can for example update the descriptions of products by importing an XML file with only the names and descriptions of the products you want to change. The only exceptions to this are custom pages types and product options. If you specify a custom product page type the old product page will be deleted and a new one created. See the 'Options' help for information about updating a product with product options.

By default eCommerce Import uses the product name to uniquely identify products. You can use another text attribute as the unique identifier by selecting that attribute in the 'Attribute Used to Uniquely Identify Products' drop down. All of of the products being imported must have a value for this attribute defined in the XML or the import for those products that don't will fail.

Select either 'Attributes' or 'Options' from the dropdown above for more information about product attributes and options.

 

FAQ

Q: How do I convert a CSV file to the XML format used by eCommerce Import
A: eCommerce Import offers two ways to convert CSV files to XML:

  1. A simple script is included in the package that will convert your CSV file into XML.  The script is found in 'scripts' subdirectory within the Import add-on package directory.  You must run this script from the command line in order to use it.  Please review the documentation at the top of the file for details.
  2. You may use a more advanced version of the csv2xml script that is installed at http://www.toddcrowe.com/csv2xml to map CSV files to XML format.

Q: Is it possible to use eCommerce Import to import data in formats other than XML or to pull the data directly from a database?
A: The code that creates and updates products (and other objects supported by Import) is written as a concrete5 helper class.  If you have PHP programming skills you can write your own script to read the data, convert it to a PHP array, and then have Import manage the complicated product creation and updating part of the work.

Q: How do I use eCommerce Import to import pages and users if I don't have the eCommerce add-on?
A: The eCommerce portions of Import may be disabled by adding the following line to your site.php file:

define('CORE_COMMERCE_IMPORT_CC_CORE', false);