Custom Product Attributes and the ExternalSettings Field

I've been working with a partner, helping them address some issues with their catalog. The specific issue is with the ExternalSettings field that's used to hold values of custom attributes defined on the Commerce data templates in Sitecore.

The ExternalSettings Catalog Property

The Commerce catalog data is integrated into the Sitecore content tree using a custom data provider. The Sitecore data provider is used for exposing the Commerce product schemas as data templates.

In some cases, there may be a need to extend the Commerce data templates in Sitecore. There are any number of reasons for this, but is likely done to enrich product content with extra attributes not required as part of the commerce transaction. This might include links to product documentation, videos or other product content for more complex commerce scenarios. The decision to put what attributes where depends on the situation and is a topic for another blog post. 

In Sitecore, when you make a change and add a new field to the Commerce data templates, a special Commerce catalog attribute called ExternalSettings stores the ID and value of the field. A content editor can edit these fields in the Content Editor as well as the Merchandising Manager, but the custom fields are not available in the Catalog Manager desktop tool.

A New Attribute

Consider a Commerce catalog, with the following product definitions:

Catalog Manager Product Definitions

The Backpack product definition might contain the following set of attributes/product properties:

Product Defintion Attributes

Looking at the data templates inside the Content Editor (Templates - Sitecore Commerce - Catalog Generated), the following Commerce templates are displayed. This list of templates matches the list of product definitions that are defined in the Commerce catalog:

Sitecore Commerce Data Templates

What if there was a need to add a rebate form or a link to an instruction manual on a product page? In the data template, create a new field pointing the datasource where the form is stored in the Media Library. Open the Commerce node in the Content Editor and add the rebate form to the product. After the product is saved, the ExternalSettings property in the Commerce catalog stores the field ID and value of this new field.

Newly Added Field

A catalog administrator can edit this new field in the Content Editor and the Merchandising Manager. Also, these new fields need to be marked as Unversioned and Shared to work with the Commerce Data Provider.

Updating and Deleting Commerce Data Templates

The integration provided by Commerce Connect allows an administrator to update and delete the Commerce data templates in Sitecore. In the Sitecore Commerce tab, these options are available:

Sitecore Commerce Tab

Update Data Templates will force an update of the Commerce data templates in Sitecore. New fields added to the templates are not affected by this update, but this will make sure the Commerce-specific templates are up-to-date based on the catalog schema. 

Delete Data Templates will completely remove the Commerce data templates from Sitecore. The delete operation will also remove any new custom attributes. Doing an update (after a Delete) will repopulate the Commerce templates, but not the custom fields. This is because the custom-added fields are not synchronized with the Commerce product schema. The Commerce catalog only stores the field's value and ID for these custom attributes.

An option for backing up these fields, is to use the serialization options (Serialize and Revert Tree) in Sitecore. This creates an XML backup of any changes made to the Commerce data templates. After restoring the data templates from backup, update the Commerce templates to ensure they're current.


In Sitecore Commerce implementations, integration to an ERP or PIM is often required for product data. This is handled by the catalog webservice or through the BizTalk Server adaptors, both of which are provided out of the box.

When pulling in data from other systems, note that the legacy system may or may not have the custom attributes that were defined on the Commerce data templates in Sitecore.

If this integration uses the catalog API to do an import, make sure to set ImportMode = Incremental to ensure any existing catalog data isn't overwritten. Otherwise, if ImportMode = Replace is used, all catalog data will be removed while importing new data, losing the values in the ExternalSettings field. 

This also applies when importing catalogs using the Commerce Catalog Manager. Make sure to use Type = Incremental, as shown here:

Import Catalog Dialog


Our partner's issue was that they updated the catalog using a prior version that did not have the contents of these custom fields. To ensure this data does not get removed, make sure to do incremental updates of catalog data. 

Sitecore Commerce pb Commerce Server provides a flexible solution for combining structured and non-structured product data. To take advantage of this flexibility, it's important to understand some of the behaviors of the integrated product.

(Relevant Sitecore Commerce 8 Documentation is located here)