Although Microsoft Commerce Server 2009's architecture is built upon Microsoft SQL Server, and has the full power of the SQL Full Text Indexing Search Platform, there are time however when you may require a richer or alternate search platform. One of these scenarios if when you want
to implement a faceted (refinement) search into your site, which provides dynamic refinements based on the search results dataset.
Faceted search is becoming popular in most online retail environments as a way of providing an enhanced user experience when browsing a larger catalogue. This is powerful for two reasons, firstly with a traditional search it is down
to a user
to think of a search term suitable for the product they are trying
to find. This typically will not return similar products or help in any way
to refine a larger dataset. Faceted searches on the other hand provide a comprehensive list of product properties, grouped together by similarity
to help the user narrow down the results returned, as the user progressively restricts the search criteria by selecting additional criteria
to search again, these facets needs
to continually refresh. The whole experience allows users
to explore alternate brands, price-ranges, or find products they hadn't initially thought of or where looking for in a bid
to enhance cross sell in the retail environment.
The second advantage of this type of search from a business perspective is also
to harvest the search result
to start
to profile your user. Even though anonymous users may routinely visit your site, and will not necessarily register or complete a transaction
to build up marketing data- profiling, you can still achieve the same result by recording search facets used within the search sequence. Below is a faceted search scenario generated from eBay using the search term "server". By creating a search profile of clicking through Computer & Networking -> Servers -> Dell - > New and recording this information against my user profile you can start
to predict with a lot more certainty what types of products I am interested in. This will allow you
to apply shopping-cart analysis against your search data and provide great cross-sale or advertising opportunity, or personalise the user experience based on your prediction of what the user may be interested in.
This type of search is extremely beneficial in e-Commerce environments but achieving it out of the box with Commerce Server and SQL Full Text indexing can be challenging. In many deployments it is often easier
to use an alternate search platform such as Microsoft's FAST,
Apache SOLR, or Endecca, however you still want these products
to integrate natively into Commerce Server
to ensure that up-to-date inventory information is presented, profile information is generated, and you provide a consistant API.
To do so we make the most of the Commerce Server extensibilty points called operation sequence components.
In this example I will be talking about Apache Solr hosted on Apache Tomcat, in this specific example I have used the SolrNet C# library
to interface
to the Java platform. Also I am not going
to talk about Solr configuration of indexing – but in a
production envionrment this would typically happen by using Powershell
to call the Commerce Server management webservice
to export your catalog as XML, apply an XSLT transform
to the file
to make it conform
to SOLR and use a simple HTTP Post
to send it
to the search enginge for indexing.
Essentially a sequance component is a step in a serial workflow used
to call a data repository (which in most cases is usually the Commerce Server pipelines or databases) and map
to and from a Commerce Entity object whilst enforcing any business rules. So the first step in the process is
to add a new class library
to your existing Commerce Server site. You will need
to use a new library as Sequence Components will need
to be strongly named
to be deployed.
Once you are inside of your new project, add a new class file and add a reference
to the Microsoft.Commerce.Providers, Microsoft.Commerce.Contracts and the Microsoft.Commerce.Broker assemblies. Now make your new class derive from the base object Microsoft.Commerce.Providers.Components.OperationSequanceComponent and overide the ExecuteQueryMethod. Your screen will then look something similar ot this:
As all we are doing on this component is conducting a search we are only interested in the ExecuteQuery method. This method accepts three arguments, queryOperation, operationCache, and response. The queryOperation will be the object in which we receive our search parameters, the cache allows access
to the Commerce Server cache allowing us
to store regulary accessed information, and the response object is the object which we will return the result of our search upon. Inside this method is simply where we are going
to inject our logic for our third party search platform. As I am not going
to explain the inner-workings of actually making a SOLR call, I'll simply provide the sample code here. I would highly recommend however looking at the SolrNet wiki as they have some great explinations of how the API works.
What you will find however is that there are some further extensions required when attempting
to integrate a custom search provider. Firstly you out of the box the CommerceQueryOperation you will receive into the method when conducting a search against a catalog is specifically geared towards a SQL Full Text Search with properties such as a Where clause.
To make the operation you receive more relevant you will need
to create another class, this time derived from Microsoft.Commerce.Contract.Messages.CommerceSearchCriteria and within this you need
to detail the properties you will require
to allow you
to submit as parameters
to the SOLR search API. My exmaple looks like this:
[DataContract(Namespace = "http://schemas.microsoft.com/microsoft-multi-channel-commerce-foundation/types/2008/03")]
public
class
CommerceCatalogSolrSearch : CommerceSearchCriteria
{
private
Dictionary<string, string> _facetQueries;
public CommerceCatalogSolrSearch()
{
_facetQueries = new
Dictionary<String, String>();
}
public
Dictionary<String, String> FacetQueries
{
get { return _facetQueries; }
set { _facetQueries = value; }
}
public
String SearchPhrase{ get; set; }
public
int PageIndex { get; set; }
public
int PageSize { get; set; }
public
IEnumerable<String> Facets { get; set; }
public
string Sort { get; set; }
public
new
int FirstItemIndex
{
get
{
return (PageIndex-1)*PageSize;
}
}
public
int LastItemIndex
{
get
{
return FirstItemIndex + PageSize;
}
}
}
To allow you
to construct a CommerceQueryOperation call within the API you will also need
to construct another class
to derived from Microsoft.Commerce.Common.MessageBuilders.CommerceSearchCriteriaBuilder and is simply used
to construct an instance of the CommerceQueryOperation you have just created and expose the properties you want set. My Message builder looks like this:
public
class
CommerceCatalogSolrSearchBuilder : CommerceSearchCriteriaBuilder
{
private CommerceCatalogSolrSearch _solrSearch;
public CommerceCatalogSolrSearchBuilder()
{
_solrSearch = new CommerceCatalogSolrSearch();
}
public
String SearchPhrase
{
get { return _solrSearch.SearchPhrase; }
set { _solrSearch.SearchPhrase = value; }
}
public
int PageIndex
{
get { return _solrSearch.PageIndex; }
set { _solrSearch.PageIndex = value; }
}
public
int PageSize
{
get { return _solrSearch.PageSize; }
set { _solrSearch.PageSize = value; }
}
public
Dictionary<String,String> FacetQueries
{
get { return _solrSearch.FacetQueries; }
set { _solrSearch.FacetQueries = value; }
}
public
String[] Facets
{
get { return _solrSearch.Facets.ToArray(); }
set { _solrSearch.Facets = value; }
}
public
override CommerceSearchCriteria ToSearchCriteria()
{
return _solrSearch;
}
}
Once you have these two classes in place you can now safely cast the CommerceOperation you receive as an argument of the overidden ExecuteQuery method in the SequenceComponent
to the CommerceCatalogSolrSearch operation you have just created, e.g.
public CommerceCatalogSolrSearch TryGetSearchCriteria(CommerceOperation operation)
{
var searchCriteria = operation as CommerceQueryOperation;
if (searchCriteria == null)
throw
new
Exception("No search criteria present");
var local = (CommerceCatalogSolrSearch) searchCriteria.SearchCriteria;
if (local == null)
throw
new
Exception("Unexpected Search Criteria in Operation");
return local;
}
Now you have all of your search parameters present, you can go off an call the external search platform API. You will of-course get proprietry objects returned, so the next step in the process is
to convert the results being returned back into CommerceEntities. You do this via another extensibility point within the Commerce Server API called translatators. Translators are another separate class, this time derived inheriting the interface Microsoft.Commerce.Providers.Translators.IToCommerceEntityTranslator . As you can imaginge this interface is specific for the conversion of the object
TO a CommerceEntity, you will need
to implement a separate interface if you also need
to go in the opposite direction. If you implement the required method for the interace you will get a single translate method which has a source onkect, destination CommerceEntity, and a collection of properties as arguments. For simplicity sake in this example I have hard-coded the mappings, however best practice would dictate you map the objects using your metadatadefintions.xml file . Once complete your translator would look something like the following:
public
class
SolrEntityTranslator : IToCommerceEntityTranslator
{
#region IToCommerceEntityTranslator Members
public
void Translate(object source, CommerceEntity destinationCommerceEntity,
CommercePropertyCollection propertiesToReturn)
{
if (source.GetType().Equals(typeof (SearchProduct)))
{
var searchResult = (SearchProduct) source;
destinationCommerceEntity.Id = searchResult.ProductId;
destinationCommerceEntity.SetPropertyValue("DisplayName", searchResult.Title);
destinationCommerceEntity.ModelName = "Product";
}
}
Once you have a translator in place you can then safely map the results of your search platform into Commerce Entities and attach them on
to the CommerceResponse object in a fashion similar
to this:
foreach (SearchProduct result in matchingProducts)
{
var destinationEntity = new CommerceEntity(_returnModelName);
Translator.ToCommerceEntity(result, destinationEntity, _queryOperation.Model.Properties);
response.CommerceEntities.Add(destinationEntity);
}
In SOLR I actually have two objects being returned – a product, and a collection of facets so I have an additional translator for facet (which maps
to a custom facet CommerceEntity) and my facet response from SOLR is passed into the Translator helper class seperatley.
When all of this is pieced together you have sucessfully completed the extensiblity point coding. You would have created a new OperationSequanceComponent, a custom SearchCritiera object and message builder class, and translators
to convert the objects into Commerce Entities. Now you simply need
to configure them, and can start calling them in your code. Make sure you sign you assembly, compile it and identiy its signature.
Next you need
to put this a reference of your new assembly into the Channel.Config configuration file replacing that of the existing SQL Full Text component:
You will also need
to add your translators
to the Translators node of your Channel.Config too:
Lastly add any custom CommerceEntities you have developed
to your MetaDataDefintions.xml file.
Your configuration is now complete, and you should now be able
to happily make a call
to the Commerce Foundation API, which will act as a proxy
to your third party search platform and return back CommerceEntities of your search results. If you require data
to be enriched, or logged, or any other logic applied then simply add further sequence components into the OperationSequence (obviously keeping the search response first)
to the node of your Channel.Config file.
Now
to call your code you simply request it as per any other CommerceQuery operation, but taking into account you may be receiving multiple types of CommerceEntity returned:
public
KeyValuePair<FacetCollection ,List<Product>> DoFacetedProductQuerySearch(string searchPhrase, string orderKey, string sortOrder,
int recordIndex, int recordsPerPage, Dictionary<string, string> facetQueries, out
int totalItemCount)
{
var products = new
List<Product>();
var query = new CommerceQuery<CatalogEntity, CommerceCatalogSolrSearchBuilder>();
query.SearchCriteria.PageIndex = recordIndex;
query.SearchCriteria.PageSize = recordsPerPage;
query.SearchCriteria.SearchPhrase = searchPhrase;
query.SearchCriteria.FacetQueries = facetQueries;
totalItemCount = 0;
CommerceResponse response = SiteContext.ProcessRequest(query.ToRequest());
var queryResponse = response.OperationResponses[0] as CommerceQueryOperationResponse;
// No results. Return the empty list
if (queryResponse != null && queryResponse.CommerceEntities.Count == 0)
return
new
KeyValuePair<FacetCollection, List<Product>>();
totalItemCount = (int)queryResponse.TotalItemCount;
// Prepare a multi-operation
to retrieve the product variants
var multiOperation = new CommerceMultiOperation();
//Add products
to results
foreach (Product product in queryResponse.CommerceEntities.Where(x => x.ModelName == "Product"))
{
var productQuery = new CommerceQuery<Product>(Product.ModelNameDefinition);
productQuery.SearchCriteria.Model.Id = product.Id;
productQuery.SearchCriteria.Model.CatalogId = product.CatalogId;
var variantQuery = new CommerceQueryRelatedItem<Variant>(Product.RelationshipName.Variants);
productQuery.RelatedOperations.Add(variantQuery);
multiOperation.Add(productQuery);
}
CommerceResponse variantsResponse = SiteContext.ProcessRequest(multiOperation.ToRequest());
foreach (CommerceQueryOperationResponse queryOpResponse in variantsResponse.OperationResponses)
{
if (queryOpResponse.CommerceEntities.Count() > 0)
products.Add(queryOpResponse.CommerceEntities[0]);
}
//Get facet collection
FacetCollection facetCollection =
queryResponse.CommerceEntities.Where(x => x.ModelName == "FacetCollection").FirstOrDefault();
return
new
KeyValuePair<FacetCollection, List<Product>>(facetCollection, products);
}
..And that is it – simply a few classes and some configuration will allow you
to extend the Commerce Server query operations
to call a third party search platform, whilst still maintaing a unifed API in the remainder of your code.
This logic stands for any extensibility within CommerceServer, which requires excution in a serial fashioon such as call
to LOB systems or web service
to validate or enrich data. Feel free
to use this example on other applications, and if you have any questions please feel free
to e-mail and I'll help out where I can!
