Catalog storefront services

The search interface can be used for retrieving information for catalog entries or performing searches. The sample catalog programming model provides a consistent service-oriented architecture (SOA) based programming model for WebSphere Commerce storefronts. It uses the WebSphere Commerce Search framework and the CatalogNavigationView search noun to move storefront catalog services from beans and service-oriented integration (SOI) to SOA.

Note: As the catalog programming model uses the WebSphere Commerce Search framework, search-based navigation must be enabled in starter stores to use the SOA services.

WebSphere Commerce Search as a search tool

WebSphere Commerce Search uses Apache Solr as a search tool, leveraging common search engine functionality in starter stores. The following list shows search engine functionality in starter stores:
  • Auto-suggest menus for suggested keywords, categories, brands, site content, and search history.
  • Auto-suggest lists for keywords.
  • Automatic search term suggestions and spelling corrections.
  • Search term highlighting.
  • Structured and unstructured content in search results.
  • Wildcard searching.

WebSphere Commerce Search as a data store for the storefront

WebSphere Commerce uses Apache Solr as a data store, leveraging catalog filtering and product display pages in starter stores to browse for products (search-based navigation). This approach provides the following benefits:
  • It is faster than using a database, delivering performance gains.
  • It can run on servers other than WebSphere Commerce, balancing the workload.
The result is better performance with no additional licensing costs.

Search-based navigation enhances starter stores by triggering results when a shopper browses a storefront catalog. All immediate categories and products are returned in the results, and can also include its subcategories to increase its scope. With search-based navigation enabled, the storefront benefits include improved search performance and accuracy, search rules, and faceted navigation. As a result, the storefront delivers a perception of a personalized browsing experience in starter stores.

These additional capabilities in the storefront exist as part of the WebSphere Commerce Search framework to influence starter store search results. These capabilities include:
  • Search term associations.
  • Search-based merchandising rules.
  • Starter stores integration by default.

The Catalog navigation noun that is used with the storefront Catalog service is called the CatalogNavigationView. This noun represents a business response of a catalog browsing request. It contains a list of subproducts, called CatalogEntryView, and a list of subcategories, called CatalogGroupView.

Shoppers can navigate the storefront catalog in the following ways:
  • Quick search
  • Category-based navigation
  • Faceted navigation
  • Advanced search
The following catalog entry-related data beans are moved to SOA services:
  • CatalogEntryDataBean
  • ProductDataBean
  • PackageDataBean
  • DynamicKitDataBean
  • BundleDataBean
  • ItemDataBean
Moving catalog entry-related data beans to SOA services results in a consistent programming model across the Catalog component, and simplifies storefront development, since a single noun can be used for accessing all catalog data.
Note: The CatalogEntry, CatalogGroup and Catalog nouns are used for administrative purposes, while the CatalogNavigationView noun is used in the storefront.

Catalog service overview

The product display page uses the getData tag and calls the catalog service. As WebSphere Commerce Search is used to retrieve data, some of the information for the catalog entry is retrieved from the search engine and other information from the WebSphere Commerce database. The CatalogNavigationView noun is populated with data from both sources and returned in the service response. That data is then used to populate the product display page in the storefront.

The following diagram shows how the CatalogNavigationView noun works with the storefront:
Overview of catalog service

Each element in the noun either comes from the search index or the database. Access profiles determine what information comes from the database, while search profiles determine what information comes from the index.

The following elements come from the database:
  • Price
  • Components
  • MerchandisingAssociations
  • Attributes
  • DynamicKitURL
  • DynamicKitDefaultConfiguration
  • DynamicKitDefaultConfigurationComplete
  • DynamicKitModelReference
  • Title
  • MetaDescription
  • MetaKeyword
  • FullImageAltDescription
The following elements can come from the index or the database:
  • Price
  • MetaData
  • UserData
Note:
  • Where Price data comes from depends on which price display mode is selected in the wc-search.xml file.
  • MetaData is used internally.
  • UserData is for you to perform customization.

All other elements come from the search index, where elements are added to the noun by either a mediator or results filters. Various filters are defined in the search profiles in the wc-search.xml file that pull in the extra data that is required by the product display page. The results filters use a combination of index queries, command calls, and service calls to add data to the new noun elements. When possible, the results filters use search profiles to retrieve the required information from the index or database. These profiles can then be modified to return additional information with no code changes.

Implementation overview

The CatalogNavigationView noun is implemented by using the BOD Programming model and uses the same implementation concepts.

Access profiles and search profiles

Access profiles are associated with a search profile so you can specify only an access profile with the XPath query. However, you can still specify a search profile on the expression builder definition or the getData call in the JSP files to override the associated search profile. For example:

<wcf:getData type="com.ibm.commerce.catalog.facade.datatypes.CatalogNavigationViewType" var="catalogNavigationView"
             expressionBuilder="getCatalogEntryViewDetailsByID" varShowVerb="showCatalogNavigationView" scope="request">
     <wcf:param name="UniqueID" value="${catEntryID}" />
     <wcf:contextData name="storeId" data="${WCParam.storeId}" />
     <wcf:contextData name="catalogId" data="${WCParam.catalogId}" />
     <wcf:param name="searchProfile" value="MySearchProfile"/>
</wcf:getData>
The access profile provides access control and determines what information is comes from the database. The associated search profile controls information that comes from the search index. The following element is added to the wc-component.xml file, where the access profile and search profile can be linked:

<_config:configgrouping name="AccessProfileToSearchProfileMapping">
     <_config:property name="IBM_Store_Summary" value="IBM_findCatalogEntrySummary"/>
     <_config:property name="IBM_Store_Details" value="IBM_findCatalogEntryDetails"/>
     <_config:property name="IBM_Store_CatalogEntryAttachments" value="IBM_findCatalogEntryAttachments"/>
     <_config:property name="IBM_Store_CatalogEntryDetailsWithAttachments" 
       value="IBM_findCatalogEntryDetailsWithAttachments"/>
     <_config:property name="IBM_Store_CatalogEntryDetailsWithComponentsAndAttachments" 
       value="IBM_findCatalogEntryDetailsWithComponentsAndAttachments"/>
     <_config:property name="IBM_Store_CatalogEntryDetailsWithMerchandisingAssociations" 
       value="IBM_findCatalogEntryDetailsWithMerchandisingAssocDetails"/>
     <_config:property name="IBM_Store_CatalogEntryPrice" value="IBM_findCatalogEntryPrice"/>
     <_config:property name="IBM_Store_CatalogEntryPriceWithAttributes" 
       value="IBM_findCatalogEntryPriceWithAttributes"/>
     <_config:property name="IBM_Store_All" value="IBM_findCatalogEntryAll"/>
</_config:configgrouping>

Access profiles returned fields

The following table describes the access profiles and the respective fields returned by each profile.
Access profiles and returned fields
Access profile Returned fields
IBM_Store_Summary Catalog entries:
  • catalogEntryTypeCode
  • buyable
  • UniqueID
  • PartNumber
  • Name
  • ThumbNail
  • FullImage
  • ManufacturerName
  • ShortDescription
  • LongDescription
  • StoreID
  • Keyword
  • Title
  • MetaDesc
  • MetaKeyword
  • FullImageAltDescription
  • MetaData
  • UserData
Catalog groups:
  • UniqueID
  • Identifier
  • Name
  • ThumbNail
  • ShortDescription
  • MetaData
  • UserData
IBM_Store_Details

Catalog entries:

IBM_Store_Summary +

  • disallowRecurringOrder
  • SubscriptionTypeCode
  • Price
  • ParentCatalogGroupID
  • ParentCatalogEntryID
  • hasSingleSku
  • SingleSKUCatalogEntryID
  • NumberOfSKUs
  • SKUs
  • Attributes

Catalog groups:

IBM_Store_Summary +
  • LongDescription
  • FullImage
  • Title
  • MetaDescription
  • MetaKeyword
  • FullImageAltDescription
IBM_Store_CatalogEntryDetailsWithAttachments IBM_Store_Details +
  • Attachments
IBM_Store_CatalogEntryDetailsWithComponentsAndAttachments IBM_Store_CatalogEntryDetailsWithAttachments +
  • Components
  • DynamicKitURL
  • DynamicKitDefaultConfiguration
  • dynamicKitDefaultConfigurationComplete
IBM_Store_CatalogEntryDetailsWithMerchandisingAssociations IBM_Store_Details +
  • MerchandisingAssociations
IBM_Store_All IBM_Store_CatalogEntryDetailsWithComponentsAndAttachments +
  • MerchandisingAssociations
IBM_Store_CatalogEntryAttachments
  • UniqueID
  • Attachments
IBM_Store_CatalogEntryPrice
  • catalogEntryTypeCode
  • UniqueID
  • Price
IBM_findCatalogEntryPriceWithAttributes IBM_Store_CatalogEntryPrice +
  • buyable
  • StoreID
  • PartNumber
  • Name
  • ThumbNail
  • ManufacturerName
  • ShortDescription
  • Attributes

Access profiles and their corresponding search profiles

The following table shows access profiles and the corresponding search profile that are defined in the wc-search.xml file. The queries use the explicit UniqueID or PartNumber that is passed in on the XPath for the search.
Search profile mapping
Access profile Search profile
IBM_Store_Summary IBM_findCatalogEntrySummary
IBM_Store_Details IBM_findCatalogEntryDetails
IBM_Store_CatalogEntryDetailsWithAttachments IBM_findCatalogEntryDetailsWithAttachments
IBM_Store_CatalogEntryDetailsWithComponentsAndAttachments IBM_findCatalogEntryDetailsWithComponentsAndAttachments
IBM_Store_CatalogEntryDetailsWithMerchandisingAssociations IBM_findCatalogEntryDetailsWithMerchandisingAssocDetails
IBM_Store_All IBM_findCatalogEntryAll
IBM_Store_CatalogEntryAttachments IBM_findCatalogEntryAttachments
IBM_Store_CatalogEntryPrice IBM_findCatalogEntryPrice
IBM_Store_CatalogEntryPriceWithAttributes IBM_findCatalogEntryPriceWithAttributes

Search profile inheritance

The following table depicts the search profile inheritance for the catalog programming model:
Search profile inheritance
Search profile Extends from
IBM_findCatalogEntrySummary
IBM_findCatalogEntryDetails IBM_findCatalogEntrySummary
IBM_findCatalogEntryDetailsWithAttachments IBM_findCatalogEntryDetails
IBM_findCatalogEntryDetailsWithComponentsAndAttachments IBM_findCatalogEntryDetailsWithAttachments
IBM_findCatalogEntryDetailsWithMerchandisingAssocDetails IBM_findCatalogEntryDetails
IBM_findCatalogEntryAll IBM_findCatalogEntryDetailsWithComponentsAndAttachments
IBM_findCatalogEntryAttachments
IBM_findCatalogEntryPrice
IBM_findCatalogEntryPriceWithAttributes IBM_findCatalogEntryPrice
IBM_findCatalogGroupSummary
IBM_findCatalogGroupDetails IBM_findCatalogGroupSummary
The following code sample shows the IBM_findCatalogEntrySummary search profile.

<!-- Search profile for IBM_findCatalogEntrySummary-->
  <_config:profile indexName="CatalogEntry" name="IBM_findCatalogEntrySummary">
    <_config:query>
      <_config:param name="debug" value="false"/>
      <_config:param name="maxRows" value="50"/>
      <_config:param name="maxTimeAllowed" value="5000"/>
      <_config:provider classname="com.ibm.commerce.catalog.facade.server.services.search.expression.solr.SolrSearchProfileNameValidator"/>
      <_config:provider classname="com.ibm.commerce.catalog.facade.server.services.search.expression.solr.SolrSearchIndexNameValidator"/>
      <_config:provider classname="com.ibm.commerce.catalog.facade.server.services.search.expression.solr.SolrSearchIndexSynchronizer"/>
      <_config:provider classname="com.ibm.commerce.catalog.facade.server.services.search.expression.solr.SolrSearchByStorePathExpressionProvider"/>
       <_config:provider classname="com.ibm.commerce.catalog.facade.server.services.search.expression.solr.SolrSearchByPublishedEntryOnlyExpressionProvider"/>
       <_config:provider classname="com.ibm.commerce.catalog.facade.server.services.search.expression.solr.SolrSearchProductEntitlementExpressionProvider"/>
        <_config:provider classname="com.ibm.commerce.catalog.facade.server.services.search.expression.solr.SolrSearchByCustomExpressionProvider"/>
      <_config:provider classname="com.ibm.commerce.catalog.facade.server.services.search.expression.solr.SolrSearchExpressionValidator"/>
    </_config:query>
    <_config:result>
      <_config:field name="catentry_id"/>
      <_config:field name="storeent_id"/>
      <_config:field name="buyable"/>
      <_config:field name="partNumber_ntk"/>
      <_config:field name="name"/>
      <_config:field name="thumbnail"/>
      <_config:field name="fullImage"/>
      <_config:field name="shortDescription"/>
      <_config:field name="longDescription"/>
      <_config:field name="keyword"/>
      <_config:field name="mfName_ntk"/>
      <_config:field name="catenttype_id_ntk_cs"/>
    </_config:result>
</_config:profile>

Expression builders

The UniqueIDsExpressionBuilder class is modified to support the searchProfile parameter, which can be passed in addition to the access profile. The search data mediator is modified to extract and add the UniqueID to the search query. One expression builder is created for each access profile and for both catentryID and partNumber.

Expression builders and associated access profiles
Expression builder Access profile
getCatalogEntryViewSummaryByID IBM_Store_Summary
getCatalogEntryViewSummaryByPartnumber IBM_Store_Summary
getCatalogEntryViewDetailsByID IBM_Store_Details
getCatalogEntryViewDetailsByPartnumber IBM_Store_Details
getCatalogEntryViewAttachmentsByID IBM_Store_CatalogEntryAttachments
getCatalogEntryViewAttachmentsByPartnumber IBM_Store_CatalogEntryAttachments
getCatalogEntryViewPriceByID IBM_Store_CatalogEntryPrice
getCatalogEntryViewPriceByPartnumber IBM_Store_CatalogEntryPrice
getCatalogEntryViewPriceWithAttributesByID IBM_Store_CatalogEntryPriceWithAttributes
getCatalogEntryViewPriceWithAttributesByPartnumber IBM_Store_CatalogEntryPriceWithAttributes
getCatalogEntryViewDetailsWithAttachmentsByID IBM_Store_CatalogEntryDetailsWithAttachments
getCatalogEntryViewDetailsWithAttachmentsByPartnumber IBM_Store_CatalogEntryDetailsWithAttachments
getCatalogEntryViewDetailsWithComponentsAndAttachmentsByID IBM_Store_CatalogEntryDetailsWithComponentsAndAttachments
getCatalogEntryViewDetailsWithComponentsAndAttachmentsByPartnumber IBM_Store_CatalogEntryDetailsWithComponentsAndAttachments
getCatalogEntryViewDetailsWithMerchandisingAssociationsByID IBM_Store_CatalogEntryDetailsWithMerchandisingAssociations
getCatalogEntryViewDetailsWithMerchandisingAssociationsByPartnumber IBM_Store_CatalogEntryDetailsWithMerchandisingAssociations
getCatalogEntryViewAllByID IBM_Store_All
getCatalogEntryViewAllByPartnumber IBM_Store_All
getCatalogNavigationCatalogGroupView IBM_Store_Summary
getCatalogNavigationCatalogGroupViewByIdentifier IBM_Store_Summary
getCatalogNavigationCatalogGroupViewByCatalogId IBM_Store_Summary
getCatalogNavigationCatalogGroupViewByParentCatalogGroup IBM_Store_Summary
getCatalogEntryViewSummaryByID expression builder

<expression-builder>
  <name>getCatalogEntryViewSummaryByID</name>
  <data-type-name>CatalogNavigationView</data-type-name>
  <class>com.ibm.commerce.foundation.internal.client.taglib.util.UniqueIDsExpressionBuilder</class>
  <method>formatExpression</method>
  <param>
      <name>template</name>
      <value>/CatalogNavigationView[CatalogEntryView[(UniqueID=)]]</value>
  </param>
  <param>
      <name>accessProfile</name>
      <value>IBM_Store_Summary</value>
  </param>
</expression-builder>

XPath expression

The XPath for catalog entries is /CatalogNavigationView[CatalogEntryView[ParentCatalogGroupID= and (catalogEntryTypeCode=)]]

The XPaths for catalog groups are:
  • /CatalogNavigationView[CatalogGroupView[(UniqueID=)]]
  • /CatalogNavigationView[CatalogGroupView[(Identifier=)]]
  • /CatalogNavigationView/CatalogGroupView
  • /CatalogNavigationView[CatalogGroupView[(ParentCatalogGroupID=)]]
The CatalogNavigationView noun XPath is extended to support returning results for one or more catalog entries by catalog entry ID and part number:
  • /CatalogNavigationView[CatalogEntryView[(UniqueID=)]]
  • /CatalogNavigationView[CatalogEntryView[(PartNumber=)]]
The XPath to Solr search query mappings are defined in the wc-search.xml file.
<_config:queryMapping indexName='CatalogEntry'
     xpathKey='/CatalogNavigationView[CatalogEntryView[(UniqueID=)]]'
     searchQuery='catentry_id:(?UniqueID?)'/>

<_config:queryMapping indexName='CatalogEntry'
     xpathKey='/CatalogNavigationView[CatalogEntryView[(PartNumber=)]]'
     searchQuery='partNumber_ntk:(?PartNumber?)'/>


<_config:queryMapping indexName="CatalogEntry"
        searchQuery="parentCatgroup_id_search:?ParentCatalogGroupID?  AND catenttype_id_ntk_cs:(?catalogEntryTypeCode?)
      " xpathKey="/CatalogNavigationView[CatalogEntryView[ParentCatalogGroupID= and (catalogEntryTypeCode=)]]"/>

    <_config:queryMapping indexName="CatalogGroup"
        searchQuery="catgroup_id:(?UniqueID?)" xpathKey="/CatalogNavigationView[CatalogGroupView[(UniqueID=)]]"/>

  <_config:queryMapping indexName="CatalogGroup"
        searchQuery="identifier_ntk:(?Identifier?)" xpathKey="/CatalogNavigationView[CatalogGroupView[(Identifier=)]]"/>

    <_config:queryMapping indexName="CatalogGroup"
        searchQuery="parentCatgroup_id_facet:*_-1" xpathKey="/CatalogNavigationView/CatalogGroupView"/>

    <_config:queryMapping indexName="CatalogGroup"
        searchQuery="parentCatgroup_id_facet:(*_?ParentCatalogGroupID?)" 
        xpathKey="/CatalogNavigationView[CatalogGroupView[(ParentCatalogGroupID=)]]
      " queryComposer="com.ibm.commerce.foundation.internal.server.services.search.processor.solr.SolrSearchQueryContainingAsteriskComposer"/>

The current control parameter for access control (_wcf.ap) is used to control access and details returned.

Search index changes

To support the new noun, the following changes are made to the catalog entry search index:

<field name="longDescription" type="string" indexed="false" stored="true"  multiValued="false"/>
<field name="keyword" type="wc_text" indexed="true" stored="false"  multiValued="false"/>
<field name="disallowRecOrder" type="int" indexed="false" stored="true" multiValued="false"/>
<field name="subscripType" type="string" indexed="false" stored="true" multiValued="false"/>


<field name="parentCatgroup_id_facet" type="wc_keywordText" indexed="true" stored="true" multiValued="true"/>
<field name="sequence" type="wc_keywordText" indexed="true" stored="true" multiValued="true" />
To support the new noun, the unstructured content index indexes all attachments and are sorted according to the attachment relationship sequence number. That is, instead of sorting by relationship ID. The rulename element is mapped to attachment Usage:

<_config:mediator-property name="CatalogEntryView/Attachments/Usage" value="rulename" />