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!