You are on page 1of 37

Sitecore Reference Storefront

Sitecore Commerce 8.2


Developer Overview
Sitecore Reference Storefront

Table of Contents

Chapter 1 Introduction ...................................................................................................................................... 4


1.1 License .................................................................................................................................................. 5
Chapter 2 Development Environment ............................................................................................................... 6
2.1 Solutions and Projects ........................................................................................................................... 7
2.2 Compiling the Sitecore Reference Storefront source code solution ....................................................... 8
2.2.1 Compiling the Commerce Server Solution ......................................................................................... 8
2.2.2 Compiling the AX Solution ................................................................................................................ 9
2.3 Architecture Overview ........................................................................................................................ 10
2.3.1 Sitecore Content Tree ..................................................................................................................... 10
2.3.2 Controller View Request and Javascript API Calls ............................................................................ 10
2.3.3 Knockout.js ..................................................................................................................................... 10
2.3.4 Views & Labels ................................................................................................................................ 11
2.3.5 Controllers, Managers and Connect API Calls .................................................................................. 11
2.3.6 HTML Caching ................................................................................................................................ 12
2.4 Catalog Presentation........................................................................................................................... 14
2.4.1 Resolving Category and Product Presentation via the Shop Item .................................................... 14
2.5 Checkout ............................................................................................................................................. 15
2.5.1 Differences Between Dynamics and Commerce Server ................................................................... 15
2.6 Multi Storefront Support ......................................................................................................................17
2.6.1 Setting Up a Second Storefront for Commerce Server .....................................................................17
2.6.2 Setting Up a Second Storefront for Microsoft Dynamics ................................................................. 18
2.7 Security ............................................................................................................................................... 20
2.7.1 HTTPS Implementation .................................................................................................................. 20
2.7.2 Controller Method Attributes .......................................................................................................... 20
2.8 Miscellaneous ..................................................................................................................................... 22
2.8.1 ProductItemResolver ...................................................................................................................... 22
2.8.2 CatalogLinkManager ....................................................................................................................... 22
2.8.3 Map Credentials .............................................................................................................................. 23
2.8.4 Category and Product Visited Renderings ....................................................................................... 23
2.8.5 Product Recommendations ............................................................................................................. 23
Chapter 3 GitHub Repository .......................................................................................................................... 25
3.1 Branching Strategy ............................................................................................................................. 25
Chapter 4 Do’s and Dont’s ............................................................................................................................... 27
4.1 Do Controller Renderings - Don't do View Renderings ......................................................................... 27
4.2 Use View Models Instead of Domain Objects....................................................................................... 27
4.3 JSON Responses Must Not Contain Domain Objects ........................................................................... 27
4.4 Respect the Controller, Manager, Connect API Pattern ....................................................................... 27
Chapter 5 Microsoft Dynamics Inventory Indexing .......................................................................................... 28
Chapter 6 Indexed and Live ECS Price Lookup ................................................................................................. 29
6.1 Commerce Server ............................................................................................................................... 29
6.1.1 Direct Access .................................................................................................................................. 29
6.1.2 Index File Access ............................................................................................................................. 29
6.2 Microsoft Dynamics ............................................................................................................................ 30
Chapter 7 Inventory Stock Status .................................................................................................................... 31
Chapter 8 Leveraging Sitecore Features .......................................................................................................... 32
8.1 Languages and Language Fallback ...................................................................................................... 32
Chapter 9 Performance ................................................................................................................................... 34
9.1 Rendering Caching .............................................................................................................................. 34
9.2 New Caching Option ........................................................................................................................... 34

2
Sitecore Reference Storefront
9.2.1 Vary by Url Path .............................................................................................................................. 34
9.3 Request Caching ................................................................................................................................. 34
9.4 Mini Cart Caching ................................................................................................................................ 35
9.5 Stock Status and Product Prices via Index Files ................................................................................... 35
9.6 Read-only session state support per controller method for improved performance ............................. 36

3
Sitecore Reference Storefront

Chapter 1 Introduction

The Sitecore Reference Storefront is an out-of-the-box storefront solution for building B2C e-commerce
solutions. It has its own separate installation package that contains a webshop, which builds on top of the Sitecore
Experience Platform and Sitecore Commerce powered by Commerce Server or Sitecore Commerce powered by
Microsoft Dynamics.
Both the Microsoft Dynamics and Commerce Server solutions can be found on GitHub:
https://github.com/Sitecore/Reference-Storefront

4
Sitecore Reference Storefront

1.1 License
The solution is licensed under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the
License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
In order to contribute as an individual or company, you will have to sign an agreement and get it approved by
Sitecore.
For more information and in order to obtain agreement forms, visit GitHub

5
Sitecore Reference Storefront

Chapter 2 Development Environment

The Sitecore Reference Storefront development is based on Microsoft Visual Studio 2013. The solution makes use
of Team Development for Sitecore (TDS) from Hedgehog Development to maintain the storefront Sitecore items
and produce update packages that can later be uploaded to Sitecore.
Before you can build the solution, you will need to copy assemblies from the various platforms into their
respective locations. For more information, see section 2.2

6
Sitecore Reference Storefront

2.1 Solutions and Projects


The Sitecore Reference Storefront is comprised of the following 2 solutions:
 Commerce.Dynamics.Storefront.sln
 Commerce.Server.Storefront.sln
Both solutions are located at the root of the Storefront folder. Each solution contains:
 A platform specific web storefront project
 A common project encapsulating the common functionality shared between Microsoft Dynamics and
Commerce Server.
 Platform specific and shared TDS projects.

Project Description
Storefront/AX Folder
Commerce.Storefront.ProfileDatabase.sqlproj This represents the SQL project for the Commerce Server profile
database. This creates a DACPAC file that can be used when
setting up the Commerce Server site.

For more information, please see the Setup a Commerce Server


site section of the SCpbCS Reference Storefront Setup Guide.
CSF\Commerce.Storefront.csproj Web storefront ASP.Net MVC 5 web application project.
TDSProject_Master\ TDS Project containing specific Dynamics Sitecore items or
TDSDynamicsRetails_Master.scproj overrides of existing items.
Package:
Sitecore.Reference.Storefront.Powered.by.Microsoft.Dynamics.update
Storefront/CS Folder
CSF\Commerce.Storefront.csproj Web storefront ASP.Net MVC 5 web application project.
TDSCommerceServer_Master\ TDS Project containing Commerce Server Sitecore items or
TDSCommerceServerRetails_Master.scproj overrides of exist intems.
Package:
Sitecore.Reference.Storefront.Powered.by.CommerceServer.update
Storefront/Common Folder
CommonSettings\CommonSettings.csproj Common storefront ASP.Net Web Application. This web
application is never deployed and simply provides the Common
TDS project with artifacts that will be part of the generated
update package.

The resulting assembly is not used.


Project\Common.csproj Common code library shared between Dynamics and Commerce
Server.
TDSCommon_Master\TDSCommonMaster.scproj Common TDS Project containing the base set of Sitecore items
shared between Dynamics and Commerce Server.
Package:
Sitecore.Reference.Storefront.Common.update

7
Sitecore Reference Storefront

2.2 Compiling the Sitecore Reference Storefront source code solution


The Storefront source code solution can be located on GitHub. The solution is licensed under the Apache License.
For more information, see section License and go the solution on GitHub.

Note
Before getting the source code from the GitHub project, you must make sure the line-ending option is configured
properly for your git client. TDS requires the file to end with a carriage-return + linefeed combination. Failure to
do this will result in the solution not to compile properly.

At the GIT command line, issue the following: git config --global core.autocrlf true

We have supplied a PowerShell CmdLet named UnixToWindoesEOL that can change the line-ending in case the
above command was not issued beforehand. It takes a root path and a file pattern (include filter) like “*.item” as
parameters

Furthermore, in this release a new .gitattribute was added specifically to stop GIT from transforming *.item files.

Pre-requisites

 The solution makes use of Team Development for Sitecore (TDS) from Hedgehog Development version
5.5.19.
 Microsoft Visual Studio 2015 or later is required. Note that only VS 2015 has been tested.
 .Net framework version 4.52.
 Commerce Server has been installed as the project assembly references use the GACed version of the
libraries.

For further system requirements, see section 2.1 System Requirements.

2.2.1 Compiling the Commerce Server Solution


Note
Note that dependent libraries are automatically downloaded using NuGet and stored in the package folder.
Library references will be resolved at compile time.

To install the solution:

1. Clone or download the solution from https://github.com/Sitecore/Reference-Storefront


2. Copy the following assemblies under the Lib folder of the solution root and in the specified folders:
a. All the Sitecore XP 8.2 assemblies (“/bin/sitecore/*.*”) and Social assembly
(“/bin/social/ninject.dll”) into the “\Storefront\lib\Sitecore” and “\Storefront \lib\Sitecore\social”
folders respectively
b. The Sitecore Commerce assembly (“/bin/Sitecore.Commerce.dll”) into the “\Storefront \lib\”
folder
c. The Sitecore Commerce powered by Commerce Server integration assembly
(“Sitecore.Commerce.Connect.CommerceServer.dll”) ” into the “\Storefront \lib\ folder
d. All Commerce Server assemblies are assumed to be in the GAC.
3. Open the Commerce.Server.Storefront.sln solution file.
4. Compile and build the solution

The outcome is a series of update packages that can be deployed on a SCpbCS installation.

8
Sitecore Reference Storefront
The common update package is located in: \Common\TDSCommon_Master\Package_Debug.

2.2.2 Compiling the AX Solution


Note
Note that dependent libraries are automatically downloaded using NuGet and stored in the package folder.
Library references will be resolved at compile time.

To install the solution:

1. Clone or download the solution from https://github.com/Sitecore/Reference-Storefront


2. Copy the following assemblies under the Lib folder of the solution root and in the specified folders:
a. All the Sitecore XP 8.2 assemblies (“/bin/sitecore/*.*”) and Social assembly
(“/bin/social/ninject.dll”) into the “\Storefront\lib\Sitecore” and “\Storefront \lib\Sitecore\social”
folders respectively
b. The Sitecore Commerce assembly (“/bin/Sitecore.Commerce.dll”) into the “\Storefront \lib\”
folder
c. The Sitecore Commerce powered by Commerce Server integration assembly
(“Sitecore.Commerce.Connect.CommerceServer.dll”) ” into the “\Storefront \lib\ folder
d. You must place the appropriate Sitecore.Commerce.Connect.DynamicsRetail.dll in the
“/AX/Lib/Connect.DynamicsRetail” folder.
e. All Commerce Server assemblies are assumed to be in the GAC.
3. Open the Commerce.Dynamics.Storefront.sln solution file.
4. Compile and build the solution

The outcome is a series of update packages that can be deployed on a SCpbMD installation.

The common update package is located in: \Common\TDSCommon_Master\Package_Debug.

9
Sitecore Reference Storefront

2.3 Architecture Overview


The Sitecore Reference Storefront application is based on ASP.NET MVC 5. It is assumed the reader is already
familiar with the MVC pattern making use of Controller and Views.

2.3.1 Sitecore Content Tree


The Storefront is defined in the Sitecore Experience Platform in the
following way.
The Storefront item has 2 main children. The Global item defines
configuration data used by the Storefront. Such information includes, email
content used by the EAPs, localizable strings, the carousel slides, etc…
The Home node’s children defines the pages and presentation details used
when rendering a view as well as having configuration information on the
Home node itself.
To access the configuration information, you need to make use of the
StorefrontManager class which contains a static method to return the
current CommerceStorefront object. This object has all of the necessary
properties and methods to access Storefront specific data.
As an example, if you need to access the default configured catalog name,
you would make the following call:
StorefrontManager.CurrentStorefront.DefaultCatalog.Name

Note:
The StorefrontManager resolves the CurrentStorefront via the Sitecore Site
node configuration element defined in Commerce.Storefront.config file.
The hostName attribute must be set to the web site host header defined in
IIS. Sitecore will automatically resolve the Sitecore.Context.Site property and the StorefrontManager combines
the Site.RootPath and Site.StartItem to locate the Home node for the CommerceStorefront.

2.3.2 Controller View Request and Javascript API Calls


Two types of controller calls are made. Calls that need to render a view to be presented in the browser and
Javascript API calls.
View rendering calls are made by Sitecore based on the presentation detail information defined for the targeted
Sitecore item. This means the controllers and actions are defined in Sitecore rendering items. Direct MVC calls
into the controller are still possible but the Reference Storefront makes use of Sitecore best practices in building
MVC sites hosted by the Sitecore Experience Platform.
Javascript calls are purely MVC. Sitecore does not intervien in the process and therefore it is important to
understand that no Sitecore rendering context is available during these calls. This is one of the main drivers for
the following Knockout.js topic.

2.3.3 Knockout.js
Views requirering dynamic and responsive refresh of the data make use of Knockout.js bindings to fulfill their
content. Let’s take the cart page as an example. When the Index() method of the CartController is called,
Knockout bindings and labels are setup in the cshtml view, that’s it! When the view has rendered into the
browser, a Javascript call is made to get the current cart data (in Json format) that is automatically bound to the
view.

10
Sitecore Reference Storefront
Many of the Storefront pages follow this pattern.

2.3.4 Views & Labels


Sitecore item data can be versioned and be in different languages. The Storefront makes use of this capability to
provide localized version of the views.
Let’s look at how the cart page is configured:

Clicking on the ShoppingCart item (as shown above) reveals it’s label data. The views target those fields during
the rendering process. For example, to get the Total Label the following call in made in the view:

var totalLabel = Html.Sitecore().Field("Total Label", Html.Sitecore().CurrentItem);


The above retrieves the Total Label label value in the currently selected language.

2.3.5 Controllers, Managers and Connect API Calls


Controller actions communicate with managers to perform their task. They never communicate directly with the
Connect API and do not perform any business logic. When rendering a view, the controller will get the data via
managers and pass it to the view for rendering purpose. In an API call scenario, the controller communicates with
managers to perform the task and interpret the result of the action and return Json data to the caller.
Managers provide a means of isolating controllers from business logic while offering a means of sharing business
logic across controllers. Managers are the only component that are allowed to communicate with the Connect
APIs.

Note:
Managers are automagically injected into the controller constructors via Castle Winsor.

Let’s look at the GetCurrentCart() CartController action:

public JsonResult GetCurrentCart()


{
try
{

11
Sitecore Reference Storefront
var response = this.CartManager.GetCurrentCart(CurrentStorefront,
CurrentVisitorContext, false);
CSCartBaseJsonResult cartResult = new
CSCartBaseJsonResult(response.ServiceProviderResult);
if (response.ServiceProviderResult.Success && response.Result != null)
{
cartResult.Initialize(response.Result);
}

return Json(cartResult, JsonRequestBehavior.AllowGet);


}
catch (Exception e)
{
CommerceLog.Current.Error("GetCurrentCart", this, e);
return Json(new BaseJsonResult("GetCurrentCart", e),
JsonRequestBehavior.AllowGet);
}
}

This controller action is responsible for returning the current user’s cart to the caller in a standardized Json format.
The method calls CartManager.GetCurrentCart(). In turn, the manager calls the Connect API and returns it to the
controller in the form of a ManagerResponse. The full Connect result context is accessible, allowing to inspect the
return value of the connect call for errros and messages while allowing direct access to the predominant object of
the call via the Result property.
The following is the method signature of the GetCurrentCart() method.

public ManagerResponse<CartResult, CommerceCart> GetCurrentCart([NotNull] CommerceStorefront storefront, [NotNull]


VisitorContext visitorContext, bool refresh = false)

Note:
Input into managers always take the CurrentStorefront and CurrentVisitorContext. As shown in the
GetCurrentCart() code, the base controller class supports convenience methods to retrieve the information.

The ManagerResponse exposes both the CartResult object of the Connect API call (via the ServiceProviderResult
property) as well as the CommerceCart it returned (via the Result property).
The last part of the GetCurrentCart method returns the cart in a Json format. Notice the Storefront makes use of
classes which sets up the necessary properties that are serialized into the response1.

2.3.6 HTML Caching


Sitecore HTML caching is utilized across the Storefront sites to provide a significant performance boost. For the
most part, the caching attributes are set directly on the Storefront rendering definitions.
The following are the default cache settings:

Page Rendering Parameters


Home Carousel Vary by Login
Shared ChildCategoryNavigation Vary by Url Path
Shared FooterNavigation

1 In the future the Json class initialization pattern will change. See Chapter 6 for more
information.

12
Sitecore Reference Storefront

Page Rendering Parameters


Shared LanguageSelector Vary by Query String
Shared Logo
Shared Navigation Clear on Index Update
Category ProductFacets Vary by Url Path
PDP ProductImages Vary by Url Path
PDP Productinformation Vary by Login
Vary by Url Path
Home2 ProductRecommendation Clear on Index Update
PDP RelatedCatalogItems Vary by Url Path
PDP ShareAndPrint Vary by Login
PDP SocialConnector Vary by Url Path
Shared Title Vary by Data
Shared TopBarLinks Vary by Login
Vary by User

Vary by Url Path


The Vary by Url Path is an extension to Sitecore that can be found in the Common project. The code is found in
the ApplyVaryByUrlPath.cs file. The system Cache template was extended to make the new option available to
the user in the content editor along with its specification in the Reference.Storefront.config file.

2 The cache attributes have been set


on the presentation details of the Home node since the
ProductRecommendation rendering could be shared with other pages.

13
Sitecore Reference Storefront

2.4 Catalog Presentation

2.4.1 Resolving Category and Product Presentation via the Shop Item
The Storefront makes use of the Sitecore “*” notation to provide the presetation detail information of category
and product. First let’s look at the url format generated by the Storefront.

Category: http://<domain>/shop/<displayname>_<category name>


Product: http://<domain>/shop/<displayname>_<category name>/<displayname>_<product id>

Note:
Urls are generated via the Sitecore LinkManager. The Reference Storefront Common library provides a
CatalogLinkProvider that generates the category and product urls.

The following is an example of a category link:


http://ax.reference.storefront.com/shop/Monitors_22565422994

The following shows how the Shop item are defined in Sitecore:

The first “*” under Shop defines the presentation details of the categories and the second level “*” defines the
presentation details of the products.

14
Sitecore Reference Storefront

2.5 Checkout
The Reference Storefront checkout is currently defined in a single view containing 3 tabs. Everything is controlled
via JavaScript and Knockout.js bindings.
When the checkout view is loaded, a Javascipt call is made to retrieve all of the data required to handle the
checkout process. The following CheckoutController action is called: GetCheckoutData

Note:
The returned JSON contains direct Connect, CS Connect or AX Connect entity references. This will change in the
near future to have independent JSON return classes.

The returned data contains the current cart, Shipping Options (global and per line), Payment Options and
Payment methods, etc… You can use a tool like Fiddler to intercept the calls and see what exactly is returned in
the JSON response.

2.5.1 Differences Between Dynamics and Commerce Server

Countries and Geographical Regions


Microsoft Dynamics provides the Countries and Geographical Regions to the Storefront. The Commerce Server
implementation instead makes use of data maintained within Sitecore as these are not natively supported in the
e-commerce platform. Commerce Server site terms could have been used for this. Using Sitecore instead
provides a much better user experience for adding and maintaining the information and a more obvious context
for maintaining the display names in different languages.

Shipping and Payment Options


The Connect Shipping and Payment Options (and methods) is mostly supported in the Dynamics Connector.
Native Commerce Server only supports the concept in shipping and payment methods.
The Reference Storefront for Commerce Server version makes use of Sitecore to add the concept of Shipping and
Payment Options.

15
Sitecore Reference Storefront

The Options above simply acts as a container of the Methods.


The Shipping and Payment pipelines have been adapted accordingly.

Checkout Billing Page


The Reference Storefront for Commerce Server adds an extra CheckoutController action called
SetPaymentMethods(). This allows to add the payment methods into the cart and run the Commerce Pipeline and
get some extra validation and total information.
The Reference Storefront for Microsoft Dynamics simply does nothing in the action.

16
Sitecore Reference Storefront

2.6 Multi Storefront Support


Note
The support of multiple storefront has not undergone extensive testing at this point. This will be solidified in the
near future.

The Reference Storefront support the ability to define multiple storefronts (of the same platform) in the same
Sitecore instance.
Using controller renderings instead of view renderings in one key component (see Do Controller Renderings -
Don't do View Renderings).
Controllers support base class methods that will build the path to the view based on the current storefront.

Base Controller Method Description


CurrentRenderingView Returns the storefront view path based on the name of the current action.
GetRenderingView() Given the name of the view, build a storefront view path

As metioned earlier, the Sitecore Site element is used to identify the current storefront being browsed. Different
host headers should be defined for each of the storefronts. The host header is key to identifying the current
Storefront.
Also mentioned earlier is the use of: StorefrontManager.CurrentStorefront to access Storefront specific
configuration information.

2.6.1 Setting Up a Second Storefront for Commerce Server


These notes assume:
1. Your new storefront will be called: MyStorefront
2. You will be using a Commerce Server catalog called: MyStorefront Catalog 3
3. The web site url will be: cs.reference.mystorefront.com
First we need to perform the following steps:
1. Open IIS Manager
a. Add new bindings to the Sitercore site for ports 80 and 443 with host name
cs.reference.mystorefront.com
2. Add the new host name to the HOSTS file
a. 127.0.0.1 cs.reference.mystorefront.com
3. Open [inetpub path]\Website\App_Config\Include\Reference.Storefront \Reference.Storefront.config
a. Make a copy of the Site node.
i. Set name = “MyStorefront”
ii. Set rootPath = “sitecore/content/MyStorefront”
iii. Set hostname = “cs.reference.mystorefront.com”
4. Open [inetpub path]\Website folder
a. Make a copy of [inetpub path]\Website\Views\Storefront and rename it to MyStorefront
Navigate to the Sitecore site and login
1. Open Content Editor

3 If you want, you can setup MyStorefront to use the original Adventure Works Catalog.

17
Sitecore Reference Storefront
a. Add MyStorefront Catalog to the selected catalogs under \Sitecore Commerce\Catalog
Management\Catalogs
b. Copy the existing Storefront site and rename the copy to MyStorefront
c. Update MyStorefront/Home node Catalog property to use "MyStorefront Catalog"
d. Update the MyStorefront/Home/Product catalog node CategoryDatasource property to
point to /sitecore/Commerce/Catalog Management/Catalogs/MyStorefront
Catalog/Departments
e. Update all the items under the MyStorefront/Global node to point to the MyStorefront
Storefront site
f. Update all the pages presentation details under MyStorefront/Home node (including Home)
so the rendering data sources are pointing to the MyStorefront Storefront site
2. Open the Sitecore/System/Marketing Control Panel/Engagement Plans/CommerceConnect node.
a. Copy the existing AE plans and rename them to start with MyStorefront
b. Deploy the new plans
3. Publish and index

2.6.2 Setting Up a Second Storefront for Microsoft Dynamics


Sitecore pipeline connectors will resolve the AX's channel they should "talk" to by looking at the value of the
ChannelId field defined on the Home node of the Sitecore Storefront site. There is an exception to this and it's
when indexing the Sitecore site; in this case the Channel id will be resolved by getting the Catalog's channel id
property of the products being indexed. Each AX's channel/Storefront site must has its own Transaction Service
running under the Sitecore site and all the Transaction Service endpoint names have to end in _[ChannelId],
where [ChannelId] is the corresponding AX's channel id.
What needs to be updated for existing sites, using multichannel or not
 The new Channel property added to the Home node of the Sitecore Storefront site definition with the
value of the AX's channel id corresponding with that Store.
 The Catalog taxonomy. Now when running sync each newly imported Catalog will have a ChannelId
property associated to it.
 Each Transaction Service endpoint's name, defined on the [inetpub
path]\Website\App_Config\Include\DynamicsRetail.Connectors.Services.config file, has to end on
_[ChannelId], where [ChannelId] is the corresponding AX's channel id
These notes assume:
1. Your new storefront will be called: Fabrikam
2. You will be using a Commerce Server catalog called: Fabrikam Base Catalog
3. The web site url will be: ax.reference.fabrikam.com
We are ready to start setting up the second Storefront.
1. Open IIS manager
a. Create a new application under the existing Sitecore site for Fabrikam's Transaction Service
i. Copy the content from the existing Contoso Transaction Service folder to the new
Fabrikam Transaction Service's folder
ii. Update the CommerceRuntimeConnectionString for Fabrikam's Transaction Service,
open the web.config
<add name="CommerceRuntimeConnectionString"
connectionString="Server=retail.fabrikam.com,57500;Database=RetailFabrika
mStore;User Id=ContosoFrontEnd;Password=C0nt0so123" />
iii. Update the defaultOperatingUnitNumber for the Fabrikam's Transaction Service, open
the commerceRuntime.config
<storage defaultOperatingUnitNumber="077" />

18
Sitecore Reference Storefront
b. Add new bindings to the Sitercore site for ports 80 and 443 with host name
ax.reference.fabrikam.com
2. Add the new host name to the HOSTS file
127.0.0.1 ax.reference.fabrikam.com
3. Open [inetpub path]\Website\App_Config\Include\DynamicsRetail.Connectors.Services.config file
a. Add an endpoint for each of the existing endpoints (Contoso's endpoints). The endpoint's
addresses have to point to the Fabrikam's Transaction Service and the names have to end in
"_[channelID]", where Channel ID is Fabrikam's channel id (5637145359).
4. Open Commerce Server Catalog Manager and import Fabrikam's catalog
5. Open [inetpub path]\Website\App_Config\Include\ Reference.Storefront \Reference.config
a. Make a copy of the Site node.
i. Set name = Fabrikam
ii. Set rootPath = “/sitecore/content/Fabrikam”
iii. Set domain = “CommerceUsersFabrikam”
iv. Set hostname = “ax.reference.fabrikam.com”
6. Open [inetpub path]\Website\App_Config\Security\Domains.config file and add the following domain
<domain name="CommerceUsersFabrikam" ensureAnonymousUser="false" />
7. Open [inetpub path]\Website folder
a. Make a copy of [inetpub path]\Website\Views\Storefront and rename it to Fabrikam

Now we are ready to start setting things up in Sitecore. Navigate to the Sitecore site and login
1. Open Content Editor
a. Add Fabrikam's catalog to the selected catalogs under \Sitecore Commerce\Catalog
Management\Catalogs
b. Copy the existing Storefront site and rename the copy to Fabrikam
c. Update Fabrikam/Home node Catalog property to use "Fabrikam Base Catalog"
d. Set the Fabrikam/Home node Channel property to Fabrikam's channel id (5637145359)
e. Update the Fabrikam/Home/Product catalog node CategoryDatasource property to point to
/sitecore/Commerce/Catalog Management/Catalogs/Fabrikam Base
Catalog/Departments/22565426194
f. Update all the items under the Fabrikam/Global node to point to the Fabrikam Storefront site
g. Update all the pages presentation details under Fabrikam/Home node (including Home) so the
rendering data sources are pointing to the Fabrikam Storefront site
2. Open the Sitecore/System/Marketing Control Panel/Engagement Plans/CommerceConnect node
a. Copy the existing AE plans and rename them to start with Fabrikam
b. Deploy the new plans
3. Publish and index

19
Sitecore Reference Storefront

2.7 Security

2.7.1 HTTPS Implementation


The Storefront protects sensitive pages/data by forcing HTTPS in certain area of the web site. Once a user is in
HTTPS, he/she will remain in HTTPS for the remainder of the session. All API calls made by secured pages are also
secure and run in the same HTTPS context as the browser.
Pages deemed to execute in HTTPS are derived from a Storefront page template template called: Secured Page.
Any page that inherits from this template will automatically be redirected to HTTPS if necessary. This is achieved
via the SecuredPageProcessor of the < httpRequestBegin> pipeline.
As of version 8.2.577.2, all pages have been inheriting from template Secured Page and thereby forcing all pages
to use HTTPS protocol. Enforcing HTTPS on all page requests is becoming more of a standard nowadays. With the
improvements in hardware, the overhead of encrypting data sent over the internet is negligiable.

Self-Signed Certificates
For development purpose, you will need to setup a self-signed certificate if you desire to run the Storefront in
HTTPS. The following link will bring you to a Microsoft page that shows you how this is done:
https://technet.microsoft.com/en-us/library/cc753127(v=ws.10).aspx

Disabling HTTPS
The Sitecore.Storefront.config file contains a settings value if you need to disable HTTPS for development
purpose.

<settings>
<setting name="Storefront.EnforceHTTPS" value="true"/>
</settings>

Simply set the value to false and the enforcing of HTTPS will be disabled.

Note
The AX Checkout control does not yet understand this flag and will currently always enforce HTTPS.

2.7.2 Controller Method Attributes

API Controller Methods


API controller methods accessed via Ajax calls should sport the following attributes:

Attribute Description
HttpPost Base on security best practices, all Ajax API methods should be done via HTTP
POST instead of GET. Even for method that simply return values.
Authorize This should be used when the Ajax call needs to be performed by an authorized
user. Anonymous calls are automatically rejected.

20
Sitecore Reference Storefront

Attribute Description
ValidateJsonAntiForgeryT By validating the anti-forgery token, we protect the site from Cross Site Request
oken Forgery. For more information, please follow this link:

https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)
OutputCache(NoStore = This ensures the results are not cached by the browser, server or any other device.
true, Location =
OutputCacheLocation.No https://www.owasp.org/index.php/Session_Management_Cheat_Sheet#Web_Co
ne) ntent_Caching

21
Sitecore Reference Storefront

2.8 Miscellaneous

2.8.1 ProductItemResolver
The ProductItemResolver processor of the <httpRequestBegin> pipeline is used to resolve the current Sitecore
catalog item (Category or Product) by examining the Url and the defined route data. When a Catalog item is
identified, it sets the following ISiteContext parameters:
 CurrentCatalogItem
 UrlContainsCategory
This allows the Reference Storefront code to know when the current url represents a CatalogItem.

2.8.2 CatalogLinkManager
In conjunction with the Sitecore LinkManager.GetDynamicUrl() method, the CatalogLinkManager is responsible
for generating all of the catalog item urls. The following shows how it is specified in the
Reference.Storefront.config file:

<linkManager defaultProvider="sitecore">
<patch:attribute name="defaultProvider">commerce</patch:attribute>
<providers>
<add name="commerce"
includeFriendlyName="true"
useShopLinks="true"
includeCatalog="false"
type="Sitecore.Reference.Storefront.SitecorePipelines.CatalogLinkProvider,
Sitecore.Reference.Storefront.Common"/>
</providers>
</linkManager>

Note
The Sitecore attributes are not shown in the XML configuration as we only describe the attributes that are specific
to the Reference Storefront.

Parameter Description
includeFriendlyName Tells the link manager to include the product or category display name as part of the
url.
useShopLinks When true, the link manager will generate urls that fall under the “shop” item of the
Storefront Home item.

When false, it generates urls that either fall under the Category or Product items of the
Storefront Home item.
includeCatalog When true, the catalog name is added as part of the url.

Direct Links
The Reference Storefront allows direct links to items found under the “Product Catalog” item of the storefront
Home item. When the CatalogLinkManager detects direct links, it will end up generating direct links
automatically. For example, if a direct link is used to browse a category, all products within that category will be
direct links as well. When a direct link is used on a product, the product recommendations will be direct links.

22
Sitecore Reference Storefront
Note
If you rename the “Product Catalog” storefront Home item, you will need to change the code to recognize the
new name. The constant is found in ProductItemResolver.NavigationItemName. Renaming this will
automatically adjust the Route table.

2.8.3 Map Credentials


The credentials required by the pick up in store map displayed in the Microsoft Dynamics AX version of the
storefront are configured on the home node of the storefront. This can be easily edited directly from the content
editor.

2.8.4 Category and Product Visited Renderings


The Category and Product Visited renderings are used to respectively trigger the Category and Product Visited
page events.
For performance reasons the Category and Product Information renderings are cached and Javascript is used to
update the stock information. The separate renderings for Category and Product Visited allow us to keep the
caching enabled on the Category and Product Information and permit us to register these important events.

2.8.5 Product Recommendations


The product recommendation of the Home page is populated via the ProductRecommendation rendering defined
on the Home item’s presentation details.
Figure 1 - Product Recommendation Presentation Details

23
Sitecore Reference Storefront
The control properties define a Data Source that points to an item (Recommended Products) that in turn define
the Named Searches to be applied. Two types of named searches are supported:
1. Search based
2. Static
A Search based named search defines the Sitecore query that will be applied to locate the products to be
displayed.

Figure 2 - Search Based Named Search

A Static named search statically defines the products to be displayed.


Figure 3 - Static Named Search

Notes
The current version of the system does not validate that only catalog items (category & product) can be selected.
If you add any other type of item, the Reference Storefront will fail to render the home page.

24
Sitecore Reference Storefront

Chapter 3 GitHub Repository

The source code is located on GitHub: https://github.com/Sitecore/Reference-Storefront

3.1 Branching Strategy


The Reference Storefront project has two repositories. An internal TFS repository and a publically accessible
GitHub repository. This article focuses on the branching strategy of the public GitHub repository.
The GitHub repository is not used as the main development repository but instead acts as a means of distributing
our source code to external developers and have external Contributors to the project (via Forks and Pull
Requests). When pull request are accepted, they will be added to the TFS repository and will be available in the
next release.
For these reasons, we will adopt a simple branching strategy that will permit us to version our code and make
version specific changes (bugs, etc…) if necessary in the current or any previous version of the product.
The main master branch will always have the latest version of the Reference Storefront code along with a version
specific branch with the same code. New code is only uploaded to GitHub at the end of a release since the main
development is done in TFS. When new code is uploaded, it will be branched immediately to the new version.

Branch version is in the following format: /releases/X.X.X/master

The master branch always has the latest code. In the above example, master is the same as
releases/8.0.0/master. Bug fixes to previous version are made in the version specific branch. These changes are

25
Sitecore Reference Storefront
never merged into master. Bug fixes to the current version are done in the version specific branch and merged
into master.

26
Sitecore Reference Storefront

Chapter 4 Do’s and Dont’s

4.1 Do Controller Renderings - Don't do View Renderings


View renderings require hard coded paths to the view being required to be rendered by a controller. Instead, use
Controller Renderings as both Storefronts have multi-shop support. That is, based on the given shop name, it will
pick a difference storefront view root directory.

4.2 Use View Models Instead of Domain Objects


View Models should be passed into the view rendering process instead of native connector entities. These views
should expose an independent view of the data that does not expose any native entity. This creates a clean
separation between the connectors and the storefront and therefore allowing to share the implementation across
multiple external commerce system.
See Error! Reference source not found..
Views and its models should reside in the Common library and the initialization should be done in the Storefront.

4.3 JSON Responses Must Not Contain Domain Objects


Same reason as the View Models section above.

4.4 Respect the Controller, Manager, Connect API Pattern


This was mentioned earlier in the document and is worth metioning it a second time. Respect the pattern,
manager’s allow to isolate the business logic and can be easily shared. Controllers manage the request and
formats the output, managers take care of the business logic and call the Connect API and return the response.,
Connect calls the external commerce system.

27
Sitecore Reference Storefront

Chapter 5 Microsoft Dynamics Inventory Indexing

The Sitecore Reference Storefront powered by Microsoft Dynamics is configured out-of-the-box


to make calls to the AX Connector Inventory Service to retrieve product stock information rather
than use the stock information maintained within the index file.

To improve indexing performance, you may want to remove the indexing of the product
inventory information. This can be done by removing the pipeline processor defined in the
<commerce.inventory.stockStatusForIndexing> pipeline.

This can be achieved by using a standard <patch:delete> element in one of the existing Sitecore
Reference Storefront configuration file.

Here is an example of how this is done:

<commerce.inventory.stockStatusForIndexing>
<processor
type="Sitecore.Commerce.Connect.DynamicsRetail.Pipelines.Inventory.StockStatu
sForIndexing, Sitecore.Commerce.Connect.DynamicsRetail">
<patch:delete/>
</processor>
</commerce.inventory.stockStatusForIndexing>

28
Sitecore Reference Storefront

Chapter 6 Indexed and Live ECS Price Lookup

This section refers to how the Reference Storefront looks for Product prices when displaying
product lists either on the category page or on the related product section of the Product Detail
Page (PDP). From an API perspective, we focus on the GetProductBulkPrices API configuration.

The index may provide a significant performance boost in some cases when retrieving and
displaying lists of products.

The PDP always looks up the current product price via the live Connect API.

The price lookup strategy is configured as part of the Sitecore.Reference.Storefront.config file.

6.1 Commerce Server


By default, the Commerce Server version of the storefront uses the index. If you locate the
<commerce.prices.getProductBulkPrices> section you will notice two possible configurations.
The following provides the exact configuration for each price access:

6.1.1 Direct Access


<commerce.prices.getProductBulkPrices patch:source="Sitecore.Commerce.Prices.config">
<!-- Direct Price Access from the CS Catalog items -->
<processor type="Sitecore.Commerce.Pipelines.Prices.GetProductBulkPrices.GetProductBulkPrices,
Sitecore.Commerce">
<patch:attribute name="type">
Sitecore.Reference.Storefront.Connect.Pipelines.Prices.GetProductBulkPrices,
Sitecore.Reference.Storefront.Powered.by.CommerceServer</patch:attribute>
<param ref="entityFactory"/>
<UseProductBasePriceAsVariantPrice>false</UseProductBasePriceAsVariantPrice>
</processor>
</commerce.prices.getProductBulkPrices>

When the UseProductBasePriceAsVariantPrice flag is set to <true>, the variant price will be the one defined at the
product level. When set to <false>, the actual variant price is returned.

6.1.2 Index File Access


<commerce.prices.getProductBulkPrices patch:source="Sitecore.Commerce.Prices.config">
<!-- Price information retrieved from the index file. -->
<processor type=
"Sitecore.Commerce.Pipelines.Prices.GetProductBulkPrices.GetProductBulkPrices,
Sitecore.Commerce">
<patch:attribute name="type">
Sitecore.Reference.Storefront.Connect.Pipelines.Prices.GetProductBulkPricesFromIndex,
Sitecore.Reference.Storefront.Powered.by.CommerceServer</patch:attribute>
<param ref="entityFactory"/>
</processor>
<processor type=
"Sitecore.Commerce.Connect.CommerceServer.Catalog.Pipelines.GetProductBulkPrices,

29
Sitecore Reference Storefront
Sitecore.Commerce.Connect.CommerceServer">
<patch:delete/>
</processor>
</commerce.prices.getProductBulkPrices>

The above will use the version of the GetProductBulkPrices API that retrieves price information from the index.
One more configuration must be added to indicate that we need to index the variant pricing. The following must
be added to the <fields> section of the Reference.Storefront.Index.Lucene.config file.
<field fieldName="VariantInfo"
returnType="string">Sitecore.Reference.Storefront.Search.ComputedFields.VariantInfoComputedField,
Sitecore.Reference.Storefront.Powered.by.CommerceServer</field>

6.2 Microsoft Dynamics


The Microsoft Dynamics version of the Reference Storefront is configured by default to look up price information
live in Dynamics AX.
To configure the price access from the index, the following must be added to the <processors> section of the
Reference.Storefront.config file:

<commerce.prices.getProductBulkPrices patch:source="Sitecore.Commerce.Prices.config">
<processor type=
"Sitecore.Commerce.Connect.DynamicsRetail.Pipelines.Prices.GetProductBulkPrices,
Sitecore.Commerce.Connect.DynamicsRetail">
<patch:attribute name="type">
Sitecore.Reference.Storefront.Connect.Pipelines.Prices.GetProductBulkPricesFromIndex,
Sitecore.Reference.Storefront.Powered.by.Microsoft.Dynamics</patch:attribute>
<param ref="entityFactory"/>
</processor>
<processor type=
"Sitecore.Commerce.Connect.CommerceServer.Catalog.Pipelines.GetProductBulkPrices,
Sitecore.Commerce.Connect.CommerceServer">
<patch:delete/>
</processor>
</commerce.prices.getProductBulkPrices>

One more configuration must be added to indicate that we need to index the variant pricing. The following must
be added to the <fields> section of the Reference.Storefront.Index.Lucene.config file.
<field fieldName="VariantInfo"
returnType="string">Sitecore.Reference.Storefront.Search.ComputedFields.VariantInfoComputedField,
Sitecore.Reference.Storefront.Powered.by.Microsoft.Dynamics</field>

30
Sitecore Reference Storefront

Chapter 7 Inventory Stock Status

By default, both Commerce Server and Microsoft Dynamics AX versions of the Storefront
retrieve the stock status information from the index.

This can be easily configured by editing the home item of the storefront in the content editor as
shown below:

31
Sitecore Reference Storefront

Chapter 8 Leveraging Sitecore Features

8.1 Languages and Language Fallback


The Reference Storefront is available in all the following tier-1 languages:
1. English
2. Danish
3. German
4. Japanese
The language files are downloadable from the release page of the GitHub project.

Note
French is not defined as Tier-1 language in Sitecore and hence has no corresponding language file for download,
but it is still automatically created by CS Connect upon site startup.

As of Sitecore version 8.1, language fallback is natively supported. For more information on this new feature,
please follow this link:
https://doc.sitecore.net/sitecore_experience_platform/language_fallback/language_fallback

The Reference Storefront has been fully tested to make sure item level language fallback is fully supported. To
enable the feature, the Reference.Storefront.config file needs to be modified in the following manner:

<sites>
<site name="storefront" patch:before="site[@name='website']"
virtualFolder="/"
physicalFolder="/"
rootPath="/sitecore/content/storefront"
startItem="/home"
database="web"
domain="extranet"
allowDebug="true"
cacheHtml="true"
htmlCacheSize="10MB"
enablePreview="true"
enableWebEdit="true"
enableDebugger="true"
disableClientData="false"
requireLogin="false"
hostName="cs.reference.storefront.com"
contentLanguage="en"
content="master"
language="en"
ItemNotFound="/error/404"
enableTracking="true"
enableItemLanguageFallback="false"
enableFieldLanguageFallback="false"
/>

32
Sitecore Reference Storefront
<site name="shell">
<patch:attribute name="enableItemLanguageFallback">true</patch:attribute>
</site>
<site name="website">
<patch:attribute name="enableItemLanguageFallback">true</patch:attribute>
</site>
</sites>
The enableItemLanguageFallback attribute of the “storefront” site enables the feature in the storefront, while the
“shell” & “website” enables it in the content editor.

33
Sitecore Reference Storefront

Chapter 9 Performance

The Reference Storefront has been tuned to offer maximum performance under load. This has
been achieved through the various techniques described below.

9.1 Rendering Caching


Many of the renderings are being cached to offer maximum performance. While this provides a performance
boost it increases the memory consumption of the site. You might wish to further tune the site to handle your
own scenarios and achieve the perfect balance between caching and memory utilization.

9.2 New Caching Option


One new caching option has been introduced in the Reference Storefront:
 Vary by Url Path

9.2.1 Vary by Url Path


Allow to cache rendering HTML based on the Url path. This cache key includes:
 Site name
 Language
 Absolute Uri
 Rendering ID

By including the language, this allows to cache renderings by including the currently selected user language. Very
useful for sites operating in multiple languages. For an example, see the ProductInformation storefront rendering.

9.3 Request Caching


Sitecore allows you to control the web page layout and content via item Presentation Details. The Reference
Storefront adheres to the same principle therefore offering a developer experience that Sitecore developers are
accustomed too.

In this scenario, it is possible for more than one rendering of the same presentation detail to request similar
information. The Reference Storefront makes use of request caching to make sure that queries for catalog items
are only performed once per http request, therefore does not penalize site performance over granularity of the
presentation detail controls.

34
Sitecore Reference Storefront
Figure 4 - Product Presentation Details

In the example product presentation details shown above, the controls boxed in red all share the same
information. Request caching is used to make sure only a single query is performed to retrieve the product
information.

9.4 Mini Cart Caching


Fetching the mini cart on every page refresh is an expensive operation as it appears on most of the Reference
Storefront pages. In order to optimize the cart retrieval process, the fetching of the cart has been optimized by
fetching it from the ECS only when it has been modified.

This is done by using a cookie that acts as an indicator telling the web server when it is ok to retrieve the cart from
the ECS. When the cart is modified, the cookie is removed and on the next call for the mini cart, the cart is
retrieved and the cookie is re-created.

9.5 Stock Status and Product Prices via Index Files


Chapter 6 and 7 show how to configure both the CS and AX versions of the Reference Storefront to make use of
index files when the web site requests stock status and product pricing information.

In some cases, using the index file can provide an important performance boost over calling the API which
perform direct lookups in the ECS. You need to be aware that if these options are enabled, your indexing time will
increase as extra time will be required to save this information in the index.

35
Sitecore Reference Storefront

9.6 Read-only session state support per controller method for improved
performance
By design, ASP.NET session state is set to Required by default to allow session content to be both read and
updated (read-write). In the Sitecore Experience Platform (SXP), both contacts and interactions are loaded into
session state, which means that any attempt to update the contact or add experiences to the interaction requires
write access. When multiple requests try to access the session content concurrently, they will by default be
queued up as only one thread can update the session content at any given point in time.
Modern websites load a page asynchronously using AJAX technology as part of improving the user experience. By
returning the minimal amount of HTML immediately, it’s possible for the browser to partially render the page at
the earliest possible time. Pages that involves retrieval of data will be able to partially render the page without
having to wait until all data have been retrieved and thereby provide a rapid response to the visitor. By executing
multiple requests in parallel it will potentially speed up the retrieval of data and the total page load time will be
decreased. In the Reference Storefront, a page like My Account, which gives an overview of the visitor’s order
history, active wish lists, customer addresses and loyalty programs, the content for the individual sections are
requested in parallel as individual AJAX calls. Including the main page, mini-cart, and VisitorIdentification
(required SXP specific call), that amounts to 7 simultaneous HTTP requests for the page to fully load the HTML
and data. If images, CSS and scripts are included, it amounts to more, but these artifacts are usually cached both
in the browser and at the IIS and presents less of a problem.
HTTP requests that are not updating the session, including not updating the contact or interaction through the
use of the SXP API, can be executed with session state set to read-only, thereby allowing the requests to be
unblocked and executing in parallel to improve page load time and page throughput.
The effect is most apparent in case of long running AJAX requests like retrieving order history, active wish lists
etc. which retrieves data from the external commerce system.
In ASP.NET MVC it’s possible to set the session state per controller. By using an IOC container like Windsor-Castle
and by overriding method GetControllerSessionBehavior for setting SessionStateBehavior, it’s possible to
set it for each controller method being called. The advantage is a more fine grained configuration without having
to split up controller methods that logically belongs together.
In version 8.2, a new setting “Storefront.ReadOnlySessionStateBehaviorEnabled” has been introduced in file
“/App_Config/include/Reference.Storefront/Reference.Storefront.config” with default value set to false:

<setting name="Storefront.ReadOnlySessionStateBehaviorEnabled" value="false"/>

In version 8.2 of the storefront, a new attribute StorefrontSessionState has also been introduced
[StorefrontSessionState(System.Web.SessionState.SessionStateBehavior.ReadOnly)]
If a method is augmented with the attribute having SessionStateBehavior set to ReadOnly, the method gets
called with read-only access to session content, meaning it can be executed in parallel. The rest of the controller
methods gets the default access.

36
Sitecore Reference Storefront
As example, the controller Sitecore.Reference.Storefront.Controllers.AccountController contains
method AddressList, which is augmented with the attribute:
/// <summary>
/// Address Book in the Home Page
/// </summary>
/// <returns>The list of addresses</returns>
[HttpPost]
[Authorize]
[ValidateJsonAntiForgeryToken]
[OutputCache(NoStore = true, Location = OutputCacheLocation.None)]
[StorefrontSessionState(System.Web.SessionState.SessionStateBehavior.ReadOnly)]
public JsonResult AddressList()
{

37