1. Administration

Walkthrough: Creating a custom index

Version:
Note

This walkthrough applies to Sitecore XC releases 9.0.2 and 9.0.3.

You can create your own custom indexes for your search provider if the default indexes do not suit your purposes. This walkthrough describes how to create a new custom index, create a policy for incremental updates to the index, and configure the update strategy to update the index itself.

This walkthrough describes how to:

For the purposes of this walkthrough, the new custom index uses Solr as a search provider and contains Commerce catalog items from the Sitecore master database.

Create a new Solr core

Follow the instructions on the Solr website to create and initialize a new Solr core called mysite_master_products.

Create new Commerce Engine lists to track incremental changes

All indexing configuration is stored in the Plugin.CatalogIndexing.PolicySet-1.0.0.json file. You must add a new policy that instructs the Commerce Engine to create new lists for tracking incremental updates to your custom index.

For more information on incremental index updates in Sitecore XC, see the Incremental index updates topic.

Note

You must add this configuration in all Commerce Engine environments.

To create new lists in Commerce Engine to track incremental changes:

  1. Navigate to the c:\inetpub\wwwroot\<environment>\wwwroot\data\Environments folder and open the Plugin.CatalogIndexing.PolicySet-1.0.0.json file.

  2. Add a policy block (under the "values" list) to create managed lists for incremental updates to your custom index:

      {
    "$type": "Sitecore.Commerce.Plugin.Catalog.SitecoreCatalogIndexingPolicy, Sitecore.Commerce.Plugin.Catalog",
    "Name": "MySiteSellableItemsIndexMaster",
    "IncrementalListName": "MySiteSellableItemsIncrementalMasterProducts",
    "DeletedListName": "MySiteSellableItemsDeletedMasterProducts",
    "EntityTypeNames": {
      "$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
      "$values": [
         "Sitecore.Commerce.Plugin.Catalog.SellableItem, Sitecore.Commerce.Plugin.Catalog"
      ]
    }
  },
  {
    "$type": "Sitecore.Commerce.Plugin.Catalog.SitecoreCatalogIndexingPolicy, Sitecore.Commerce.Plugin.Catalog",
    "Name": "MySiteCategoriesMasterProducts",
    "IncrementalListName": "MySiteCategoriesIncrementalMasterProducts",
    "DeletedListName": "MySiteCategoriesDeletedMasterProducts",
    "EntityTypeNames": {
      "$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
      "$values": [
        "Sitecore.Commerce.Plugin.Catalog.Category, Sitecore.Commerce.Plugin.Catalog"
      ]
    }
  },
  {
    "$type": "Sitecore.Commerce.Plugin.Catalog.SitecoreCatalogIndexingPolicy, Sitecore.Commerce.Plugin.Catalog",
    "Name": "MySiteCatalogsMasterProducts",
    "IncrementalListName": "MySiteCatalogsIncrementalMasterProducts",
    "DeletedListName": "MySiteCatalogsDeletedMasterProducts",
    "EntityTypeNames": {
      "$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
      "$values": [
         "Sitecore.Commerce.Plugin.Catalog.Catalog, Sitecore.Commerce.Plugin.Catalog"
      ]
    }
  }

  3. Bootstrap the Commerce Engine to persist your changes.

  4. Perform an IIS reset in the IIS Manager.

Create an index configuration file

You must create a configuration file for the new custom index. The index configuration file contains:

  • general information about the index, such as the index name, the Solr core it's associated with, the property store

  • references to the update strategies used to retrieve changed or deleted items for incremental updates to the index

  • a definition for the crawler that populates the index and the root location in the content tree to start from

  • detailed definitions of each update strategy referenced by the index

Example

<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 search:require="solr">
    <contentSearch>
      <configuration type="Sitecore.ContentSearch.ContentSearchConfiguration, Sitecore.ContentSearch">
        <indexes hint="list:AddIndex">
          <index id=" mysite_master_products" type="Sitecore.ContentSearch.SolrProvider.SolrSearchIndex, Sitecore.ContentSearch.SolrProvider">
            <param desc="name">$(id)</param>
            <param desc="core"> mysite_master_products</param>
            <param desc="propertyStore" ref="contentSearch/indexConfigurations/databasePropertyStore" param1="$(id)" />
            <configuration ref="contentSearch/indexConfigurations/defaultSolrIndexConfiguration" />
            <strategies hint="list:AddStrategy">
              <strategy ref="contentSearch/indexConfigurations/indexUpdateStrategies/mysite_products_sellableItemsIntervalAsynchronousStrategyMaster" />
              <strategy ref="contentSearch/indexConfigurations/indexUpdateStrategies/mysite_products_categoriesIntervalAsynchronousStrategyMaster" />
              <strategy ref="contentSearch/indexConfigurations/indexUpdateStrategies/mysite_products_catalogsIntervalAsynchronousStrategyMaster" />
            </strategies>
            <locations hint="list:AddCrawler">
              <crawler type="Sitecore.Commerce.Engine.Connect.Search.Crawlers.SellableItemsCrawler, Sitecore.Commerce.Engine.Connect">
                <ItemsToTake>100</ItemsToTake>
                <ListName>SellableItems</ListName>
                <IndexListName>SellableItemsIndex</IndexListName>
                <Environments hint="list">
                  <environment>HabitatAuthoring</environment>
                </Environments>
                <Database>master</Database>
              </crawler>
              <crawler type="Sitecore.Commerce.Engine.Connect.Search.Crawlers.CategoriesCrawler, Sitecore.Commerce.Engine.Connect">
                <ItemsToTake>100</ItemsToTake>
                <ListName>Categories</ListName>
                <IndexListName>CategoriesIndex</IndexListName>
                <Environments hint="list">
                  <environment>HabitatAuthoring</environment>
                </Environments>
                <Database>master</Database>
              </crawler>
              <crawler type="Sitecore.Commerce.Engine.Connect.Search.Crawlers.CatalogsCrawler, Sitecore.Commerce.Engine.Connect">
                <ItemsToTake>100</ItemsToTake>
                <ListName>Catalogs</ListName>
                <IndexListName>CatalogsIndex</IndexListName>
                <Environments hint="list">
                  <environment>HabitatAuthoring</environment>
                </Environments>
                <Database>master</Database>
              </crawler>
            </locations>
          </index>
        </indexes>
      </configuration>
      <indexConfigurations>
        <indexUpdateStrategies>
          <mysite_products_sellableItemsIntervalAsynchronousStrategyMaster type="Sitecore.Commerce.Engine.Connect.Search.Strategies.SellableItemsIntervalAsynchronousStrategy, Sitecore.Commerce.Engine.Connect">
            <IncrementalIndexListName>MySiteSellableItemsIncrementalMasterProducts</IncrementalIndexListName>
            <DeletedIndexListName>MySiteSellableItemsDeletedMasterProducts</DeletedIndexListName>
            <ItemsToTake>100</ItemsToTake>
            <Environments hint="list">
              <environment>HabitatAuthoring</environment>
            </Environments>
            <param desc="interval">00:10:00</param>
            <param desc="database">master</param>
          </mysite_products_sellableItemsIntervalAsynchronousStrategyMaster>
          <mysite_products_categoriesIntervalAsynchronousStrategyMaster type="Sitecore.Commerce.Engine.Connect.Search.Strategies.CategoriesIntervalAsynchronousStrategy, Sitecore.Commerce.Engine.Connect">
            <IncrementalIndexListName>MySiteCategoriesIncrementalMasterProducts</IncrementalIndexListName>
            <DeletedIndexListName>MySiteCategoriesDeletedMasterProducts</DeletedIndexListName>
            <ItemsToTake>100</ItemsToTake>
            <Environments hint="list">
              <environment>HabitatAuthoring</environment>
            </Environments>
            <param desc="interval">00:10:00</param>
            <param desc="database">master</param>
          </mysite_products_categoriesIntervalAsynchronousStrategyMaster>
          <mysite_products_catalogsIntervalAsynchronousStrategyMaster type="Sitecore.Commerce.Engine.Connect.Search.Strategies.CatalogsIntervalAsynchronousStrategy, Sitecore.Commerce.Engine.Connect">
            <IncrementalIndexListName>MySiteCatalogsIncrementalMasterProducts</IncrementalIndexListName>
            <DeletedIndexListName>MySiteCatalogsDeletedMasterProducts</DeletedIndexListName>
            <ItemsToTake>100</ItemsToTake>
            <Environments hint="list">
              <environment>HabitatAuthoring</environment>
            </Environments>
            <param desc="interval">00:10:00</param>
            <param desc="database">master</param>
          </mysite_products_catalogsIntervalAsynchronousStrategyMaster>
        </indexUpdateStrategies>
      </indexConfigurations>
    </contentSearch>
  </sitecore>
</configuration>

To create a custom index configuration file:

  1. Open a new text file in the App_Config\Include folder and save it with an appropriate file name and .config extension (for example, my_site_master-products_index.config).

  2. Open the file and add your index configuration (using the example above as a guide).

    In addition to configuring index configuration properties, you must define the index crawler, and include configuration for the index update strategies.

  3. Save your changes.

    Note

    In this example, the custom index is configured to contain items from the master database. For this reason, you would store the custom index configuration file in the App_Config\Include folder in your CM deployment.

If you have suggestions for improving this article, let us know!