In just a few minutes we'll be shipping BV Commerce 6.0.40. This update brings some new features (like order editing) and includes a new REST based API. For those who don't know, REST is a way to let machines communicate to each other using standard HTTP protocols. When you type in a URL into your web browser you are making an HTTP GET request and asking a web server to "get" a web page for you. When you submit a form on a web site you're sending an HTTP POST request and posting some form data to a web server.

REST based APIs are simple by nature. They rely on the convention that each "resource" should have a single URL. For example, /api/v1/rest/products/abc123 would represent product ABC123. If I made an HTTP DELETE request to that address the server would delete that product if I have the correct permissions to do so.

Fortunately, you don't have to learn about HTTP methods and REST conventions to work with the new API in BV Commerce 6. We've created a simple class library that makes your life easier. Here's a quick tutorial:

1) Create a new project in Visual Studio

2) Add a reference to the BVSoftware.CommerceDTO class library

3) Make sure you have an API key created under Options->Api in the Admin side of your store

4) Here's the sample code to create a product:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using BVSoftware.CommerceDTO.v1;
using BVSoftware.CommerceDTO.v1.Client;
using BVSoftware.CommerceDTO.v1.Catalog;
namespace SuperSimpleApiSample
{
  class Program
  {
    static void Main(string[] args)
    {
      // Create the proxy to your remote storeApi 
      remoteServer = new Api("http://www.mystore.com", "my api key");
      // Create a local product object
      ProductDTO p = new ProductDTO();
      p.Sku = "ABC123";
      p.ProductName = "My Sample Product";
      p.SitePrice = 19.95m;
      // Call the create function
      // - Note, we're passing null instead of uploading an image for this sample
      ApiResponse response = remoteServer.ProductsCreate(p, null);
      // Output the newly created BVIN value for the product
      Console.WriteLine("The bvin of the created product is " + response.Content.Bvin);
    }
  }
}

BV Commerce 6 includes a completely revamped promotions engine. The previous version used a selection of pre-built sales and offers that limited what merchants could do in many ways. Because any price adjustments can be complicated it was also difficult to figure out exactly how a price was derived using the old system.

Promotions are now rule-based allowing merchants to mix and match qualifications and actions into powerful sales and offers. Like older versions promotions are grouped into two main types; sales and offers. A sale is a promotion that can apply to individual products as they are viewed on the store. An offer is a promotion that only applies to a cart/order.

Promotions in the Admin

From the Marketing»Promotions screen in the admin you can create custom sales and offers by combing your set of rules and actions or you can select from pre-defined promotions for common scenarios like a Storewide Sale or Free Shipping on specific items.

The main screen also displays the current status of promotions. Disabled promotions are hidden by default and when you create a new promotion it is marked is disabled for safety. This prevents it from accidently applying to items on the store while you’re working on it. You can use the Show Disabled Items checkbox when viewing the list to see any items you’ve created but haven’t completed yet. You can also search for the name of your promotion.

If a promotion is enabled, its status is evaluated based on the current date and time. All times are stored in Universal Time in the database to ensure that offers apply based on the store time zone only. Promotions are shown in the admin as Active, Expired or Upcoming. When the store evaluates promotions it only pulls the Active promotions from the database to reduce the processing require to price items.

Editing Promotions

When you initially create a sale or offer its Mode is set once and cannot change. If you edit a sale you will see a different set of qualifications and actions than you would if you edit an offer.

In the editor you add qualifications first. These are inclusive. Every rule must be valid or the promotion won’t apply. Some rules allow multiple selections. In this case the selections may be any or all based depending on the qualification settings. For example, the Product Category qualifier allows you to select many categories. It will apply to any product that is assigned to at least one of the categories in the list.

Qualifiers also have a Relative Processing Cost which is a measure of how much work is involved in checking the rule. Checking a ProductId on a product is a very low cost operation. We already have the product and it’s easy to check the ID. Checking a Product Category selection is a very costly operation because we need to make a database call to load up all categories for each product checked for the promotion. For this reason promotion qualifiers are sorted from lowest to highest cost before checks. This means that low cost checks might rule out the product before expensive steps are taken.

If you are creating your own qualifiers be aware that qualifiers may be called very frequently, especially for sales. Too many high cost operations and too many promotions running at one time can bring a store grinding to a halt if you’re not careful.

Actions are applied in sequence to the product or order. Their effect is cumulative. Adding many actions to a promotion can have strange effects and is not recommended unless you are careful.

Unified Discounting System

The new promotion engine relies on the unified discounting system, which provides much better feedback and reporting on exactly how prices are derived. In the past, prices were adjusted in multiple places and there was no way to track down exactly what happened along the way. One common reporting problem was the prices for sales were adjusted before items arrived in the cart. This meant that reports could not show retail prices and discounts for sales.

The new system uses a list of DiscountDetails on products and line items. Each detail shows the amount applied and a description of what created the discount. User group pricing, volume discounts and promotions all use this list to describe price changes. Any custom code that adjusts prices should use this system too.

Products are priced when viewed by the BVApplication.PriceProduct() method. This takes into account the current environment like current time and current user when evaluating priced. Calling this one method on any product before display ensures that the correct sales and discounts will be shown to the shopper.

The shopping cart now displays the discounts as part of the line item detail. This makes tracking down pricing origins much easier and allows merchants to add attention getting descriptions of discounts to the cart.

Extending the Discounting System

Although the new discount system is rule based and appears to be very extensible BV recommends that you do not create your own custom qualifiers or actions at this time. We prefer that you contact us with your requirements and see if we can create a built-in generic qualifier or action as needed. There are two reasons for this: a) Promotions can have a big performance impact and we’d rather build them in and test before releasing them on a live store and b) we do not have a plugin model yet for promotions. We’d like the promotions system to live in the wild for a little while before we lock it down to a specific plugin API.

BV Commerce 6 includes a new theme system that offers lots of new options to designers. Developers should be aware of the new theme structure and how things work.

System Themes and User Themes

One of the issues that arose with previous versions of BV Commerce was that designers had a tendency to edit the built-in themes directly rather than make copies of them. This meant that when a service pack was released it had the potential to overwrite a modified built-in theme without the designer knowing.

To resolve this BV Commerce 6 has a selection of “System Themes” which are built-into the software and then are installed to a store as needed. This allows designers to create their own modified themes with a single click from Options->Themes in the admin side. It also has the benefit of allowing designers to create copies of their own themes for backup and versioning purposes.

The system themes are located in the /Content/Themes folder where each folder represents an individual theme available for install. As a developer any new theme you place in this folder becomes available for install in stores.

When themes are installed they are copied to the /images/sites/{0}/themes folder where {0} represents the ID number of the store. For toolkit installs of BV Commerce there will only be a single store ID. Themes are copied with their exact name so that the system knows which themes have been installed already and which ones are available for new install. If you made a copy of the “Simple Blue” theme you’re actually creating a new one. Deleting your copy of the original Simple Blue theme would make it once again available for install. So, if a new version of a system theme is made available in a service pack you can duplicate your current version for backup and then install the new one.

Theme Parts

BV Commerce 6 Themes are made up of a collection of files in a folder. Every theme in BV 6 uses the same Site.Master file from the root of the web site.

Bvtheme.xml – This is the theme definition file that contains information like the theme ID, name and designer’s web site. You can edit this by hand or duplicate an existing theme and use the built-in theme editor pages in the admin to modify the file.

ColumnData.xml – Another new feature of BV Commerce 6 themes is the ability to save and install content columns to/from a store. This gives designers the flexibility to customize the site when a theme is installed. This file is the XML serialized version of the content columns and blocks. Don’t worry, you can also use the theme editor pages in the admin side to copy blocks into this file. No need to hand edit.

Preview.png and Preview_big.png – These are preview images that show store users what your theme normally looks like when installed.

Header.htm and Footer.htm – These files contain any custom HTML header and footer for the theme. These files contain standard HTML but also have optional tokens that are replaced at runtime. For instances the text {{copyright}} would be replaced by a copyright symbol and the current year.

Styles.css – This is the CSS file for the store. It is processed and minified before being returned to the browser. This allows you to use site-relative URLs in the style sheet like “~/images/sample.png” for a background image. The “~” character is replaced with the site relative root just like ASP.NET pages do.

/Assets – This folder inside the theme contains any images the theme may need to install in the store’s assets. For example, if you need to install a background image you would place it in this folder and when the theme is installed the file would automatically be copied to the stores Assets.

/Buttons – This folder contains button images to replace the standard button images. It is highly recommended that you create a complete set of button images. Image names must match exactly although PNG, JPG and GIF formats are accepted (in that order).

Theme Options on the Admin Web Site

The admin web site contains a new set of theme options under Options->Themes. The first page is the control panel showing a list of available themes on the right and installed themes on the left. Hovering over a theme on the right shows an “Install” button which you can use to copy a system theme to the current store. Hovering over an installed theme shows options to “Select”, “Duplicate”, “Edit” or “Delete” a theme. The currently selected theme displays in a different color background and will not have a “Select” button available.

The “Duplicate” button creates a copy of any theme. “Delete” removes a theme from the store but does not destroy system themes, which are always available. “Edit” takes you to the edit theme area.

http://help.bvcommerce.com contains several tutorials showing how to create and edit themes from the admin control panel. As a developer, just be aware that under the hood these pages are editing the files described above in the appropriate theme folder.

BV Commerce 6 includes a completely new search engine. Previous versions used simple SQL “LIKE” statements to match up parts of words. This made it difficult to determine relevancy and had trouble handling plural words. The new search engine functions more like Google. The BVSoftware.Search project has the main implementation of a generic search engine and the BVSoftware.Commerce project has management classes that are specific to commerce web sites.

Lexicon

The first part of the new search system is the Lexicon. This is a simple storage container that holds words and assigns them a numerical value. Every word that has ever been indexed in the search engine will exist exactly once in the lexicon. Part of the magic of the Lexicon is that although it can accept any word, BV only inserts stemmed words.

Stemmer

The stemmer is a tool used to convert plain English text into specialized roots of the word. For example, “Flower” and “Flowers” would stem to the same root. So would “Child” and “Children” which is more difficult to classify with simple rules. The BV Commerce stemmer uses the Porter Stemmer Algorithm. The first version was written by Martin Porter in the 1980’s and has become the de-facto standard for English language stemming. Keep in mind that if you are using BV Commerce in a non-English language you may need to replace the stemmer algorithm with one appropriate to your store’s language.

Search Objects and Search Object Words

The Lexicon stores information about words and SearchObjects are the items that contain words. SearchObjectWords are the core of the search system. SearchObjectWords relate SearchObjects to specific words with relevancy information. They link a “SearchObjectId” to a “WordId” from the Lexicon and have a “Score” which tells a searcher how important that word is for the SearchObject. A SearchObject is simply anything that can be indexed. It has an Id, a short summary of the item and links to the actual item. Item Type is also useful on SearchObjects allowing the search engine to return results for Products, Pages, or both.

Indexers

An indexer takes information about words and scores for an object and inserts it into the catalog of searchable items. A simple text indexer scores words based on the frequency with which they appear and a complex indexer accepts a list of pre-scored words for indexing. The complex indexer is used to index items in BV. The BVSoftware.Commerce.Catalog.SearchManager class pre-scores words for Products and other BV items then sends that data to the Complex Indexer to be included in future searches. The SearchManager scores words based on their importantance as BV Product information. For example, a word in the Title of a product will have a higher score than the same word in the description of the product. This helps return relevant search results even if other items had a higher count of the same word in their description.

Text Parser

The Text Parser is responsible for taking strings of text and converting them into a list of usable search terms. This includes splitting the text into individual words, removing non-alphanumeric characters, stemming words and removing stop words. Stop words are real words that have little to no effect on searches. Common examples include “I”,”a”,”and”,”but”,”of”,”from”,etc. By removing these words searches are more efficient and relevant. The Text Parser is used to clean up incoming queries and by the indexer so that the same rules apply to text from objects as text from search requests.

Searcher

The searcher class is the glue that ties everything together to deliver search results. It takes a Lexicon of words, a store of SearchObjects and SearchObjectWords and uses a Text Parser to convert from a text query into Word and Object Ids.

Summary

When a customer types in a search request on a BV Commerce 6 store the following steps take place:

• The search query is sent to a text parser where it is split into words and stop words are removed
• The query words are stemmed to their roots
• A searcher looks up those words in the Lexicon to see if they exist yet and to get their Ids
• The search looks through all of the search words to find the search objects that contain the highest score for those words and returns the a list of those objects.
• The BV search results page looks at the results and generates links to the items based on their Id and object type.