Blog posts by Shannon Gray

Episerver Catalog Packages vs Bundles

Fri, 09 Jun 2017 03:41:58 GMT

This is a short blog to clarify a catalog concept that is often unclear for folks new to Episerver : the difference between bundles and packages.

Bundles and packages are catalog item-types that have distinct features and different use cases.

A bundle is a collection of SKUs that are simply grouped together for catalog-browse and add-to-cart purposes. There is no bundle-specific pricing or inventory. The pricing for a bundle is simply the total of the prices for the SKUs in the bundle. Inventory is tracked on the SKU level. A common scenario for using bundles is when an item usually needs to be bought in conjunction with other items in the catalog, like a phone and its charger.

When a bundle is added to the cart, your “add to cart” functionality needs to retrieve the SKUs in the bundle from the system and add each one to the cart. Once in the cart, the SKUs from the bundle are not identifiable as part of a bundle; they’re simple SKUs (as lineitems) in the cart. Therefore, a) you can’t attribute promotions to them as a bundle, b) you can change the quantity of each SKU/lineitem independently, and c) you can delete the individual lineitems that were associated with the bundle SKUs. Given the lack of pricing on a bundle and that promotions can’t be applied to them, you can’t provide discount pricing to incentivize buying bundles (at least not without significant additional development).

Conversely, packages contain SKUs but have their own pricing and inventory. When you add a package to the cart, its a single lineitem, like a SKU. SKUs can’t be removed from the package lineitem in the cart. You can only update the quantity of the package in the cart (or remove it). You can think of a package as a group of SKUs that are physically stored together and inventory is managed on the package level. Packages allow you to provide discounted pricing for a group of SKUs. You can also create promotions for packages. Note, however, that promotions which apply to SKUs contained in the package will not apply to the package lineitem.

These catalog types and their behavior are flexible with some minor customization. You could do things like:

* Create a “dynamic package”, where a user can select which items in a package or bundle is ultimately purchased in their cart.

* Use packages but still maintain inventory on the SKU level

* Add a package as multiple lineitems in the cart

These customizations may require additional effort to a) ensure your pricing logic reflects this logic, b) modify the way carts are processed to validate the content of the carts, update prices, etc , and/or c) change the way your add to cart functionality works.

Documentation on how to work with packages and bundles programmatically is here:

http://world.episerver.com/documentation/developer-guides/commerce/catalogs/catalog-content/Bundles-and-packages/

[Edited to incorporate comments below from Khurram and Per from 6/9/17]

Episerver Releases B2B Demo Site

Mon, 03 Apr 2017 22:11:30 GMT

Episerver just released the source code for a B2B demo site. This site is designed to showcase how Episerver easily supports complex B2B capabilities. Ed Kennedy and Jacob Khan gives a great introduction to the site below.

Its built on the QuickSilver demo site and has its own catalog; the catalog is also more B2B/Industrial, containing items like Lifting Equipment, Power Tools, and Generators.

Here's some of the capabilities it demonstrates:

· Organizing customers into companies (Organizations) and company divisions (Sub-Organizations)

Customers can be associated with Organizations, representing the company. In addition, an organization can have sub-organizations, representing subdivisions.

· Customer Self Service, as a Company/Organization

Users for a company can log in and see/manage their company's users, orders, order pads (e.g. wishlists), divisions, addresses, and other information.

· User Impersonation

This empowers customer users to impersonate other user's within the company.

· User Roles within a Company

The site demonstrates how you can use Episerver to create admins, purchasers, and approvers with different permissions. Admins can manage the company's users, budgets, orders, etc as well as impersonate purchasers and approvers. Purchasers can't manage or see their company's information, but they can place orders. Approvers can see organization information and approve purchaser orders, allowing them to be submitted to the backend. To be clear, this is an example role setup - each B2B implementation user role setup will be unique.

· Customer Credit Accounts/Budgets

Users can manage their organization's budgets. These budgets can be assigned to a Purchaser. These budgets can then be used as a payment method during checkout.

· Order Workflow

Carts can be submitted by Purchasers. Orders placed by Purchaser's must be approved by Approvers to be submitted for fulfillment.

· Requesting a Quote

Carts and Order Pads can be submitted to the backend for a quote. The quote can then be processed in the Order Management system, updating the pricing, and marking the quote as complete.

· Organization-based Pricing

This demonstrates how Episerver supports pricing based on association to an Organization. Organizations have a property, Customer Group, which maps to the pricing field Customer Price Group. Using this, you can group one or more Organizations in a Customer Group and assign a price to that Customer Group. Any users associated with that organization will get that price. To learn more about that, read here: http://world.episerver.com/documentation/developer-guides/commerce/pricing/.

· Organization-based Discounts

This highlights how you can create a visitor group that maps to a customer's Organization Customer Group (see previous). You can then target promotions to only apply to members of that visitor group/Organization using a setting on the Campaign settings.

You can find the source for this B2B demo, setup directions, and user logins here : http://github.com/episerver/quicksilverb2b

It should be noted: this is a demo site, not a production-ready site. It showcases capabilities and provides code samples you can use in your implementations. The demo site also has its own business rules built-in to demonstrate a particular B2B scenario (for example, a particular order workflow, particular user permissions, the use of budgets, etc.). Of course, those underlying features can be used in plenty of implementation approaches.

Promotion Engine Sale Price Customization

Mon, 14 Nov 2016 23:14:08 GMT

Overriding how sale prices are calculated in Episerver’s promotion engine for SKUs and packages outside of the cart requires a minor customization. Good examples of where this applies are category landing page and product detail pages where you may show a discount price(s). Sales price calculation is usually done by a) evaluating the prices associated with a SKU or package and b) applying the site’s business rules to determine the correct price of an item for a customer. The sales price is calculated in the promotion engine to determine the price from which to subtract the promotion discounts. As I previously mentioned here, using the PromotionEngine GetDiscountPrices() method involves an important constraint: It has a default sale price calculation built in which may or may not fit your site’s business rules. Here is how to customize the promotion engine to use alternate pricing calculation logic.

The sale price for items to be evaluated in the promotion engine is calculated in the PromotionEngineContentLoader class by calling the ReadOnlyPricingLoader GetDefaultPrice() method. This method returns the lowest “All Customer” price for an item that has a valid date and is the correct currency and market for the current customer. So it doesn’t use customer-specific, price group, or custom sale price types to calculate the sale price. An instance of PromotionEngineContentLoader is stored in the IOC container and used in the promotion engine - so it can be overridden in your implementation.

To override this sale price calculation in the promotion engine, create a class that inherits from PromotionEngineContentLoader and then configure your IOC container to use this new implementation. Here’s an example of how you can do this:

   1: public class CustomPromotionEngineContentLoader : PromotionEngineContentLoader

   2: {

   3:     public CustomPromotionEngineContentLoader(

   4:             IContentLoader contentLoader,

   5:             CampaignInfoExtractor campaignInfoExtractor,

   6:             ReadOnlyPricingLoader readOnlyPricingLoader) : base(contentLoader, campaignInfoExtractor, readOnlyPricingLoader){ }

7:

   8:     public override IOrderGroup CreateInMemoryOrderGroup(ContentReference entryLink, IMarket market, Currency marketCurrency)

   9:     {

  10:         var orderGroup = new InMemoryOrderGroup(market, marketCurrency);

11:

  12:         //this is where you can reference your own pricing calculator to retrieve the right sale price

  13:         IPriceValue price = YourSalePriceCalculator.GetSalePrice(entryLink);

14:

  15:         if (price != null)

  16:         {

  17:             orderGroup.Forms.First().Shipments.First().LineItems.Add(new InMemoryLineItem

  18:             {

  19:                 Quantity = 1,

  20:                 Code = price.CatalogKey.CatalogEntryCode,

  21:                 PlacedPrice = price.UnitPrice.Amount

  22:             });

  23:         }

24:

  25:         return orderGroup;

  26:     }

  27:          …

  28: }

Notice that an IOrderGroup is used to contain the SKU or package. The InMemoryOrderGroup is simply an implementation of that interface that allows carts and one-off SKUs or packages to be processed for promotion calculation in the same way. This also simplifies promotion calculation. It allows for the custom promotion processors (see here) that you create to simply process the IOrderGroup instance rather than having separate methods for one-off items and carts. The PromotionProcessorContext class contains an IOrderGroup property and is passed into the Evaluate() method for promotion processor classes.

Finally, add initialization of your IOC container to point to your custom implementation like this:

   1: [ModuleDependency(typeof(EPiServer.Commerce.Initialization.InitializationModule))]

   2: public class DiscountCalculateInitialization : IInitializableModule, IConfigurableModule

   3: {

   4:     public void ConfigureContainer(ServiceConfigurationContext context)

   5:     {

   6:         context.Container.Configure(c => c.For<PromotionEngineContentLoader>().Singleton().Use<CustomPromotionEngineContentLoader>());

   7:     }

   8: …

   9: }

The ModuleDependency ensures that the new implementation is set/used, overriding the original implementation set in Episerver’s commerce initialization module.

As you can see, overriding the promotion engine sale price takes very little effort. I think the new promotion engine has made calculating discounts a lot easier with a straight-forward and exposed model that can be overridden.

Calculating Discounted Pricing With Episerver’s New Promotion Engine

Tue, 25 Oct 2016 07:52:49 GMT

Episerver's new promotion engine makes it easy to calculate discounts. It is also designed so that developers can easily override built-in promotion functionality and custom business rules can be applied in the calculation of discounts.

In working with Episerver's new promotion engine, the two most common places where you need to calculate discount prices are 1) for individual SKUs (like on a product detail page or category browse page) and 2) in the cart.

Calculating discounts and applying them to the cart is simple. Simply run either the CartValidate or CartPrepare activity flows as documented here:
http://world.episerver.com/documentation/Items/Developers-Guide/Episerver-Commerce/9/workflows-and-activities/workflows-and-activities/
Or you could use the more direct cart processing methods like cart.ApplyDiscounts() as documented here:
http://world.episerver.com/documentation/Items/Developers-Guide/Episerver-Commerce/9/Orders/order-processing/

However, calculating the discounted price for a SKU/package individually involves a little more effort. Here's a quick and easy example discount calculator to do that:

private static Injected<ICurrentMarket> _currentMarket;
private static Injected<IPromotionEngine> _promotionEngine;
private static Injected<ReferenceConverter> _referenceConverter;
private static Injected<ILineItemCalculator> _lineItemCalculator;
 
 
public static decimal GetDiscountPrice(VariationContent variation, IMarket market)
{     
  if (market == null)     
  {
    market = _currentMarket.Service.GetCurrentMarket();     
  }    
  
  //these discounts are returned in order of priority and only if not excluded
  IEnumerable<DiscountedEntry> discountEntries =
    _promotionEngine.Service.GetDiscountPrices(new List<ContentReference>() { variation.ContentLink }, market, market.DefaultCurrency, _referenceConverter.Service, _lineItemCalculator.Service);     
    
  //get the biggest discount promotion application and return     
  decimal lowestDiscountedPrice = discountEntries.SelectMany(x => x.DiscountPrices).OrderBy(x => x.Price).FirstOrDefault().Price.Amount;     
  
  return lowestDiscountedPrice;
}

An explanation of what this code does:
_promotionEngine.Service.GetDiscountPrices() retrieves a list of DiscountedEntry objects. Each DiscountedEntry represents the discounted price for a SKU/package after each applicable promotion is applied. The DiscountedEntry instances reflect the applicable promotions with configured exclusions preventing inapplicable promotion discounts from being returned. In addition, the discounted prices are returned in the sort order specified in the promotion configuration UI for applicable promotions.

This means, when lowestDiscountedPrice is calculated, we're limited to taking one of the discounted prices and returning it. There isn't sufficient information readily available to calculate the compounded discount price for a SKU or package (when multiple promotions are applied).

GetDiscountPrices() also has a built-in price calculator to determine the sale price for the SKU or package (which is then discounted based on applicable promotions). The price calculator takes the lowest All Customers price from the SKU/packages.

If these two limitations work for your site (Only one promotion can apply to a SKU or package AND the lowest All Customers price is the correct SKU/package sale price), then this is all you need to use the new promotion engine on catalog pages. The approach is also a quick-and-easy way to test that custom promotions you're creating are functioning properly.

However, if this approach doesn't meet your site needs, some base functionality in GetDiscountPrices() needs to be overridden. This will be the topic of my next blog.

Do A Lot More With EPiServer Commerce Promotions With a Little Code

Tue, 30 Jul 2013 06:22:55 GMT

The promotion engine is powerful. It allows you to create a broad range of promotions with very different criteria and rewards out of the box. The Build Your Own Discount promotions are especially flexible. Here are some ways that you can extend Build Your Own Discounts to be even more powerful.

1. Promotions based on LineItem metafields : its not obvious how to use LineItem metafields for promotion criteria. For example : For all LineItems in a cart where the color (a LineItem metafield in this example) is green, give $20 off the order total.

2. Promotions based on SKU/Entry metafields : they aren't exposed at all in the dynamic fields of the Build Your Own Discount promotion types. So it doesn't seem possible to provide a discount for all SKUs with the color "Green" and product types of "notebook".

3. Promotions based on product codes rather than SKU codes: When the catalog is made up of products and SKUs, there isn't a visible way of providing discounts for products. For example, buy a shirt product (for which there are SKUs representing different colors and sizes) and get 20% off of the price for any of its associated SKUs.

4. Promotions targeting anonymous customers based on visitor groups or other criteria: Customer Segments are designed to target promotions to logged-in users. There doesn't seem to be a way to target anonymous users based on their visitor group, location information, the online marketing campaign that got them to the site, market, or any other user information.

Here's How You Can Create Each of These:

LineItem metafields

You can create Build Your Own Discounts using the metafield values of the LineItems in a customer's cart.

How to implement:

* Add metafields to the LineItem metaclass for each of the fields you want to use in creating promotion criteria.

* Populate the LineItem metafield when the SKU is added to the cart to create the LineItem. The code to do this looks like:

_cartHelper.AddEntry(entry, quantity, false, new CartHelper[] { _cartHelperToRemove });

//after adding the Entry, get a reference to the lineitem and pass in the metafield value that's used by the promotion
LineItem item = _cartHelper.Cart.OrderForms[0].LineItems[_cartHelper.Cart.OrderForms[0].LineItems.Count - 1]; 

item["Taste"] = entry.ItemAttributes["Taste"].Value[0]; 

_cartHelper.Cart.AcceptChanges();

Even better code is coming up to do this more generically..

Explanation:

You may have noticed that lineitem metafields are exposed in the dynamic properties in Build Your Own Discounts. This means that, when an item is added to the cart, the metafield needs to be populated in the LineItem and a promotion will apply to that LineItem where there is a promotion criteria match with that metafield. In the image below, an Order Build Your Own Discount is created with a condition that the lineitem metafield Taste be equal to a value. Note that this only works when discounts are calculated for a cart (for example with the CartValidate or CartPrepare workflows), not for a SKU on a category browse page. When you add new lineitem metafields, make sure you reset IIS so you'll see the new field(s) in Commerce Manager.

You can also do this:

There’s one important caveat regarding using metafields (for entries or lineitems):

The metafield cannot support multiple languages or be a dictionary type. It needs to be a string-type field (e.g. ShortString) and can’t be numeric.

The metafield should be an internal field. For example, you may have a field "Color" which is multi-lingual and used on the front end to display different text based on the language settings for the customer. Then you'd setup a secondary field "CLR" which was used strictly for internal logic purposes, like promotions.

These limitations can be circumvented by using the marketing provider discussed at the end of the article.

Entry metafields

Its possible to target promotions based on Entry metafields, which would allow promotions to apply to SKUs being browsed on the site (not just items in the cart as above). To do this, associate a metafield in the lineitem class to a SKU metaclass as well. Then, when the SKU is added to the cart, make sure the cooresponding metafield is populated in the lineitem.

How to implement:

* Add a metafield to the LineItem metaclass (if it doesn't already exist there)

* Add a metafield to the applicable SKU metaclass (if it doesn't already exist there) where you want to apply a promotion

* Populate the SKU metfield value (if not already populated).

* Make sure the LineItem metafield is updated with the SKU value for the same metafield when added to the cart. See the code above for the LineItem metafield promotions.

Explanation:

If you've looked at the code for calculating discounts, both in Mediachase.Commerce.Website.Helpers.StoreHelper and Mediachase.Commerce.Workflow.Activities.CalculateDiscountsActivity, you'll notice that the an entry or a lineitem can be used to calculate a discount. These can be seen in :

StoreHelper.GetDiscountPrice(Entry entry, string catalogName, string catalogNodeCode, IMarket market, Currency currency)

and

CalculateDiscountsActivity.CalculateDiscounts()

Yet, when you configure a Build Your Own Discount in Commerce Manager, you only see the LineItem metafields listed as possible attributes to map promotion criteria to. Furthermore, the properties of the promotion refer to TargetLineItem. What's happening in both of the aforementioned methods is that many of the base fields and all of the metafield values of the Entry and LineItem objects are being mapped internally to a third class, PromotionEntry. When a discount price is being calculated for an Entry (like on a category landing page), the Entry metafields are added; when the discount price is calculated on a cart, the LineItem metafields are added. The PromotionEntry class doesn't know weather "it" is an Entry or a LineItem. The PromotionEntry is then used by the promotion engine to match up whether a promotion applies to a SKU or LineItem.

Here's a diagram that creates a visual explanation of this:

So you can create a promotion that targets a LineItem metafield that also happens to be shared by an Entry metaclass. If the code calls StoreHelper.GetDiscountPrice() for an Entry that has a metafield "CLR", the LineItem metaclass also has a metafield "CLR", and you've created a promotion with a criteria for CLR to be equal to Green, it will match the Entry metafield value for the Entry used in the StoreHelper.GetDiscountPrice() method.

Here’s some example code for adding all Entry field short string metafield values into matching Lineitem metafield values:

_cartHelper.AddEntry(entry, quantity, false, new CartHelper[] { _cartHelperToRemove });

//after adding the Entry, get a reference to the LineItem and pass 
//in the metafield value that's used by the promotion

… 
lineItemBeingAdded = _cartHelper.Cart.OrderForms[0].LineItems[_cartHelper.Cart.OrderForms[0].LineItems.Count - 1]; 

MapEntrytoLineItem(entry, lineItemBeingAdded);
…

/// <summary> 
/// Map all matching SKU metafield values (strings only) to matching lineItem metafields 
/// </summary> 
/// <param name="entry"></param> 
/// <param name="item"></param> 
private void MapEntrytoLineItem(Entry entry, LineItem item) 
{ 
   foreach (ItemAttribute entryAttribute in entry.ItemAttributes.Attribute) 
   { 
     foreach (MetaField lineitemAttribute in item.MetaClass.MetaFields) 
     { 
       if (lineitemAttribute.Name.Equals(entryAttribute.Name)) 
       { 
         if (entryAttribute.Type.Equals("ShortString", StringComparison.InvariantCultureIgnoreCase)) 
         { 
           item[lineitemAttribute.Name] = entry.ItemAttributes[entryAttribute.Name].Value[0]; 
         } 
       } 
     } 
  } 
}

Promotions With Product Criteria

If a catalog contains products and SKUs, the current approach to target items in that catalog is either limited to a catalog, category code, or SKU - there isn't a clear way to target products.

This is important if you want to simplify creating Build Your Own Discounts. For example, if you want to target 5 products that have 30 associated SKUs - that's a tedious build your own discount to create. However, there is a way to create promotion criteria that map to product codes. To add this, you can simply add a metafield to the SKU metaclass definition, call it something like ProductCode, and populate it with the parent product code. Setting the metafield value can either be done to the database definition of the SKU or dynamically, during runtime, immediately before calling the StoreHelper.GetDiscountPrice() or running one of the workflows. There also needs to be a matching product code metafield on the LineItem metaclass. And as before, the Entry metafield value needs to be mapped to the lineitem metafield when the item is added to the cart. Then you can write promotions that target products.

Customer Targeting

If you want to target particular customers for your promotions, you're currently seemingly limited to customer segment configuration in promotions and promotion campaigns. And customer segments require the user to be logged in and to have provided information like their email or address.

However, there is a way to inject customer information into a SKU or lineitem to allow that information to be used as a promotion criteria. To do this, you need to add a metafield to the Entry object in memory before calling StoreHelper.GetDiscountPrice() or executing a workflow.

The ItemAttributes portion of the Entry object is settable. So you can retrieve the built-in collection of metafield values from ItemAttributes and add your own metafields and values. So you could do something like:

List<ItemAttribute> attributeList = new List<ItemAttribute>(entry.ItemAttributes.Attribute); 
ItemAttribute visitorGroupAttribute = new ItemAttribue();
visitorGroupAttribute.FriendlyName = "VisitorGroup"; 
visitorGroupAttribute.Name = "VisitorGroup"; 
visitorGroupAttribute.Type = "ShortString";

//the value set in this metafield can be a visitor group lookup or other customer-attributes 
visitorGroupAttribute.Value = new string[] { "MyVisitorGroup" };

attributeList.Add(visitorGroupAttribute); 
entry.ItemAttributes.Attribute = attributeList.ToArray(); 

var discountPrice = StoreHelper.GetDiscountPrice(entry, string.Empty, string.Empty, _marketId);

To be able to use this new metafield, you'd need to add a new metafield named "VisitorGroup" to the LineItem metaclass. When the entry is added to the cart, make sure the LineItem metafield is populated. Now you'll be able to create Build Your Own Discounts that can target different anonymous users based on their associated Visitor Groups or geo-location lookup location or whatever other criteria you want to you.

Extending the Promotion Engine Further

There's another alternative to implementing this logic. You can control how the PromotionEntry object is populated in the StoreHelper.GetDiscountPrice() method and CalculateDiscountActivity before its used to determine whether an Entry or Cart or LineItem meets a promotion's criteria. The EPiServer Commerce system has a provider model for populating the PromotionEntry object. It allows you to explicitly set what fields are added to the PromotionEntry object.

This approach allows you to circumvent the aforementioned limitations where non-string values don't work in promotions and dictionaries can't be used. The reason non-string values don't currently work is because the string representation of all metafield values is currently injected into the PromotionEntry object. However, in your own implementation, you can pass the correct data types in for those metafields you want to use in your promotions. Once you've done this, you'll be able to do things like create a criteria where the container size is greater than 10.

You can use the marketing provider model to :

- add customer segment information like visitor groups or online marketing campaign ids

- decide what dictionary values are added and in what format

- decide what localized version of a field is used in the PromotionEntry

- add values in their explicit type

- create composite fields (using the data from several metafields and/or data sources to create a custom field value)

- and other things no one has thought of.

To use this provider model:

* Create a new class project

* Add a new class to this project that inherits from IPromotionEntryPopulate. (See an example implementation here)

* Add your custom settings to the IPromotionEntryPopulate implementation

* Create a reference in your web site to this new project

* Modify the Configs/ecf.marketing.config file (PromotionEntryPopulateFunctionType element) to map to this new dll and class

* Create LineItem metafields that map to these new settings

* If using this with SKU promotions too, then add the metafields to the SKU metaclass as well. And populate the LineItems with the SKU values when they're added to the cart.

* Now you can create build your own discount promotions that use these custom properties.

An example implementation of the IPromotionEntryPopulate is provided here: http://world.episerver.com/Code/Shannon-Gray/Promotion-PromotionEntry-Provider-Implementation-Example/

It uses the implementation built-in to the API with some example added fields. There's not a lot to explain in the implementation. The class simply passes values from either a LineItem or an Entry object into the PromotionEntry dictionary (). Add your custom settings there.

All of these approaches will take more time thinking about and designing then any of the coding will take. Hopefully this help you create more customized promotions quickly and easily in EPiServer Commerce.

EPiServer Commerce Promotion Examples

Sat, 29 Jun 2013 03:01:12 GMT

Sometimes the best way to learn how something works is to see some examples of how its used. Below are a number of promotion examples built in EPiServer Commerce (out of the box) that will illustrate how dynamic promotions work. Specifically, you’ll see how to customize the Build Your Own Discount promotion templates to create a wide array of discounts. They come in three flavors : Entry (for giving discounts on individuals SKUs, independent of the cart, like on a category landing page), Order (for cart discounts on the cart or items in the cart), and Shipping (for providing discounts on shipping charges). Here are the examples with some explanation.

One general note is that the promotion descriptions are in $ but aren’t specific to a currency (unless specifically noted).

For orders which contain more than $60 of a combination of one or more skus, give a free gift