Catalog Object Import/Export

You can 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.

Catalog import/export is designed so that:

Business Manager Import/Export Location

Select site > Merchant Tools > Products and Catalogs > Import & Export

Catalog Import

The catalog import is currently implemented as a two-pass import.

  1. In the first pass, objects are created, updated, and deleted.
  2. In the second pass, relationships between objects are established.

This allows the category and product elements to appear in any order in the feed. You typically have no exposure to the two passes. However, if you are using the default transaction mode (for example, changes are committed after each object) and the import is aborted between the first and second pass for a particular object, an object can be left behind that was created or updated, though the relationships had not yet been established.

New products imported in MERGE and REPLACE modes default to offline status if this status isn't specified in the import file.

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

You can export data on selected products from Business Manager or through a custom pipeline. During catalog export, Salesforce B2C Commerce automatically trims leading and trailing whitespace and removes any previously saved newline characters in a product image path.

Business Manager catalog export mode Export Specific Products only contains the list of selected products and the category assignments for those products. Select site > Merchant Tools > Products and Catalogs > Import & Export > Catalog Export > catalog > product(s). You can use the standard product search functionality or the beta search functionality as described in Simple Products Search.

Note: The beta search functionality must be enabled by Commerce Cloud Support.

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 has an import configuration that lets you delete the catalog before import. You can use this as a high-performance way to empty a catalog, specifically if the objects in the catalog are unknown. You can also delete custom attributes before import when using the UPDATE or MERGE mode. For more information, see Removing Outdated Objects.

Custom product attribute definitions can only be imported using the pipelet ImportCatalog. It isn't possible to import product object custom attribute definitions using Business Manager catalog import. The import of custom product attribute definitions must be explicitly enabled. Do this by setting 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 are not imported.

If product attribute definitions are provided 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 a Products iterator is specified, only the category assignments for the list of exported products or categories assignments are contained in the export file. 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

The following are some element-specific details you need to consider when importing a category element.

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 these element are submitted in XML with an empty value, for example, <online-from/>.You can reset the online-from and online-to category attributes during a catalog import process.

To rest 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>

You must also 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 REPLACE Mode:

Understanding the behavior of REPLACE mode is important for customers who can produce catalog "delta files" to update their catalogs, but want to use "replace-mode" import to ensure that obsolete data is 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

The following are some element-specific details you need to consider when importing the product element. Understanding the behavior of REPLACE mode is important for customers who can produce catalog delta files to update their catalogs, but want to use "replace-mode" import to ensure that obsolete data is removed.

Resetting product Attributes

In some cases, you might want to remove values for product attributes during import in merge mode.

You can 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>
You also need to 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">
Note: This should be included in the file on a single line.

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.

Sub-element 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 that are 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. Sometimes for values (for example, variation attribute values) a specific merge-mode is available; but this isn't the case for the custom attributes to which you are 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 REPLACE semantic is used by default. This 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 by specifying 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:

Note: As with other cases where the 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 is especially helpful in the case where a single (classification) catalog is used in conjunction with multiple, site-specific (navigation) catalogs.

In 2.11.3, a new element, variation-configuration, and a new complex type, VariationConfiguration, were added to 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 is represented 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, each product’s actual position is determined by the order in which it appears in the file.

For example, in Business Manager Product A is assigned as position 1 and Product B is assigned as 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 is listed first and Product B is listed 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.

Attribute definitions can only be imported via the ImportCatalog pipelet and can't be imported via Business Manager import. Product attributes created by catalog import have the following default values:

Note: You can change the values of these attributes in Business Manager. These attributes can have a significant impact on other parts of your storefront, notably your checkout processing. Because the catalog import is intended to let you create product attribute definitions from a backend system automatically, you are prevented from accidentally causing problems with your storefront by the requirement that you explicitly change them separately.

If the product-attribute-definitions element isn't defined in the import file, no existing product attribute definitions are modified during import.

The element is processed identically for the MERGE, REPLACE, and UPDATE modes. If the product-attribute-definitions element is defined in the import file, the import checks whether the attribute definition already exists in the database and does the following:

For the import mode DELETE any product-attribute-definitions elements defined in the import file are ignored.

Note: Importing an existing attribute definition with a new value type or a new localizable status is considered a new attribute definition and replaces the existing attribute definition with the same ID.

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 is unnecessary to use the attribute in REPLACE mode, because that mode automatically removes all variants before replacing them with the variants listed in the feed.

This means you can choose to add variations and remove variations by adding them to separate variants elements. You can only have 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">
                <variant product-id="883239585285"/>
                <variant product-id="883239585289"/>
        </variants>       
    </variations>
</product>
Example 2: remove three variations
<product product-id="28447">
    ...
    <variations>
        <variants merge-mode="remove">
                <variant product-id="883239585281"/>
                <variant product-id="883239585282"/>
                <variant 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">
                <variant product-id="883239585287"/>
        </variants>
    </variations>
</product>

Sorting of variants and variation attribute values on Import

You can control the sorting of variants and variation attribute values during catalog import. This is useful if you need to preserve the sort order of existing variants and variation attribute values when importing.

If merge is specified for the merge-mode attribute of the variation-attribute-values and variants elements, the importer handles the values as follows:
  • All new values specified in the import file are imported at the end of the list, in the same order as specified in the import file.
  • All existing values specified in the import file are updated. This means that all attributes of the value, such as display name, are updated if specified in the import file. The position of the existing values are not updated. All existing values not specified in the import file are removed.
    Note: For variants, the products are not removed, but are unlinked from the master 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.
Note: The handling of these elements is completely independent of the top-level import mode used for the catalog import.

Related Links

Import Export Object Cheatsheet

Simple Product Search

Removing Outdated Objects

X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used and to tailor advertising. By continuing to use this site you are giving us your consent to do this.