Catalog Object Import/Export

Business Manager Import/Export Location

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

Catalog Import

You can import a catalog from a CSV or XML file type. A CSV file can only be uploaded in MERGE mode and you have to specify which catalog you're uploading before continuing the import process.

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 and relationships are not 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 for the existing product doesn't change unless one 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

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

Category elements can appear in any order in the feed.
You can 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 is 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 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 UPDATE Mode:

Understanding the behavior of UPDATE mode is important for customers who can produce catalog delta files to update their catalogs.

Note: To remove obsolete data during catalog import, use REPLACE mode.

If a category that is the target of a category link is imported without the category that is the link's source, the link isn't removed.
If a category with child categories is imported without its children, the children are not 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.

Product elements can appear in any order in the feed.
You can 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.
Product variations and variation groups are owned by exactly one base product. You can change this ownership from one base product to another in a single import process.
If a variation product is imported without its base product, the product remains a variation.
If a base product is imported without its variation products, the products specified in the <variation product> section remain related to the base product. Other variation products are unlinked from the base product and become normal products.
If a product set is imported without its parent product-set, it remains a member of the set.
If a bundled product is imported without its bundle, it remains a member of the bundle.
If a product that is the target of a product link is imported 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.

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:

merge: the default.
replace: use if you intend to erase all stored image information for a product and then reimport. Use this, for example, if you changed the variation attributes that a base product uses to vary its images by.

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.

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 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:

order-required is set to false
searchable is set to false
externally-defined is set to true

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:

New attribute definitions are added and the externally-defined flag is set to true in 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 false in the B2C Commerce database are ignored during import and the system logs a data error.
Invalid attribute definitions are skipped during import. If there is an existing attribute with the same ID and the externally-defined-flag set to true, it's removed. This also removes any configured values for the attribute from the B2C Commerce database.
Attribute definitions that have the externally-defined flag set to true in the B2C Commerce database and that are not present in the import feed are removed. This 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 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 variation products before replacing them with the variation products 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">
                <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

You can control the sorting of variation products and variation attribute values during catalog import. This is useful if you need to preserve the sort order of existing variation products 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: Variation products are not 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.

Note: The handling of these elements is completely independent of the top-level import mode used for the catalog import.