You are here:
Catalog Object Import/Export in B2C Commerce
Import an entire catalog at once; the import operation includes the catalog and any categories and products within the catalog. Export works similarly; you export the entire catalog at once. This topic applies to B2C Commerce.
Catalog import/export is designed so that:
- You can import a storefront catalog independently of the product catalog.
- A storefront catalog category can reference the products to appear in that category.
- Imports of other storefront catalogs don't affect the already established product/category assignments.
- Product update imports of the product catalog don't affect the assignments into the storefront catalogs.
- The catalog import semantic is adjusted so that product and storefront catalogs are self-contained data units, isolated from each other, allowing you to import them without deleting each other's data structures.
Business Manager Import/Export Location
Select
Catalog Import
Import a catalog from a CSV or XML file type. You can only upload a CSV file in MERGE mode and Specify which catalog you're uploading before continuing the import process. Importing catalog data into development and production environments results in errors if the same catalog exists in staging. We recommend replicating catalog data from staging.
The catalog import is implemented as a two-pass import.
- In the first pass, objects are created, updated, and deleted.
- In the second pass, relationships between objects are established.
The import process allows the category and product elements to appear in any order in the feed. During import, you don’t have exposure to the two passes. The default transaction mode commits changes after each object import. If the import is aborted between the first and second pass, the created or updated object can be left behind. In this situation, relationships aren’t created for the object. To eliminate leaving objects behind, include all entities corresponding to a catalog in a single XML file.
New products imported in MERGE and REPLACE modes default to offline status if this status isn't specified in the import file.
- For existing products imported in UPDATE, MERGE, and REPLACE modes, the online/offline status doesn't change unless the status is specified in the import file.
- For import files that specify the online/offline status for every product, this change has no effect on the existing behavior of the catalog import.
The import schema catalog.xsd requires that a <value-definition>
element must declare a child <value> element. The specified value must be nonempty
and it must not contain leading or trailing whitespace.
Catalog Export
Export data on selected products from Business Manager or through a custom pipeline. During catalog export, B2C Commerce automatically trims leading and trailing whitespace and removes any previously saved newline characters in a product image path. Export a catalog as an XML or a CSV.
Business Manager catalog export mode Export Specific Products only
contains the list of selected products and the category assignments for those products.
Select . You can
use the standard product search functionality or the beta search functionality as
described in Simple Products
Search.
Page Meta Tags Import/Export
Page meta tag rules and definitions are now imported and exported within a separate 'Page Meta Tags' section. See Page Meta Tags.
Only assignments are imported and exported within Catalog, Library, and Site ImPex.
Pipelets
ImportCatalog
Imports the catalog data specified by ImportFile into the system in the specified mode. This pipelet has an import configuration that lets you delete the catalog before import. Use this technique as a high-performance way to empty a catalog, specifically if the objects in the catalog are unknown. Also delete custom attributes before import when using the UPDATE or MERGE mode. For more information, see Removing Outdated Objects.
You can only import custom product attribute definitions using the pipelet
ImportCatalog. It isn't possible to import product object custom attribute definitions
using Business Manager catalog import. To enable the import of custom product attribute
definitions, set the ImportCatalog pipelet
ImportConfiguration parameter to ImportAttributeDefinitions = true. If
this parameter isn't provided in the ImportConfiguration or if it's set to
false, product attribute definitions aren’t imported.
If you provide product attribute definitions in the catalog import file, but the
ImportAttributeDefinitions = false or not provided or the file is
imported in Business Manager, then a data error is logged. In this case, the
product-attribute-definitions element is ignored during import for the UPDATE, MERGE,
and REPLACE import modes.
ExportCatalog
When the ExportCatalog
pipelet parameter ExportCategoryAssignments=True, and you specify a
Products iterator, the export file contains only the category assignments for the
list of exported products or categories assignments. When
the Products iterator isn't specified, all category assignments are
exported.
Granularity: passed categories, products of passed categories, category assignments of passed categories, all recommendations in catalog, all shared product options in catalog).
Schema Elements
This section describes the elements in the catalog.xsd and considerations when creating values for them.
Element: Category
Consider some element-specific details when importing a category element.
- Category elements can appear in any order in the feed.
- Specify DELETE mode at the category element level, overwriting the import process mode, for example, <category category-id="Electronics" mode="delete"/>.
- A catalog's root category isn't deleted with DELETE mode. Nor is it deleted with the REPLACE mode. However, it’s updated with the REPLACE mode.
- Deleting a category deletes the category's category assignments (not the products within the category), category links (incoming and outgoing), and all subcategories.
- The root category's display name and description is also set as the catalog's display name and description.
- Some category subelements have a special semantic or set of defaults, if not provided in the feed. The following table provides details.
Attributes: online-from and online-to
Some situations require that the online-from and online-to category
attributes values be reset during a catalog import process. For example, XML validation
fails if you submit these elements in XML with an empty value (for example,
<online-from/>). Reset the online-from and
online-to category attributes during a catalog import process.
To reset these attributes values during a catalog import process, the import file must conform to the following XML format example:
<category category-id="RESET_ME">
<!-- reset default online-from value -->
<online-from xsi:nil="true" />
<!-- reset default online-to value -->
<online-to xsi:nil="true" /> </category>Add the following to your catalog import file:
xsi:noNamespaceSchemaLocation="catalog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"For example:
<catalog xmlns="http://www.demandware.com/xml/impex/catalog/2006-10-31"
xsi:noNamespaceSchemaLocation="catalog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" catalog-id="catalog">
When using UPDATE Mode:
Understanding the behavior of UPDATE mode is important for customers who can produce catalog delta files to update their catalogs.
- If you import a category that is the target of a category link without the category that is the link's source, the link isn't removed.
- If you import a category with child categories without its children, the children aren’t removed.
| Subelement | Comments |
|---|---|
| display-name | If element omitted: attribute not altered |
| description | If element omitted: attribute not altered |
| online-flag | If element omitted during create: defaults to false If element omitted during update: attribute not altered |
| parent | If element omitted: DATAWARNING in log, defaults to "root" |
| position | If element omitted: attribute not altered |
| thumbnail | If element omitted: attribute not altered |
| image | If element omitted: attribute not altered |
| template | If element omitted: attribute not altered |
| sitemap-included-flag | If element omitted: attribute not altered |
| sitemap-changefrequency | If element omitted: attribute not altered |
| sitemap-priority | If element omitted: attribute not altered |
| page-attributes | If element omitted: attributes not altered Element provided: MERGE semantic for each attribute and locale |
| custom-attributes | If element omitted: attributes not altered Element provided: MERGE semantic for each attribute and locale |
| category-links | If element omitted: category links not altered Element provided: REPLACE semantic on outgoing category links Order of appearance of category-link elements defines sort order |
| attribute-groups | If element omitted: groups not altered Element provided: REPLACE semantic Order of appearance of attribute-groups defines sort order Order of appearance of attributes defines sort order |
| refinement-definitions | If element omitted: refinements not altered Element provided: REPLACE semantic Order of appearance of refinement-definition elements defines sort order |
Element: Product
Consider some element-specific details when importing the product element.
- Product elements can appear in any order in the feed.
- Specify DELETE mode at the product element level, overwriting the import process mode, for example: <product product-id="PN00001" mode="delete"/>.
- The following product types are mutually exclusive: bundle, product set, and base product. Therefore, the following elements are mutually exclusive: bundled-products, product-set-products, and variations.
- You can't specify variations of the following product types: bundle, product set, or base product.
- Exactly one base product owns each product variation and variation group. Change this ownership from one base product to another in a single import process.
- If you import a variation product without its base product, the product remains a variation.
- If you import a base product without its variation products, the products specified in the <variation product> section remain related to the base product. Other variation products unlink from the base product and become normal products.
- If you import a product set without its parent product-set, it remains a member of the set.
- If you import a bundled product without its bundle, it remains a member of the bundle.
- If you import a product that is the target of a product link without the link's source product, the link isn't removed.
- Deleting a bundle doesn't delete the bundled products.
- Deleting a base product also deletes the variation products.
Resetting product Attributes
In some cases, you might want to remove values for product attributes during import in merge mode.
Reset the following attributes during catalog import:
- online-from
- online-to
- search-rank
- search-placement
- sitemap-included-flag
- sitemap-changefrequency
- sitemap-priority
XML format example:
<product product-id="RESET_ME">
<!-- reset default online-from value -->
<online-to xsi:nil="true" />
<!-- reset default search-placement value -->
<search-placement xsi:nil="true" />
<!-- reset site-specific search-placement value -->
<search-placement site-id="YourSite" xsi:nil="true" />
</product>
Add the following:
xsi:noNamespaceSchemaLocation="catalog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
to the root element of your import file, so that it looks like the following:
<catalog xmlns="http://www.demandware.com/xml/impex/catalog/2006-10-31" xsi:noNamespaceSchemaLocation="catalog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" catalog-id="catalog">
Special processing for Subelements
Some product subelements have a special semantic or set of defaults, if not provided in the feed. The following table provides details.
| Subelement | Comments |
|---|---|
| ean | If element omitted: attribute not altered |
| upc | If element omitted: attribute not altered |
| unit | If element omitted during create: defaults to empty string If element omitted during update: attribute not altered |
| min-order-quantity | If element omitted during create: defaults to 1 If element omitted during update: attribute not altered |
| step-quantity | If element omitted during create: defaults to 1 If element omitted during update: attribute not altered |
| display-name | If element omitted: attribute not altered |
| short-description | If element omitted: attribute not altered |
| long-description | If element omitted: attribute not altered |
| online-flag | If element omitted during create: defaults to true If element omitted during update: attribute not altered |
| online-from | If element omitted: attribute not altered |
| online-to | If element omitted: attribute not altered |
| available-flag | If element omitted during create: defaults to true If element omitted during update: attribute not altered |
| searchable-flag | If element omitted during create: defaults to true If element omitted during update: attribute not altered |
| image | If element omitted: attribute not altered |
| thumbnail | If element omitted: attribute not altered |
| template | If element omitted: attribute not altered |
| tax-class-id | If element omitted: attribute not altered |
| brand | If element omitted: attribute not altered |
| manufacturer-name | If element omitted: attribute not altered |
| manufacturer-sku | If element omitted: attribute not altered |
| search-placement | If element omitted: attribute not altered |
| search-rank | If element omitted: attribute not altered |
| sitemap-included-flag | If element omitted: attribute not altered |
| sitemap-changefrequency | If element omitted: attribute not altered |
| sitemap-priority | If element omitted: attribute not altered |
| page-attributes | If element omitted: attributes not altered Element provided: MERGE semantic for each attribute and locale |
| custom-attributes | If element omitted: attributes not altered Element provided: MERGE semantic for each attribute and locale The values for the custom attribute don't merge. Merge creates the object if it doesn't exist and then modifies an existing object. Object attributes not provided in the feed are left untouched. When a custom-attribute value is in the XML file, the product gains that value but the other values that were selected before are no longer selected. The Import merge mode imports the attributes and not the value itself. For some values (for example, variation attribute values) a specific merge-mode is available; but not for the custom attributes to which you’re referencing. |
| bundled-products | If element omitted: relationships not altered Element provided: REPLACE semantic Order of appearance of bundled-product elements defines sort order. |
| product-set-products | If element omitted: relationships not altered Element provided: REPLACE semantic Order of appearance of product-set-product elements defines sort order |
| options | If element omitted: options not altered Element provided: REPLACE semantic on all private and shared options (delete/create private options, unbind/bind shared options) Order of appearance of option and shared-option elements defines sort order |
| variations | Element variations omitted: attributes and relationships not altered Element attributes omitted: attributes not altered Order of appearance of attribute elements defines sort order Element variants omitted: relationships not altered merge-mode attribute determines whether variations are added, removed, or replaced, regardless of MERGE semantic. if merge-mode attribute isn't provided, the importer uses the REPLACE semantic by default. This behavior is the legacy behavior for the element. |
| product-links | If element omitted: product links not altered Element provided: REPLACE semantic on outgoing product links Order of appearance of product-link elements defines sort order |
| classification-category | If element omitted: relationship not altered |
Site-Specific Attributes
The <product> import/export elements
<online-flag>, <online-from>,
<online-to>, <searchable-flag>,
<search-rank>, <search-placement>,
<sitemap-included-flag>,
<sitemap-priority>,
<sitemap-changefrequency>, and
<custom-attribute> elements support an optional site-id
that indicates the attribute value is site-specific. To specify a site-specific value, use a human-readable site
ID. For example:
<online-flag site-id="MySiteEurope">false</online-flag>Element: Images
Catalog import supports a merge-mode attribute for the <images>
section. This attribute has two possible values:
-
merge: the default. -
replace: use if you intend to erase all stored image information for a product and then reimport. Use this value, for example, if you changed the variation attributes that a base product uses to vary its images by.
merge-mode attribute is supported, it
only makes sense to use it when the overall import mode is UPDATE or MERGE.Element: Category-Assignment
The system preserves product-category assignments as part of catalog.xsd during import, allowing you to import categories with predefined product assignments in one step. This behavior is especially helpful in the case where you use a single (classification) catalog in conjunction with multiple, site-specific (navigation) catalogs.
The variation-configuration element and the
complex type VariationConfiguration allow the configuration of slicing
for variation products at the category level.
When you assign product position values for a category in Business Manager, each
product’s position value appears as a sequential number. When products are
imported/exported, their position element of
category-assignment is assigned a value of auto. To
resolve the common value and determine product position, the order in which it appears in the file determines each product’s actual position.
For example, Business Manager assigns Product A position 1 and Product B position 2 for a category. During import, the value of the
position elements for both products is set to auto.
Because Product A is first in the file, Product A appears first and Product B appears
second.
Element: Product-Attribute-Definitions
The product-attribute-definitions element is intended to support attribute definitions
for the product object via a feed from a third-party or backend system. It isn't
intended to allow the general import of attribute meta data via import. Product
attribute definition metadata isn't supported for export. If the
product-attribute-definitions element includes definitions for
system attributes, the import file is invalid.
You can only import attribute definitions via the ImportCatalog pipelet and can't import them via Business Manager import. Product attributes created by catalog import have the following default values:
- order-required is set to
false - searchable is set to
false - externally-defined is set to
true
If the product-attribute-definitions element isn't defined in the
import file, the import doesn't modify any existing product attribute definitions.
The import processes the element identically for the MERGE, REPLACE, and UPDATE modes. If you define the
product-attribute-definitions element in the import file,
the import checks whether the attribute definition already exists in the database and
does the following:
- New attribute definitions are added and the externally-defined flag is set to
truein the B2C Commerce database. - Existing attribute definitions that have the externally-defined flag set to true in the B2C Commerce database are updated, but not replaced.
- Existing attribute definitions that have the externally-defined flag set to
falsein the B2C Commerce database are ignored during import and the system logs a data error. - The import skips invalid attribute definitions. If there’s an existing
attribute with the same ID and the
externally-defined-flagset to true, the import removes it. The import also removes any configured values for the attribute from the B2C Commerce database. - If an attribute definition has the externally-defined flag set to true in the B2C
Commerce database, and if the attribute isn’t present in the import feed, the
attribute is removed. The import also removes any configured values for the attribute
from the B2C Commerce database.
B2C Commerce removes any externally defined attributes not present in the import feed because backend systems are often unable to provide information about obsolete information. The automatic removal of obsolete attributes prevents the accumulation of large numbers of obsolete attributes in the database.
For the import mode DELETE, the import ignores any product-attribute-definitions elements
defined in the import file.
Complex Type: AttributeDefinition
The catalog.xsd complex type AttributeDefinition supports the
site-specific-flag attribute.
Attribute: System
Site-specific values for system attributes are supported via catalog import and export.
Attribute: Custom
Site-specific values for custom attributes are supported via catalog import and export.
<online-flag site-id="MySiteAmerica">false</online-flag>Element: Variants
Attribute: Merge-Mode
The merge-mode attribute overrides the specified MERGE semantic for
specific variants element in UPDATE, MERGE, and REPLACE modes. The
attribute has these possible values: add, merge, replace, and
remove.
It’s unnecessary to use the attribute in REPLACE mode, because that mode automatically removes all variation products before replacing them with the variation products listed in the feed.
To add and remove variations separately, place them in separate variants elements. Only use one variants
element and mode per variations element and product.
Example 1: add two new variations
<product product-id="28447">
...
<variations>
<variants merge-mode="add">
<variation product-id="883239585285"/>
<variation product-id="883239585289"/>
</variants>
</variations>
</product>Example 2: remove three variations
<product product-id="28447">
...
<variations>
<variants merge-mode="remove">
<variation product-id="883239585281"/>
<variation product-id="883239585282"/>
<variation product-id="883239585283"/>
</variants>
</variations>
</product>Example 3: replace the attribute values for the third variation
<product product-id="28447">
...
<variations>
<variants merge-mode="replace">
<variation product-id="883239585287"/>
</variants>
</variations>
</product>Sorting of variation products and variation attribute values on Import
Control the sorting of variation products and variation attribute values during catalog import. This capability is useful if you must preserve the sort order of existing variation products and variation attribute values when importing.
If you specify merge for the merge-mode attribute of
the variation-attribute-values and variants elements,
the importer:
- Adds all new values specified in the import file to the end of the list, in the same order as specified in the import file.
- Updates all existing values specified in the import file. This behavior means
that the importer updates all attributes of the value, such as display name, if specified
in the import file. The position of the existing values isn’t updated. The importer removes all
existing values not specified in the import file.Note Variation products aren’t removed, but are unlinked from the base product and become standalone products.
If the merge-mode attribute isn't specified in the file, the
importer completely replaces the list stored in the system with the values in the import
file. The import uses the default replace semantic for lists of
elements.
Import/Export for Recommendations in B2C Commerce
Recommendations are imported as part of the catalog that owns them. A recommendation is represented as a top-level element of the catalog schema. The recommendation element is a sibling of the <product>, <category> and <category-assignment> elements. This topic applies to B2C Commerce.
Schema File (Catalog.xsd)
The following snippet is from the catalog schema:
<!-- Recommendation -->
<xsd:complexType name="complexType.Recommendation" mixed="false">
<xsd:sequence>
<xsd:element name="display-name" type="sharedType.LocalizedString" minOccurs="0" maxOccurs="unbounded" />
<xsd:element name="short-description" type="sharedType.LocalizedString" minOccurs="0" maxOccurs="unbounded" />
<xsd:element name="long-description" type="sharedType.LocalizedString" minOccurs="0" maxOccurs="unbounded" />
<xsd:element name="callout-message" type="sharedType.LocalizedString" minOccurs="0" maxOccurs="unbounded" />
<xsd:element name="image" type="simpleType.Generic.String.256" minOccurs="0" maxOccurs="1" />
<xsd:element name="custom-attributes" type="sharedType.CustomAttributes" minOccurs="0" maxOccurs="1" />
</xsd:sequence>Example
The following is the part of the catalog schema file that handles RecommendationTypes:
<xsd:simpleType name="simpleType.RecommendationType">
<xsd:annotation>
<xsd:documentation>Allowed string values are the 'int' values defined for the Recommendation.recommendationType attribute, and additionally the values 'cross-sell', 'up-sell', and 'other' for backward compatibility.</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="simpleType.Generic.String" />
</xsd:simpleType>With RecommendationTypes, the import process expects a positive integer value to be passed in this field. Alternatively, the import process accepts the legacy values cross-sell, up-sell or other, which are internally converted to one, two, or three respectively. If anything else is passed, the import process reports an error and doesn't import the recommendation. The import process doesn't validate the passed integer. If the value passed isn't equal to one of the configured attribute values, the import process creates the recommendation with the passed type anyway.
You can define a list of RecommendationTypes in the Business Manager. For example, you can define a new type 4=="down-sell" or 5=="upside down sell", which appear in the XML file, as shown in the following sample:
<recommendation type="4" target-id="PN0002" source-type="product" source-id="PN0001" />
<recommendation type="5" target-id="S1965524" source-type="product" source-id="S1937231"/>Sorting
Recommendations are sorted in the context of the source object and type. This sorting is accomplished in the Business Manager and as part of the catalog import process.
The import process positions recommendations in the same order as they appear in the catalog import file. An imported recommendation is:
- Added to the bottom of the list of existing recommendations in REPLACE mode, and new recommendations in MERGE mode
- Left at its current position for existing recommendations in MERGE mode
