Customizing search

This document describes how to customize and extend the search in EPiServer Commerce by for instance adding index fields and creating new search indexers for specific purposes. Refer also to the section Creating a Search Provider in the EPiServer Commerce SDK for related information.

Classes referred to here are available in the following namespaces:

• Mediachase.Search
• Mediachase.Search.Extensions
• Mediachase.Search.Extensions.Indexers

Adding index fields

The process of adding a new field can differ depending on the provider you use and where the data is coming from. Here we explain the steps to add field for the catalog index using Lucene and SOLR providers.

When using Lucene and you simply want to add meta field to be searchable, go to the meta field configuration in Commerce Manager and mark it as searchable. The field will be automatically added to the index.

When using SOLR, you will need to do an extra step and add that field into the SOLR configuration file which is located in APACHERROOT\solr\catalog\conf\catalog.schema.xml.

Example: adding an index filed to the SOLR Schema

<field name="MyNewField" type="string" indexed="true" stored="true" multiValued="true" />

To add a field programatically in the case when data comes from an external data source or needs to be computed, you will need to create a new class that inherits the existing CatalogIndexer.

Example: adding a custom index class

public class MyCatalogIndexer : Mediachase.Search.Extensions.Indexers.CatalogIndexBuilder
        {
                /// <summary>
                /// Called when catalog entry is indexed. Override this method to add some extra fields.
                /// </summary>
                /// <param name="document">The document.</param>
                /// <param name="entry">The entry.</param>
                /// <param name="language"></param>
                protected override void OnCatalogEntryIndex(ref SearchDocument document, CatalogEntryDto.CatalogEntryRow entry, string language)
                {
                    // Example, add all apple products as featured
                    if(entry.Name.Contains("apple"))
                        document.Add(new SearchField("featured", true));

                    base.OnCatalogEntryIndex(ref document, entry, language);
                }
        }

Creating a search indexer

Search Indexer is a component that is responsible for assembling data into documents that Search Provider can then index. It typically connects subsystems like Catalogs, gets a list of changes and submits it to the search provider. This document describes how to implement a new search indexer.

By default EPiServer Commerce indexes catalog data via the the BaseCatalogIndexBuilder class or an inheriting class. However, third party implementations may implement ISearchIndexBuilder instead of extending the BaseCatalogIndexBuilder.

/// <summary>
/// Search Index Builder Interface.
/// </summary>
public interface ISearchIndexBuilder
{
    /// <summary>
    /// An event handler for progress message events.
    /// </summary>
    event SearchIndexHandler SearchIndexMessage;

    /// <summary>
    /// Gets or sets the manager.
    /// </summary>
    /// <value>The manager.</value>
    SearchManager Manager { get; set; }

    /// <summary>
    /// Gets or sets the build indexer.
    /// </summary>
    /// <value>The build indexer.</value>
    IndexBuilder Indexer { get; set; }

    /// <summary>
    /// Builds the index.
    /// </summary>
    /// <param name="rebuild">if set to <c>true</c> the full rebuild will be done, if not. The last build date will be used.</param>
    void BuildIndex(bool rebuild);

    /// <summary>
    /// Updates the specified items in the index.
    /// </summary>
    /// <param name="itemIds">The ids of the items to update.</param>
    /// <returns>True if successful; otherwise, false.</returns>        
    bool UpdateIndex(IEnumerable<int> itemIds);
}

The UpdateIndex method is used by the updated catalog event system, and will be called for any changed or deleted catalog entries. The parameter will enumerate catalog entry IDs of changed or delete entries, and the implementation is expected to update the search indexes appropriately for these entries.

If a transient error occurs (for example, a network error when accessing a remote service), UpdateIndex should return false. The system may then retry the same batch of updates again later. If a non-transient error occurs, then the implementation should throw an exception.

An implementation of ISearchIndexBuilder should throw an exception from UpdateIndex if the updated event system is not supported, and scheduled tasks will be used to execute BuildIndex.

See also

• The Search section in the EPiServer CMS SDK