Adding a property field to an index

Current version: 10.2

When a Sitecore index rebuild is invoked, Commerce Engine indexing minions add the indexed fields to the sitecore_web_index and the sitecore_master_index to enable search for Catalog content items, for example Habitat catalog content items, in the Sitecore Content Editor, or in the SXA storefront.

The Commerce Engine implements a number of default index field handlers that define the configuration properties required to map, for example, a catalog entity field to an index field type. To introduce new catalog property fields in a search index, you must add the appropriate field handler configuration to the PlugIn.Search.Solr.PolicySet.*.json file. There is no need to write or change code, assuming that you can map the new field to one of the existing Catalog field handlers. If you cannot use one of the existing field handlers to index your custom catalog item field, you can create a custom field handler that supports it.

Overview of index field mapping definitions in the search policy set file

There are two approaches to consider when mapping a new field to an index. You can either map the new index field directly to a Commerce entity property, or you can use a computed field (such as a Solr dynamic field ), through a field handler implementation, similar to the way Sitecore uses computed fields in Solr field name resolution.

You add new Commerce entity properties to the index by mapping an index field type to the custom entity property in the PlugIn.Search.Solr.PolicySet.*.json file. This policy set file resides on the instance of the Commerce Engine that is hosting the indexing role in your deployment (for example: C:\inetpub\wwwroot\CommerceMinions_Sc\wwwroot\data\Environments).

In the policy set file, the ItemIndexablePolicy policy defines index field mappings in two main configuration sections: the "FieldTypeMappers" and "Fields" sections.

FieldTypeMappers configuration

The "FieldTypeMappers" section details a collection of IndexFieldTypeMapper configurations that define how different Commerce Engine data types map to Sorl index field types. The following sample from the PlugIn.Search.Solr.PolicySet.*.json file shows some of the default "FieldTypeMappers" definitions for the web index ("IndexName": "sitecore_web_index"):

RequestResponse

"$type": "Sitecore.Commerce.Core.PolicySet, Sitecore.Commerce.Core",
  "Id": "Entity-PolicySet-SolrSearchPolicySet",
  "Version": 1,
  "IsPersisted": false,
  "Name": "SolrSearchPolicySet",
  "Policies": {
    "$type": "System.Collections.Generic.List`1[[Sitecore.Commerce.Core.Policy, Sitecore.Commerce.Core]], mscorlib",
    "$values": [
     ...
      {

        "$type": "Sitecore.Commerce.Plugin.Search.ItemIndexablePolicy, Sitecore.Commerce.Plugin.Search",
        "IndexName": "sitecore_web_index",
        "FieldTypeMappers": [
          {
            "TypeName": "stringCollection",
            "Type": "System.Collections.Generic.List`1[System.String]",
            "NameFormat": "{0}_sm",
            "MultiValued": true
          },
          {
            "TypeName": "textCollection",
            "Type": "System.Collections.Generic.List`1[System.String]",
            "NameFormat": "{0}_txm",
            "MultiValued": true
          },
          {
            "TypeName": "text",
            "Type": "System.String",
            "NameFormat": "{0}_t",
            "CultureFormat": "_{1}"

FieldTypeMappers properties

The configuration properties of the FieldTypeMappers are:

Properties	Description
`"TypeName"`	The name of the field type used in the Commerce Engine. .
`"Type"`	Specifies the class name that implements the system type.
`"NameFormat"`	Defines the of format the type name.
`"CultureFormat"`	Defines the format used to specify the culture for localization when applicable.
`"MultiValued"`	Indicates whether a single document contains multiple values for this field type.

Fields configuration

The SolrIndexFieldConfiguration class defines the properties of the "Fields" configuration. The "Fields" section of the .json file details a collection of configuration properties maps a Commerce entity or component property to a Solr index field. The following shows a sample of some of the default mappings from the "Fields" section in the PlugIn.Search.Solr.PolicySet.*.json file.

RequestResponse

"$type": "Sitecore.Commerce.Core.PolicySet, Sitecore.Commerce.Core",
  "Id": "Entity-PolicySet-SolrSearchPolicySet",
  "Version": 1,
  "IsPersisted": false,
  "Name": "SolrSearchPolicySet",
  "Policies": {
    "$type": "System.Collections.Generic.List`1[[Sitecore.Commerce.Core.Policy, Sitecore.Commerce.Core]], mscorlib",
    "$values": [
        {
     "FieldTypeMappers": [ 
      ...

     "Fields": [
          {
            "$type": "Sitecore.Commerce.Plugin.Search.Solr.SolrIndexFieldConfiguration, Sitecore.Commerce.Plugin.Search.Solr",
            "Name": "sxacontent",
            "Type": "System.Collections.Generic.List`1[System.String]",
            "TypeHint": "textCollection",
            "Handler": {
              "$type": "Sitecore.Commerce.Plugin.Catalog.SxaContentFieldHandler, Sitecore.Commerce.Plugin.Catalog"
            }
          },

Fields properties

The following table lists and defines properties of Fields:

Property	Description
`"$type"`	References the class name that implements the field type.
`"Name"`	Specifies the index field name.
`"Type"`	The field type.
`"TypeHint"`	Defines the type of values that can be passed.
`"Handler"`	Specifies a reference to the class that defines the field handler.
`"ValueSource"`	Specifies the name (`"PropertyName"`) of the Commerce property in Sitecore that maps to the index field name. Also takes a `"PropertyPath"` value that specifies the component class that defines the property if applicable.
`"Localizable"`	Specifies whether the field is a string that can be localized.

Examples of catalog entity property to index field mapping

There are many ways to map a Commerce entity property to an index field. This section provides various configuration examples of field mappings.

Mapping configurations are defined in the Solr policy set file PlugIn.Search.Solr.PolicySet.*.json.

Example of 1:1 mapping where the index field name and the entity property are the same

The following shows an example where the index field name ("DisplayName") and the Commerce property name are the same. There is no need to specify a "ValueSource" to define the Commerce property name, nor a handler.

RequestResponse

{
   "$type":"Sitecore.Commerce.Plugin.Search.Solr.SolrIndexFieldConfiguration,
   Sitecore.Commerce.Plugin.Search.Solr",
   "Name":"DisplayName",
   "Type":"System.String"
}

Example of a mapping where the index field name and the entity property name are different

There are cases where an index field name does not map directly to a static Commerce entity property name. In the following example, the index field name "CatalogEntityId" maps to the Commerce entity property name specified in the "ValueSource":

RequestResponse

{
  "$type":"Sitecore.Commerce.Plugin.Search.Solr.SolrIndexFieldConfiguration, Sitecore.Commerce.Plugin.Search.Solr",
  "Name":"CatalogEntityId",
  "Type":"System.String",
  "ValueSource":{
      "PropertyName":"Id",
      "PropertyPath":""
  }
}

Example of a property mapping from a component using a different name for the field than the actual property name

The following shows an example where the index field DisplayPropertiesColor maps to a component display property defined using a "ValueSource".

RequestResponse

{
  "$type":"Sitecore.Commerce.Plugin.Search.Solr.SolrIndexFieldConfiguration,
Sitecore.Commerce.Plugin.Search.Solr",
  "Name":"DisplayPropertiesColor",
  "Type":"System.String",
  "TypeHint":"string",
  "ValueSource": {
      "PropertyName":"Color",
      "PropertyPath":"DisplayPropertiesComponent"
  }
}

Example of a mapping using a custom field handler

The following shows an example configuration that uses a custom index field handler:

RequestResponse

{
   "$type":"Sitecore.Commerce.Plugin.Search.Solr.SolrIndexFieldConfiguration,
Sitecore.Commerce.Plugin.Search.Solr",
   "Name":"_UniqueId",
   "Type":"System.String",
   "Handler":{
     "$type":"Sitecore.Commerce.Plugin.Catalog.UniqueIdFieldHandler,
Sitecore.Commerce.Plugin.Catalog"
   }
}

Adding Composer-defined catalog item properties to an index

When you add a view to define a custom property for a Catalog entity using a Composer template (that is, if you link the template to a catalog, category, or selleable item entity), you use the ComposerFieldHandler to add the new property field to the index.

Note

When indexing a custom property that uses a rich text value, all formatting information is removed. Only the raw text value is indexed for text-based search support.

You add composer field handler configurations to the PlugIn.Search.Solr.PolicySet.*.json file.

The Composer field handler

The Catalog plugin contributes a ComposerFieldHandler class that allows you to add a custom entity property defined using Composer to the index. The Composer field handler contains a "ComposerSource" section that specifies the name of the view within the Composer template, and the name of the custom property to map to an index field.

RequestResponse

"Handler": { 
  "$type": "Sitecore.Commerce.Plugin.Catalog.ComposerFieldHandler,
Sitecore.Commerce.Plugin.Catalog",
  "ComposerSource": {
      "ViewName": "MyViewName", 
      "PropertyName": "StringPropertyName"
    }

Properties of the ComposerFieldHandler index field handler

The Composer field hander contains "ComposerSource" properties that specifies the name of the Composer view, and the name of the custom property to index. The following table lists and describes the configuration properties of the ComposerFieldHandler:

Property	Description
`"$type"`	Specifies the class names that implement the `ComposerFieldHandler`
`"Viewname"`	Specifies the child view name that contains the custom entity property in Composer.
`"PropertyName"`	Specifies the name of the custom Composer entity property that maps to an index field.

Note

The Viewname and PropertyName are those defined in the Catalog entity child view.

Example of mapping a Composer string property

The following shows a configuration example for mapping a custom Catalog entity property defined as a string data type to the appropriate index field type.

RequestResponse

{
 "$type": "Sitecore.Commerce.Plugin.Search.Solr.SolrIndexFieldConfiguration,
Sitecore.Commerce.Plugin.Search.Solr",
 "Name": "StringPropertyIndexName",
 "Type": "System.String",
 "Handler": {
   "$type": "Sitecore.Commerce.Plugin.Catalog.ComposerFieldHandler,Sitecore.Commerce.Plugin.Catalog",
   "ComposerSource": {
       "ViewName": "MyViewName",
       "PropertyName": "StringPropertyName"
  }
 }
}

Example of mapping a Composer integer property

The following shows a configuration example for mapping a custom Catalog entity property defined as an integer data type to the appropriate index field type.

RequestResponse

{ 
 "$type":
"Sitecore.Commerce.Plugin.Search.Solr.SolrIndexFieldConfiguration,
Sitecore.Commerce.Plugin.Search.Solr",
 "Name": "IntegerPropertyIndexName",
 "Type": "System.Int64",
 "Handler": {
   "$type": "Sitecore.Commerce.Plugin.Catalog.ComposerFieldHandler, Sitecore.Commerce.Plugin.Catalog",
   "ComposerSource": {
   "ViewName": "MyViewName",
   "PropertyName": "IntegerPropertyName"
  }
 }
}

Example of mapping a Composer decimal property

The following shows a configuration example for mapping a custom Catalog entity property defined as a decimal data type to the appropriate index field type.

RequestResponse

{
 "$type":
"Sitecore.Commerce.Plugin.Search.Solr.SolrIndexFieldConfiguration,
Sitecore.Commerce.Plugin.Search.Solr",
 "Name": "DecimalPropertyIndexName",
 "Type": "System.Decimal",
 "Handler": {
  "$type": "Sitecore.Commerce.Plugin.Catalog.ComposerFieldHandler, Sitecore.Commerce.Plugin.Catalog",
  "ComposerSource": {
    "ViewName": "MyViewName",
    "PropertyName": "DecimalPropertyName"
  }
 }
}

Example of mapping a Composer DateTimeOffSet property

The following shows a configuration example for mapping a custom Catalog entity property defined as a DateTimeOffSet data type to the appropriate index field type.

RequestResponse

{
 "$type":
"Sitecore.Commerce.Plugin.Search.Solr.SolrIndexFieldConfiguration,
Sitecore.Commerce.Plugin.Search.Solr",
 "Name": "DateTimeOffsetPropertyIndexName",
 "Type": "System.DateTimeOffset",
 "Handler": {
   "$type": "Sitecore.Commerce.Plugin.Catalog.ComposerFieldHandler,Sitecore.Commerce.Plugin.Catalog",
   "ComposerSource": {
     "ViewName": "MyViewName",
     "PropertyName": "DateTimeOffsetPropertyName"
  }
 }
}

Example of mapping a Composer Boolean property

The following shows a configuration example for mapping a custom Catalog entity property defined as a Boolean data type to the appropriate index field type.

RequestResponse

{
 "$type":
"Sitecore.Commerce.Plugin.Search.Solr.SolrIndexFieldConfiguration,
Sitecore.Commerce.Plugin.Search.Solr",
 "Name": "BooleanPropertyIndexName",
 "Type": "System.Boolean",
 "Handler": {
  "$type": "Sitecore.Commerce.Plugin.Catalog.ComposerFieldHandler, Sitecore.Commerce.Plugin.Catalog",
  "ComposerSource": {
    "ViewName": "MyViewName",
    "PropertyName": "BooleanPropertyName"
    }
  }

Adding a Sitecore-specific catalog item field to an index

When you add custom fields to a sellable item template in Sitecore, or when you set the value of an existing Sitecore-specific item field, these custom Sitecore item fields exist in Sitecore only. On the Commerce Engine side, these Sitecore-specific fields persist as ExternalSettingsComponents. Sitecore XC implements an ExternalSettingsFieldHandler handler that you can configure so that the Commerce Engine adds Sitecore-specific catalog item fields to the indexes.

The External Settings field handler

The Commerce Engine Catalog plugin contributes the ExternalSettingsFieldHandler class that allows you to add Sitecore-specific catalog item properties to the search index.

The following shows an example of the ExternalSettingsFieldHandler configuration that you add to the PlugIn.Search.Solr.PolicySet.*.json:

RequestResponse

{
  "$type": "Sitecore.Commerce.Plugin.Search.ItemIndexablePolicy, Sitecore.Commerce.Plugin.Search",
  "IndexName": "sitecore_master_index",
  "FieldTypeMappers":
   ...
  "Fields": [ 
    {
    "$type":"Sitecore.Commerce.Plugin.Search.Solr.SolrIndexFieldConfiguration, Sitecore.Commerce.Plugin.Search.Solr",
    "Name":"ExampleExternalSettingProperty",
    "Type":"System.String",
    "Handler":{
        "$type":"Sitecore.Commerce.Plugin.Catalog.ExternalSettingsFieldHandler, Sitecore.Commerce.Plugin.Catalog",
        "ExternalSettingsPropertyName":"Items Per Page"
        },   
    "Localizable":false

Property of the ExternalSettingsFieldHandler index field handler

The following table lists and describes the configuration properties of the ExternalSettingsFieldHandler handler:

Property	Description
`"ExternalSettingsPropertyName"`	The name of the custom Sitecore catalog item field that defines the value to index.

Note

If the external setting property is a shared property, you must set the "Localizable" property to "false".

Updating the Solr configuration

If you are using the Solr search provider, and you want to provide the ability to search using custom fields, you must create a configuration patch file that defines the new fields and data types. You add the configuration file in the /App_Config/Include/Z.Commerce.Engine folder. The following shows an example of a configuration patch file:

RequestResponse

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:search="http://www.sitecore.net/xmlconfig/search/" xmlns:role="http://www.sitecore.net/xmlconfig/role/">

  <sitecore role:require="Standalone or ContentDelivery or ContentManagement" search:require="solr">
    <contentSearch>
      <indexConfigurations>
        <defaultSolrIndexConfiguration type="Sitecore.ContentSearch.SolrProvider.SolrIndexConfiguration, Sitecore.ContentSearch.SolrProvider">
          <fieldMap type="Sitecore.ContentSearch.SolrProvider.SolrFieldMap, Sitecore.ContentSearch.SolrProvider">
            <fieldNames hint="raw:AddFieldByFieldName">
              <field fieldName="stringpropertysolr" storageType="YES" indexType="TOKENIZED" vectorType="NO" boost="1f" returnType="string" settingType="Sitecore.ContentSearch.SolrProvider.SolrSearchFieldConfiguration, Sitecore.ContentSearch.SolrProvider"/>
            </fieldNames>
          </fieldMap>
        </defaultSolrIndexConfiguration>
      </indexConfigurations>
    </contentSearch>
  </sitecore>
</configuration>

Do you have some feedback for us?

If you have suggestions for improving this article,