1. Extending Oracle Commerce
  2. Perform Bulk Export and Import
  3. Export and import catalog data

Export and import catalog data

Catalog data describes the structure of a catalog and specifies the catalog type (independent, filtered, or legacy).

By default, Commerce includes a single catalog called Product Catalog. However, merchants can create and assign additional catalogs. Commerce supports the following types of catalogs:

  • Independent catalogs (version 2) are not dependent on any other catalog in your environment. The default Product Catalog is an independent catalog.
  • Filtered catalogs (version 3) provide custom views into the Product Catalog.
  • Legacy catalogs (version 1) are an older type of secondary catalogs that provide custom views into the Product Catalog.

For detailed information about the different types of catalogs see Understand catalogs.

During an import, the supportVersion1Catalogs attribute determines which type of catalog to use. If this attribute is set to false, and a catalog version is not provided, an independent catalog will be created. If the supportVersion1Catalogs attribute is set to true, then you can create both an independent and legacy catalog. If you set the catalogVersion property value to 1, a legacy catalog is created. If you set the catalogVersion property value to 2, an independent catalog is created. Note that the catalogVersion attribute is added to export data, and cannot be updated.

The fixedParentCategories, ancestorCategories, parentCategoriesForCatalog and computedCatalogs attributes are updated in the repository for each child category that is linked or to be unlinked from a catalog, including any of its child categories.

Top level root categories (both navigation and non-navigation) are made when creating a catalog and cannot be moved or deleted from the catalog. Root categories, however, are not made when creating a legacy catalog. The default Product Catalog cannot be deleted but it may be updated and exported.

The following is a sample request for a catalog import:

{
  "displayName": "Classical Movies Catalog",
  "rootCategories": [
    {
      "id": "category_1"
    },
    {
      "id": "category_2"
    }
  ],
  "id": "ClassicalMoviesCatalog"
}

The catalogVersion, rootNavigationCategory and defaultCategoryforProducts attributes are exported. You can export all catalogs, including the default master catalog, in the repository along with rootCategories. The rootCategories attribute in the response contains navigation and non-navigation categories for standard catalogs, and any number of categories for Master View catalogs, and cannot be updated. The fixedChildCategories for navigation and non-navigation categories are exported for all catalogs, except for Master View catalogs.

The following is an example of a response:

{
  "catalogVersion": 2,
  "defaultCategoryForProducts": {
    "id": "category_1"
  },
  "rootNavigationCategory": {
    "id": "rootCategory_1"
  },
  "displayName": "Classical Movies Catalog",
  "rootCategories": [
    {
      "fixedChildCategories": [],
      "id": "nonNavigableCategory_1"
    },
    {
      "fixedChildCategories": [
        {
          "id": "cat40013"
        },
        {
          "id": "cat60023"
        }
      ],
      "id": "rootCategory_1"
    }
  ],
  "id": "ClassicalMoviesCatalog"
}

The following section describes the fields and validation that occurs when exporting or importing catalog data.

Catalog export and import fields

The following fields can be exported and imported for catalogs.

Field Name Description
displayName The name of the catalog.
Id The ID of the catalog.
rootCategories An array of categories associated with the catalog. From this field, you can export the Id fields of the categories.
translations

This field indicates the different names for an attributed based on the language. The current displayName is supported. The following is an example of a response: 

translations": {
  "items": [
    {
      "displayName": "Classical Movies Catalog",
      "lang": "en"
    },
    {
      "displayName": "[DE]Classical Movies
        Catalog[DE]",
      "lang": "de"
    }
  ]
}
catalogVersion Specifies the type of catalog. 1 specifies a legacy catalog, 2 specifies an independent catalog, and 3 specifies a filtered catalog.
defaultCategoryForProducts Identifies the default collection for a product. By default this links the product to the default collection in a site's default catalog. If this attribute is null, the product is orphaned.
rootNavigationCategory Identifies the navigation category for a catalog.

When there is a relationship between entities such as a collection and products, relationship updates are Full updates. New relationships override existing ones during the import or export process.

During import, you can link independent collections to catalogs. When you create a Master View catalog, the top level root categories are not created. By default, the master catalog’s navigation category is linked to the rootNavigationCategory attribute. Additionally, you can link any of the Master View catalogs to collections that are only available in the default master catalog. Errors will occur if you try to link a collection that is not in the master catalog.

When you create a catalog, the top level root categories are created; this is not the case with Master View Catalogs.

Catalog validations

The following validations are performed when importing catalogs:

  • The required displayName is valid.
  • The required catalogId is valid and must contain only alphanumeric, underscore (_) or dash (-) characters.
  • The rootCategories array should have valid categories.
  • The catalogVersion attribute value is validated based on the supportVersion1Catalogs attribute setting.
  • The defaultCategoryForProducts attribute is validated to ensure that you are not linking a collection to a root category of a standard catalog.

Special handling of large products import

You may experience some performance issues if you import more than 100,000 products and the products are not properly categorized. To avoid import performance issue, please follow these guidelines:

  1. A collection should not hold too many products. Try to restrict it to 10,000 products per collection
  2. Avoid creating too many price list groups.

Import Parameter

You should pass the parameter fullPublishMode as true when initiating a large import. Use this option with care since the recording of the changes are disabled to speed up the import process. Full publish becomes mandatory after the imports are performed using this parameter. Note that "full publish" means that all changes will be published.

For example, a sample request payload to trigger initial data import:

{
  "mode": "standalone",
  "id": "Products",
  "format": "json",
  "params": {
    "fullPublishMode": "true",
    "update": "false"
  }
}

Note: fullPublishMode=true should only be used for initial data imports.

publishChangeLists

The publishChangeLists endpoint can be used to perform to publish all changes:
/ccadmin/v1/publishingChangeLists/publish {"operationType":"publish", "skipDependencyCheck":"true"}
You can optionally set skipDependencyCheck:"true" to skip any other dependency checks from other modifications that are not necessary for publish operations.

Bulk import and export filtered catalogs

You can bulk import and export filtered catalogs. For detailed information on working with filtered catalogs, refer to Configure catalogs with optional collections.