Walkthrough: Create a custom index field handler

Current version: 10.2

You can create a custom field handler class, when the default Search plugin does not provide a handler type that suits the new field you want to add to the index.

This walkthrough describes how to:

  • Create a new field handler to index a new field.

  • Add the new field to the CE Connect search provider configuration to make it searchable in Sitecore.

Create a new field handler to index a new field

To create a new field handler for your custom index field:


The current architecture of search field handlers does not provide the ability to resolve an instance of a pipeline or command. You must add values that the handler requires to the context.

  1. Create a class that inherits from the Sitecore.Commerce.Plugin.Search.AbstractIndexFieldHandler class, and that implements the ComposeValue method, as shown in the following example:

    public class CustomFieldHandler : AbstractIndexFieldHandler
      /// <inheritdoc />
       public override object ComposeValue(object source, ConcurrentDictionary<string, object> context)
    	if (context == null || source == null || !(source is CatalogItemBase entity))
    	   return null;
    	return $"Custom field handler value: {entity.Id}";

    If you have a requirement to create a custom handler that supports asynchronous calls to pipelines for indexing real time values, you must derive your custom handler from the AbstractAsyncIndexFieldHandler class.

  2. To register the custom field handler with the search index, you must add it to the search policy set for the search provider used in your deployment. The policy set for Solr (PlugIn.Search.Solr.PolicySet-1.0.0.json) contains two policies of the type Sitecore.Commerce.Plugin.Search.ItemIndexablePolicy, Sitecore.Commerce.Plugin.Search. These policies represent the Master and Web databases of the connected Sitecore XP site. You add your custom field handler in the “Fields” collection for both indexes to register the new handler and ensure that your content is indexed in both the Master and the Web databases.

    The following shows an example of a custom Solr field handler ("Company.Project.Search.CustomFieldHandler, Company.Project") added to the PlugIn.Search.Solr.PolicySet-1.0.0.json file.

        "$type": "Sitecore.Commerce.Plugin.Search.ItemIndexablePolicy,
        "IndexName": "sitecore_web_index",
        "FieldTypeMappers": [
        "Fields": [
               "Handler": {
                   "$type": "Company.Project.Search.CustomFieldHandler, Company.Project"
  3. After the configuration changes, bootstrap the Commerce Engine environment to apply the changes.

  4. In Microsoft IIS Manager, restart the Commerce Engine minions service (CommerceMinions_Sc).

  5. Manually rebuild Sitecore XP indexes. After rebuilding the indexes, the new search handlers are visible in the search index, as shown in the following example:

    New search handlers are visible in the search index.

Add a new field to CE Connect search provider configuration

In order to make the new field searchable in Sitecore, you must add it to the search provider configuration in CE Connect.

To add the new field to the search provider configuration in CE Connect:

  1. On your Sitecore service instance, in the \App_Config\Include\Y.Commerce.Engine folder, open the search provider config file. For example, for Sorl, open the Sitecore.Commerce.Engine.Connectors.Index.Solr.config file.

  2. In the FieldMap section, add the new fieldName definition. In the following example, we add a new field named "customfield".

    <field fieldName="customfield" storageType="YES" indexType="UN_TOKENIZED" vectorType="NO" boost="1f" returnType="string" settingType="Sitecore.ContentSearch.SolrProvider.SolrSearchFieldConfiguration, Sitecore.ContentSearch.SolrProvider"/>
  3. Save your changes and bootstrap the Commerce Engine.

Do you have some feedback for us?

If you have suggestions for improving this article,