HCL Commerce Search configuration file (wc-search.xml)

The HCL Commerce Search configuration file (wc-search.xml) contains properties that are related to configuring HCL 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 HCL Commerce Search configuration file consists of four sections:
  • Server - Defines how to connect to the search server. Do not modify.
    Note: Use the embedded mode for the search server. That is, do not use the Advanced Configuration for the Search server, as it uses an extra web container thread to perform search, which is inefficient.
  • Index - Defines the associated properties of the search index. 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 HCL Commerce Search configuration files are stored in the following locations by default:
  • The default HCL Commerce Search configuration file for the search application: Search_home/resources/search/runtime/config/com.ibm.commerce.search
  • The extended HCL Commerce Search configuration file for the search application. To change the value of an existing property in the HCL 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: workspace_dir/search-config-ext/src/runtime/config/com.ibm.commerce.search/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.
wc-search.xml configurable properties
Property Description
Profile A search profile is a logical grouping unit of different configurations and implementations, which construct the final search query and format the response.

For a complete list of default search profiles, see HCL 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).

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.
Required expression providers. These providers cannot be customized or reconfigured.
SearchProfileNameValidator
A 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.
SearchIndexNameValidator
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 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.
SearchExpressionValidator
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:
SearchBasedMerchandisingExpressionProvider
A 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 more constraints to the search request to influence the order of the results. They can also 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.
SearchByCategoryExpressionProvider
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.

SearchByManufacturerExpressionProvider
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.
SearchByPriceExpressionProvider
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.
SearchByFacetExpressionProvider
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.
SearchByStorePathExpressionProvider
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.
SearchByPublishedEntryOnlyExpressionProvider
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.
SearchByCustomExpressionProvider
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.
SearchFacetConditionExpressionProvider
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.
SearchTypeExpressionProvider
This search expression provider handles the match type for keyword search requests. The following pseudo logic describes how the match type (_wcf.search.type) can be converted into a search criteria:
  1. Match type defaults to ANY, exclude SKU.
  2. Exclude SKU expression is represented as -catenttype_id_ntk_cs:ItemBean.
  3. Only SKU expression is represented as - +catenttype_id_ntk_cs:ItemBean.
  4. Include SKU expression does not need to be qualified.
The resulting Solr expression is added back into the SelectionCriteria object (_wcf.search.internal.filterquery) for other downstream processing.
SearchProductSequencingExpressionProvider
Orders product entries in the search result by ranking.
SearchCategorySequencingExpressionProvider
Sorts categories by ranking.
SearchTermAssociationExpressionProvider
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.
SearchProductEntitlementExpressionProvider
Performs product entitlement. It is run 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 no contracts are passed as parameters, 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.
SearchCategoryEntitlementExpressionProvider
Performs catalog group-level entitlement by triggering a search on the Catalog Entry core. Next, it parses 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.
SearchByKeywordRelevancyExpressionProvider
Handles the search by keyword request.
SearchInventoryExpressionProvider
Handles searches for the inventory search index.
SearchByIdentifierExpressionProvider
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.
SearchWebContentStoreInfoExpressionProvider
A 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.
SearchByJoinQueryExpressionProvider
A 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 by using the _wcf.search.internal.filterquery control parameter.
Postprocessors:
MainCatalogEntryViewResultQueryPostprocessor
Reformat the Solr response into a structured object. The mapping configuration is defined in wc-component.xml file under the XPathToCatalogEntryFieldNameMapping section.
MainCatalogGroupViewResultQueryPostprocessor
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.
MainWebContentViewResultQueryPostprocessor
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.
MainCatalogEntryViewResultQueryPostprocessor
This search query postprocessor populates the catalogEntryView part of the response.
SearchCatalogEntryViewPriceQueryPostprocessor
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.
SearchCatalogEntryViewDescriptionQueryPostprocessor
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.
SearchCatalogEntryViewSKUQueryPostprocessor
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.
SearchCatalogEntryViewAttributesQueryPostprocessor
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.
SearchCatalogEntryViewAttachmentsQueryPostprocessor
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.
SearchCatalogEntryViewComponentsQueryPostprocessor
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.
SearchCatalogEntryViewMerchandisingAssocQueryPostprocessor
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.
SearchBrandSuggestionQueryPostprocessor
A search query postprocessor for handling brand suggestion.
SearchCategorySuggestionQueryPostprocessor
A search query postprocessor for handling category suggestion.
SearchPreviewQueryPostprocessor
A search query postprocessor for handling preview context.
SearchExperimentQueryPostprocessor
A search query postprocessor for handling search rule experiment metadata.
SearchFacetQueryPostprocessor
Attach facet-related response into data.
SearchChildCategoryEntitlementQueryPostprocessor
Remove unentitled child catgroupId from the solrDocumentList in the response.
SearchCategoryEntitlementQueryPostprocessor
Remove unentitled sub category SolrDocument from the solrDocumentList in the response.
SearchEntitlementQueryPostprocessor
Put catgroup_id_search facet information into the SearchResponse.
SearchBreadCrumbTrailQueryPostprocessor
Generate the breadcrumb trail.
SearchSpellCheckSuggestionQueryPostprocessor
Reformat the Solr spell correction feedback into a more readable list of keywords.
SearchCatalogGroupViewUserDataQueryPostprocessor
Add custom index fields to the search response for category view resource.
SearchRelevancyByProductGroupingPostprocessor
A search query postprocessor for handling result grouping configurations.
SearchCatalogEntryViewVariantAndSKUQueryPostprocessor

Reformat the Solr response into a structured object. It populates the variants and SKUs list into the catalogEntryView part of the response. The mapping configuration is defined in the wc-component.xml file under the XPathToCatalogEntryViewBODResponseFieldNameMapping section. This postprocessor does a sub-search query to retrieve the catalog entry associated items (variants and SKUs). It uses the IBM_findCatalogEntrySKUs and IBM_findCatalogEntrySKUsByVariantIds search profile.
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 list 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 100.
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.
group Defines the search result grouping behavior at run time.
group
Specifies whether search result grouping is enabled. The default value is false.

You can add more grouping parameters by using the same group.parameter_name convention. For more information about grouping parameters, see the Apache 5.5 Reference Guide.

group.limit
Specifies the maximum number of search results per group. The default value is 100.
field
The field name to group by. This value must be defined as the last entry of the group configuration.
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.
QueryMissingGroupOwner
Fetches missing group owners from the index. It is run in a batch for all groups for the current page size. The default value is true.
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
Indicates that the field of the CatalogGroup index is searched with 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 that contains 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>