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!
