Preserve Sitecore settings

Current version: 8.2

The product catalog is exposed in Sitecore by use of a Sitecore data provider. The data provider exposes the catalog data as items based on templates, with fields that map to the respective catalog item properties. You can extend the Sitecore templates with additional custom fields.

Sitecore also maintains a number of system fields and properties per template and item. All of the Sitecore-specific field and property values for catalog items are also maintained by the data provider, and stored outside of Sitecore content.

Each Commerce Server catalog item defines an External Settings property. This internal property is used to persist the Sitecore-specific field and property values, along with the Commerce Server catalog item. If you change the Sitecore fields and properties of a Commerce Server managed catalog item, the External Settings property is where those changes are persisted. The changes can be made using one of the available UI tools, such as the Content Editor, Experience Editor, or Merchandising manager, or the changes can be done through the Sitecore item API. Both methods have the same results, and the data will be stored in the Commerce Server catalog.

When you customize the catalog item templates with additional fields, it is important to make sure that the values are persisted safely. Starting with the 8.2 release, you can now dictate whether external settings data is stored along with the original catalog item, or if the external settings data is stored in a separate catalog. This helps you avoid an overwrite of the Sitecore-specific settings when you update the original catalog by using the Commerce Server catalog import process, or by any external means that rebuilds the catalog items.

In the integration with Microsoft Dynamics AX (SCpbMD), it is not always possible to determine which parts of the catalogs that are owned by AX have been changed. The external Sitecore-specific settings are stored in a separate catalog so they are not cleared along with the rest of the catalogs during a full product synchronization. Integration with other external systems may have similar behavior, and will be able to take advantage of the new option.

The Preserve External Settings process is controlled through configuration of the CommerceServer.config file, where the external settings are stored:


        <type name="IExternalSettingsResolver" type="Sitecore.Commerce.Connect.CommerceServer.Catalog.DefaultExternalSettingsResolver,
        Sitecore.Commerce.Connect.CommerceServer" lifetime="Singleton" />

By default, the DefaultExternalSettingsResolver is configured and saves the external settings data, along with the catalog item.

You can specify SeparateCatalogExternalSettingsResolver, which will save the external settings in a separate catalog. When this resolver is used, Commerce Server Connect will create a new Commerce Server catalog which will have the same catalog name and be post fixed with an underscore. For example, if the catalog name is "Adventure Works Catalog", a new catalog named "Adventure Works Catalog_" will be created.


If the external settings are saved in a separate catalog, you may need to define a separate Commerce Server Staging project on this catalog to be able to publish the external settings from the Sitecore CM to the CD environment.

The new resolver creates entries in the separate catalog only if the Sitecore fields have been changed on the original catalog item in the Content Editor. If a catalog item has not been changed, no entry will be created in the external settings catalog.

The SeparateCatalogExternalSettingsResolver will make the following catalog schema additions:




Catalog metadata property used to identify external settings catalog. A value of true identifies the catalog as an external settings catalog.


Catalog metadata property indicating the name of the external settings catalog.


Product definition property assigned to the ExternalSettingsProduct definition defined later in this document.

The SeparateCatalogExternalSettingsResolver will create the following Category and Product definitions:




Category definition used by categories of the external settings catalog.


Product definition used by products of the external settings catalog.

There is no support for preserving and migrating the external Sitecore settings when you switch between the two resolvers in a configuration. It is recommended to set the configuration at an early stage, and not change it later.

A Sitecore item is always based on a single template. Due to template inheritance, all of the fields of the templates in the inheritance hierarchy by design will become a seamless part of the Sitecore item. The data provider manages all fields and settings in the same way, no matter which template the Sitecore item originates from.


We recommend that you do not customize the templates provided by Sitecore and Commerce Server. Create separate custom templates, and have the provided templates inherit from the custom templates. The inheritance relationship is set by modifying the templates with the inheritance information. This information can be re-established in the event that the templates are overwritten by a future Sitecore update.

Do you have some feedback for us?

If you have suggestions for improving this article,