Feature Pack 7 or later

WebSphere Commerce search configuration file (wc-search.xml) (Search EAR)

The WebSphere Commerce search configuration file (wc-search.xml) contains properties that are related to configuring WebSphere Commerce search application features. You can change the properties to suit your site's needs by creating a custom wc-search.xml file that contains the changed properties only.
The WebSphere Commerce search configuration file consists of four sections:
  • Server - Defines how to connect to the search server. Do not modify.
    Note: The embedded mode should be used for the search server. That is, the AdvancedConfiguration should not be used for the search server, as it uses an additional web container thread to perform searches, which is very inefficient.
  • Index - Defines the associated properties of the search index. Do not modify.
  • Cores - Lists internally used search runtime core server settings. Do not modify.
  • Profiles - Lists sets of search runtime parameters; search index name, search index fields, expression providers, paging and sorting, and search feature configurations (text highlights, facets, and spelling correction). You can control the storefront search experience at a page-level by using different search profiles.
The WebSphere Commerce search configuration files are stored in the following locations by default:
  • The default WebSphere Commerce search configuration file for the search application: Search_eardir/xml/config/com.ibm.commerce.catalog/wc-search.xml
  • The extended WebSphere Commerce search configuration file for the search application. To change the value of an existing property in the WebSphere Commerce search configuration file, you must create a customized version of the file in this location. The customized version of the file must contain only the changed properties: Search_eardir/xml/config/com.ibm.commerce.catalog-ext/wc-search.xml

Search profile properties

The following table summarizes the configurable profile properties in the file. For more information about the properties within the search profile, open the wc-search.xml file and browse to your section of interest.
Important: The following properties rely on the default operator that is configured in the solrconfig.xml file to remain set as OR to function correctly. That is, changing the default OR operator in the solrconfig.xml file is not supported.
wc-search.xml configurable properties
Property Description
Profile The IBM_Global search profile is the base search profile. It contains all common settings and properties that are reusable for most search scenarios. Each of these settings can be individually overridden for more customization.

For a complete list of the default search profiles, see WebSphere Commerce search profiles.

Query Declares properties that influence how the query expression runs against the search server at run time.

Default parameters can be defined in the wc-component.xml file. For more information, see Search properties in the component configuration file (wc-component.xml) (WebSphere Commerce EAR).

It contains the following parameters:
maxRows
Restricts the maximum number of search results per page. The default value is 50.
maxTimeAllowed
Restricts the maximum amount of time allowed (in milliseconds) for any query to run. If the query takes more time than specified, a timeout occurs and partial (or no) results might be returned. If the value is null, the parameter is removed from the request. The default value is 15000.
DynamicKitReturnPrice
Returns the Dynamic Kit price list as part of the CatalogEntryView response. The default value is true.
Required expression providers. These providers cannot be customized or reconfigured.
SolrSearchProfileNameValidator
A Solr specific implementation of the search expression validator for the search profile name. This provider ensures that the control parameter _wcf.search.profile is passed in and its definition is defined in the search configuration file.
SolrSearchIndexNameValidator
This expression provider is for validating the index core name. It can also determine the name if not specified by:
  1. Checking if _wcf.search.index is passed in as part of the expression
  2. If not, then look up the core name from the given search profile
  3. Otherwise, try to derive the core name by using the store ID to determine the master catalog ID and the locale name.
The resulting index name is added back into the SelectionCriteria object (_wcf.search.index) for other downstream processing.
SolrSearchDecodeMetaTokenExpressionProvider
A Solr specific implementation of the search expression provider for decoding the meta string by calling SolrSearchMetaTokenDecoder. The meta string is used for representing the search context, such as the breadcrumb trail.
SolrSearchEncodeMetaTokenExpressionProvider
A Solr specific implementation of the search expression provider for encoding the meta string. This provider encodes the meta string that is stored in _wcf.search.meta so that it can be reused later to represent the current facet state.
SolrSearchExpressionValidator
This search expression provider ensures that the query expression is not empty. If so, it generates a default all inclusive condition (*:*) and adds it back to the SelectionCriteria object (_wcf.search.internal.optional.query). It also ensures that all special characters are escaped properly.
Optional expression providers:
SolrRESTSearchBasedMerchandisingExpressionProvider
A Solr specific implementation of the search-based merchandising expression provider. This provider calls the marketing component to run search rules. Search rules can apply to all searches or target specific search keywords. They might add additional constraints to the search request to influence the order of the results, and add new conditions to the search query with the intention of adding new products to search results.

For example, search rules might scope search results to contain only products that are in stock. They can also elevate products that meet a specific criteria (such as brand, profit margin, or customer ranking) to the top of the search result.

The query fragments produced by search rules are added back into the SelectionCriteria object for other downstream processing:
  • _wcf.search.internal.filterquery
  • _wcf.search.internal.optional.query
  • _wcf.search.internal.mandatory.query
  • _wcf.search.internal.boostquery
  • _wcf.search.internal.sort
  • _wcf.search.term
Note: This provider runs before SolrSearchByKeywordExpressionProvider to ensure that search terms can be replaced successfully by the Add or Replace Search Criteria marketing action.
SolrRESTSearchByCategoryExpressionProvider
Handles the search by category, and considers the sales catalog in the current business context.

The resulting Solr expression is added back into the SelectionCriteria object (category into _wcf.search.internal.mandatory.query and catalog into _wcf.search.internal.filterquery) for other downstream processing.

SolrRESTSearchByManufacturerExpressionProvider
Handles the search by brand name requests. The resulting Solr expression is added back into the SelectionCriteria object (_wcf.search.internal.meta) and to be encoded into the meta string later.
SolrRESTSearchByPriceExpressionProvider
Handles the search by price range request that is generated from the Advanced Search page. The resulting Solr expression is added back into the SelectionCriteria object (_wcf.search.internal.meta) and to be encoded into the meta string later.
SolrRESTSearchByFacetExpressionProvider
Handles the search by facet request. This provider helps convert an XPath expression into a Solr specific expression. The resulting Solr expression is added back into the SelectionCriteria object (_wcf.search.internal.meta) and to be encoded into the meta string later.
SolrRESTSearchByStorePathExpressionProvider
Generates conditions to handle the store path. The resulting Solr expression is added back into the SelectionCriteria object (_wcf.search.internal.filterquery) for other downstream processing.
SolrRESTSearchByPublishedEntryOnlyExpressionProvider
Restricts search results to published entries. The resulting Solr expression is added back into the SelectionCriteria object (_wcf.search.internal.filterquery) for other downstream processing.
SolrRESTSearchByCustomExpressionProvider
Handles the search by custom expression that is stored in _wcf.search.expr. This custom expression is added to the SelectionCriteria object (_wcf.search.internal.optional.query) for other downstream processing.
SolrRESTSearchFacetConditionExpressionProvider
Generates a list of attribute related facets and currency-specific price range facets for the current search request. The resulting Solr expression is added back into the SelectionCriteria object (_wcf.search.facet.field) for other downstream processing.
SolrRESTSearchProductSequencingExpressionProvider
Orders product entries in the search result by ranking.
SolrRESTSearchCategorySequencingExpressionProvider
Sorts categories by ranking.
SolrRESTSearchTermAssociationExpressionProvider
Handles the search term association (STA) expansion. This provider helps get synonyms and replace the search term to fetch the final result. The synonyms fetched by the STA service is added back into the SelectionCriteria object for other downstream processing: _wcf.search.internal.synonyms.
SolrRESTSearchProductEntitlementExpressionProvider
Performs product entitlement. It is performed by calling ProductEntitlementExpressionHelper to build search engine-specific query expressions for contracts that contain CatalogFilter Term Conditions and ProductSet Term Conditions. If a contract list is passed in, ProductEntitlementExpressionHelper builds the search expression against those contracts, instead of fetching contract from context. Otherwise, if there are no contracts passed as a parameter, this helper class fetches the current eligible contracts and builds search expressions against them. The resulting Solr expression is added back into the SelectionCriteria object (_wcf.search.internal.filterquery) for other downstream processing.
SolrRESTSearchCategoryEntitlementExpressionProvider
Performs catalog group-level entitlement by triggering a search on the Catalog Entry core, then parsing the facet count returned from the catalog entry core, and constructing an internal filter query on the catalog group core. The resulting Solr expression is added back into the SelectionCriteria object (_wcf.search.internal.filterquery) for other downstream processing.
SolrRESTSearchByKeywordRelevancyExpressionProvider
Handles the search by keyword request.
SolrRESTSearchInventoryExpressionProvider
Handles searches for the inventory search index.
SolrRESTSearchByIdentifierExpressionProvider
Looks up by identifiers by using the dismax query parser. The resulting Solr expression is added back into the SelectionCriteria object for other processing by using the _wcf.search.internal.optional.query control parameter.
SolrRESTSearchWebContentStoreInfoExpressionProvider
A Solr specific implementation of the search expression provider for creating a mandatory search condition for searching unstructured content, along with a store path if applicable. The resulting Solr expression is added back into the SelectionCriteria object for other processing by using the _wcf.search.internal.filterquery control parameter.
Feature Pack 8SolrRESTSearchByJoinQueryExpressionProvider
Feature Pack 8A Solr specific implementation of the search expression provider to join two indexes and restrict the result to a specific condition. The resulting Solr expression is added back into the SelectionCriteria object for other downstream processing using the _wcf.search.internal.filterquery control parameter.
Postprocessors:
SolrRESTMainCatalogEntryViewResultQueryPostprocessor
Reformat the Solr response into a structured object. The mapping configuration is defined in wc-component.xml file under the XPathToCatalogEntryFieldNameMapping section.
SolrRESTMainCatalogGroupViewResultQueryPostprocessor
Reformat the Solr response into a structured object. It populates the catalogGroupView part of the response. The mapping configuration is defined in wc-component.xml file under the XPathToCategoryViewBODResponseFieldNameMapping section.
SolrRESTMainWebContentViewResultQueryPostprocessor
Reformat the Solr response into a structured object. It populates the webContentView part of the response. The mapping configuration is defined in wc-component.xml file under the XPathToWebContentViewBODResponseFieldNameMapping section.
SolrRESTMainCatalogEntryViewResultQueryPostprocessor
This search query postprocessor populates the catalogEntryView part of the response.
SolrRESTSearchCatalogEntryViewPriceQueryPostprocessor
Reformat the Solr response into a structured object. It populates the price list into the catalogEntryView part of the response. The mapping configuration is defined in wc-component.xml file under the XPathToPriceBODResponseFieldNameMapping section.
SolrRESTSearchCatalogEntryViewDescriptionQueryPostprocessor
This search query postprocessor can be used to provide the Catalog Entry description override information, and language fallback support. This post processor issues a database query to retrieve catalog entry override description which includes, catalog entry name, short description, long description, keyword, thumbnail, and full image properties. It uses the IBM_Get_CatentryDesc_By_LangId_And_CatentryId, and IBM_Get_CatentryDescOverride_By_LangId_And_CatentryId_And_GroupId query template defined in the wc-query-utilities.tpl file.
SolrRESTSearchCatalogEntryViewSKUQueryPostprocessor
Reformat the Solr response into a structured object. It populates the SKUs list into the catalogEntryView part of the response. The mapping configuration is defined in wc-component.xml file under the XPathToCatalogEntryViewBODResponseFieldNameMapping section. This postprocessor, does a sub search query to retrieve the catalog entry associated items(SKUs). It uses the IBM_findCatalogEntrySKUssearch profile.
SolrRESTSearchCatalogEntryViewAttributesQueryPostprocessor
Reformat the Solr response into a structured object. It populates the Attributes list, and Attributes values list into the catalogEntryView part of the response. The mapping configuration is defined in wc-component.xml file under the XPathToAttributesBODResponseFieldNameMapping and XPathToAttributesValuesBODResponseFieldNameMapping sections.
SolrRESTSearchCatalogEntryViewAttachmentsQueryPostprocessor
Reformat the Solr response into a structured object. It populates the Attachments list into the catalogEntryView part of the response. The mapping configuration is defined in wc-component.xml file under the XPathToAttachmentsBODResponseFieldNameMapping section. This postprocessor, does a sub search query to retrieve the catalog entry associated assets. It uses the IBM_findCatalogEntryAssociatedAssets search profile.
SolrRESTSearchCatalogEntryViewComponentsQueryPostprocessor
Reformat the Solr response into a structured object. It populates the Components list into the catalogEntryView part of the response. The mapping configuration is defined in wc-component.xml file under the XPathToComponentsBODResponseFieldNameMapping section. This postprocessor, does a sub search query to retrieve the catalog entry associated components. It uses the IBM_findCatalogEntryComponentssearch profile.
SolrRESTSearchCatalogEntryViewDynamicKitQueryPostprocessor
Reformat the Solr response into a structured object. It populates the Dynamic Kit configuration information into the catalogEntryView part of the response. It issues a cached DB query to retrieve the Configuration information from the DB. It uses the IBM_GET_STERLING_CONFIGURATOR_METADATA_BY_STORE_ID query template that is defined in the wc-query-utilities.tpl file.
SolrRESTSearchCatalogEntryViewMerchandisingAssocQueryPostprocessor
Reformat the Solr response into a structured object. It populates the merchandisingAssociationslist into the catalogEntryView part of the response. The mapping configuration is defined in wc-component.xml file under the XPathToMerchandisingAssociationsBODResponseFieldNameMapping section. This post processor issues a database query to retrieve catalog entry associated merchandising identifiers, then does a sub search query to retrieve the actual associated merchandising details. It uses the IBM_findCatalogEntryAssociatedMerchandising search profile and the IBM_GET_MERCHANDISING_ASSOCIATIONS_BY_CATALOG_ENTRY_ID query template that is defined in the wc-query-utilities.tpl file.
SolrRESTSearchBrandSuggestionQueryPostprocessor
A Solr specific implementation of the search query postprocessor for handling brand suggestion.
SolrRESTSearchCategorySuggestionQueryPostprocessor
A Solr specific implementation of the search query postprocessor for handling category suggestion.
SolrRESTSearchPreviewQueryPostprocessor
A Solr specific implementation of the search query postprocessor for handling preview context.
SolrRESTSearchExperimentQueryPostprocessor
A Solr specific implementation of the search query postprocessor for handling search rule experiment metadata.
SolrRESTSearchFacetQueryPostprocessor
Attach facet-related response into more user-friendly data.
SolrRESTSearchChildCategoryEntitlementQueryPostprocessor
Remove unentitled child catgroupId from the solrDocumentList in the response.
SolrRESTSearchCategoryEntitlementQueryPostprocessor
Remove unentitled sub category SolrDocument from the solrDocumentList in the response.
SolrRESTSearchEntitlementQueryPostprocessor
Put catgroup_id_search facet information into the SearchResponse.
SolrRESTSearchBreadCrumbTrailQueryPostprocessor
Generate the breadcrumb trail.
SolrRESTSearchSpellCheckSuggestionQueryPostprocessor
Reformat the Solr spell correction feedback into a more user-friendly list of keywords.
Feature Pack 8SolrRESTSearchCatalogGroupViewUserDataQueryPostprocessor
Feature Pack 8Add custom index fields to the search response for category view resource.
Feature Pack 8SolrRESTSearchResultGroupingQueryPostprocessor
Feature Pack 8A Solr specific implementation of the search query postprocessor for handling result grouping configurations.
Sort The sort section is for defining sorting options and their corresponding values that can be used directly from the storefront.
For example:

<_config:sort>
<_config:field name="1" value="mfName_ntk_cs asc" />
<_config:field name="2" value="name_ntk asc,price_* asc" />
</_config:sort> 
Where, when a value of 2 is passed in through a control parameter _wcf.search.sort, the following two parameters are added to the final Solr expression:

sort=name_ntk+asc,price_USD+asc 
Note: price_* contains a * operator that is substituted with the shopper's currency at run time. In the example, the shopper's currency is USD.
Result Declares a list of search index fields to return in the search result set. You can apply more data filtering.
Highlight Declares a list of search index fields to be used for highlighting and their associated highlighting behavior at run time.
Facets Declares a list of search index fields to be used for faceting and their associated faceting behavior at run time.
It contains the following parameters:
sort
Determines the ordering of the facet field constraints:
count
Sort the constraints by count (highest count first). The default value.
index
Return the constraints that are sorted in their index order (lexicographic by indexed term). For terms in the ASCII range, this is alphabetically sorted.
minCount
Indicates the minimum counts for facet fields to include in the response. The default value is 1.
limit
Indicates the maximum number of constraint counts to return for the facet fields. A negative value denotes unlimited. The default value is 200.
Note: The MAX_DISPLAY column of the FACET table overrides this limit by default in the storefront.
Spellcheck Defines the spell checking behavior at run time.
It contains the following parameter:
limit
Indicates the maximum number of suggestions to return. The default value is 5.
navigationSuggestion Defines the suggested brands, categories, and articles behavior at run time.
Articles contains the following parameter:
totalNumber
The number of cached web content articles to return. The default value is 100.
group Defines the search result grouping behavior at run time.
group
Specifies whether search result grouping is enabled. The default value is false.
group.limit
Specifies the maximum number of search results per group. The default value is 100.
group.ngroups
Specifies whether the number of groups to return as part of the response. The default value is false.
heroproduct Defines representative grouping product behavior at run time. This property applies when search result grouping is enabled.
overrideFieldName
A comma-separated list of Solr field names. When specified, some properties of the most relevant item in the group override the returned productBean properties. For example, thumbnail or name. The default value is thumbnail.
showGroupPriceRange
When set to true, the returned productBean price displays a price range based on the underlying SKUs that generated the search hits. The default value is false.
relevancy
joinFilterQuery
Indicates whether to use filter or boost options.
false
Enables boost. Products within the category that contains the shopper's search query are boosted, followed by other categories. This is the default value.
true
Enables filtering. Products within the category that contains the shopper's search query are returned. No other results are returned.
CatalogGroupSearchFields
keyword
The field of the CatalogGroup index is searched using the join query by default. You can add more indexed fields of the CatalogGroup in this parameter. By default, the keyword field of the CatalogGroup index is searched to find the possible category containing the searched products. You can add more indexed fields of the CatalogGroup in this parameter to increase the search scope. The possible fields are: name, shortDescription, longDescription, and keyword fields.
You can overwrite the default parameter values in the extended wc-search.xml file.

<_config:profile name="IBM_findProductsBySearchTerm" indexName="CatalogEntry">
   <_config:join>
      <_config:param name="joinFilterQuery" value = "true" />
      <_config:param name="CatalogGroupSearchFields" value="keyword, name" />
   </_config:join>
</_config:profile>

<_config:profile name="IBM_findProductsBySearchTerm_grouping" extends="IBM_findProductsBySearchTerm">
<_config:profile name="IBM_findProductsByNameOnly" extends="IBM_findProductsBySearchTerm">
<_config:profile name="IBM_findProductsByNameAndShortDescriptionOnly" extends="IBM_findProductsBySearchTerm">
<_config:profile name="IBM_findProductsByUnstructureOnly" extends="IBM_findProductsBySearchTerm">
As shown in the above snippet, you must include all other profiles that extend the IBM_findProductsBySearchTerm profile.

Inheritance

Similar to Java inheritance, search profile properties are inheritable. Parent properties can be either overridden or extended by its child:
Overridden
All associated elements within a given property of its parent are discarded and only the properties that are specified by the child are used instead. For example, <_config:query> or <_config:query inherits="false">.
Extended
All associated elements within a given property of its parent are passed down to its child, along with other additional properties specified by the child. For example, <_config:query inherits="true"> .
Note: Properties from the child are always processed last and therefore achieve the behavior of inheritance. In situations where sequencing of properties is necessary, properties of the parent always come before the child. If this behavior is not desired, the child can override this behavior by specifying all of its parent properties along with its own, in an order that is needed.

Overriding the extended configuration

All associated elements within a given property of its parent are passed down to its child, except for those being overridden by its child.

For example:

<_config:query inherits="true" override="field">
<_config:field name="name"/>
</_config:query>
Where the query field is the only configuration being overridden in the child profile. However, the other query configurations such as parameter, provider, preprocessor, postprocessor are being inherited from the parent profile. The override accepts a comma separated list of query configurations.
Note: This behavior only applies to the query field configuration elements.