Sunday, November 26, 2017

Adventures with Sitecore Commerce 8.2.1

Now I'll start by saying I'm am nowhere near the developer skill level of MVPs like  @mike_i_reynolds  or @jammykam or even @ryanbaileynz, but I think I can make a fairly decent job of deploying and configuring Sitecore solutions. Having recently installed Sitecore Commerce 8.2.1 five times in a row I'd thought I'd share some tips for those that are going to have a crack at it for the first time. 

The Steps 

Create a local account

 While CSFRuntime user may be ok for development deployments, if you are setting up on a multi-server environment or heading to production, you'll need more granular security accounts to provide an auditable separation of privileges.  This is described here in the Devops guide :

Big important note, these accounts need to installed on a common domain controller across all servers (CM, CD, SQL) 

Install ASP.NET Core and related software

  1. Download and install ASP.NET MVC 4 (available at For more information on MVC, go to Set up Visual Studio to work with Sitecore MVC.
Note: Make sure that the installed version of the .NET Framework is the DevPack/SDK edition, not the Runtime edition. The dotnet publish command used later  will fail if only the Runtime edition is installed.
  1. Download and install .NET Core 1.0.3 SDK Preview 2 build 3156.
No worries 
  1. Download and install .NET Core Windows Server Hosting 1.x.x.
No worries 
  1. Optionally, download and install .NET Core 1.0.1 Visual Studio 2015 Tooling Preview 2. This is only required for a development environment.
  2. Download and install Microsoft Web Deploy 3.6 (the 64 bit file is available at: WebDeploy_amd64_en-US.msi).
No worries
  1. Download and install Microsoft HttpPlatformHandler v1.0 (the 64 bit file is available at httpPlatformHandler_amd64.msi).
No worries 
  1. Restart the server, or open a command prompt and execute the iisreset command to apply the changes to the system path.

Install Sitecore Experience Platform

This should be a no-brainer but careful with this instruction: 

After you have installed Sitecore XP, change the Sitecore web site's application pool identity to .\CSFndRuntimeUser.

If this account does not have database permissions on your Sitecore databases you will run into publishing issues

Also when assigning app pool identities take care here: 

The local account must be prefixed with .\ or MachineName\, otherwise the Initialize-CSSite command (executed later in this workflow) cannot grant proper permissions for Commerce Server databases.

When using a domain controller use the fully qualified domain name i.e. MyDomain\AccountName

Additional Sitecore XP configuration

If you are using a different domain make sure you: 

Change the hostName in Website\App_Config\Include\Reference.Storefront\Reference.Storefront.config

Also remember you have done this, it becomes important later.

Don't forget you'll need a SSL cert, either a domain wildcard or self signed since no one runs on http anymore and certainly not on a commerce site. 

Install Commerce Server

This part contains virtually no tricky bits  and should be a breeze, note the port assignment though 1004

Install Sitecore modules

This is done through the installation wizard and while it may take a while, I had no issues 

Install Sitecore update packages

Again problem free on all installs, clearing the event que on the master database timed out (Azure VM) but everything installed eventually, can take a fair amount of time as well so don't panic.

Also the last package 
will most likely throw an error when it finishes (see below) - you are safe to ignore it and carry on with your installation, we will fix it later 

Let the Powershell fun begin!!

As long as you fill in the script values correctly this should be easy too, i.e. 

New-CSWebService -Name "CFSolutionStorefrontsite" -Resource Catalog -IISSite "CSServices" -AppPool "CSServices" -Identity 'CSFndRuntimeUser' -Password 'YourPassword'

Update the Commerce Server Profile Schema

Create encryption keys for the CFSolutionStorefrontSite.

This bit is easy, just make sure you run the command in the directory where the ProfileKeyManager.exe

i.e.  C:\Program Files (x86)\Commerce Server 11\Tools

Update the Commerce Server Profile schema by deploying the Commerce Storefront Profile Database DAC package, using the following command. 

This bit is not so easy as it requires permissions on the database to match the username password the process is being run by. Admittedly it was late at night but this one confounded me for a bit. 

The executable  SqlPackage.exe is required and it's location varies depending on your set up so you will have to find it and make sure the path to the .exe, the package and the database server are both correct. 

"C:\Program Files (x86)\Microsoft SQL Server\110\DAC\bin\SqlPackage.exe" /Action:Publish /SourceFile:".\Database\Profiles\Commerce.Storefront.ProfileDatabase.dacpac" /TargetDatabaseName:CFSolutionStorefrontSite_profiles /TargetServerName:"" 

In the end I went for jumping onto the SQL server and running it through the command line there. This DACPAC is very important as it sets up the YourStoreName_CommerceProfiles table correctly. 

Also don't be like me and try running it through SQL Management Studio as a Data Tier Update, it will destroy your tables, fortunately years of bumbling my way through things have taught me the value of BACKUP FIRST, BACKUP FIRST BACKUP FIRST !

If you got the error at the end of installing 
Now is the time to go back to the UpdateInstallationWizard and do it again, no errors this time buddy!

Compile the Commerce Engine

The only trick here is making sure that the installed version of the .NET Framework is the DevPack/SDK edition, not the Runtime edition. The dotnet publish command  will fail if only the Runtime edition is installed.

The publish command will create a folder called Deplopy on you C: Drive which you will copy to the CommerceAuthoring folder specified in your new IIS site. 

Bootstrap and initialize the Commerce Server environment

Now let the fun with JSON configuration files begin

These three commands 

Rely on these JSON files in your commerce authoring site: 


And all the json files found here: 


Major tip: All the configuration settings must be correct or you will have issues, including but not limited to 

Bad Gateway 

Currency set ‘{4B494292-598E-4A61-A156-D7501F7953ED}’ was not found

Things to check: 

  • Your database strings are correct throughout (Notepad ++ search and replace will save you time) 

 "$type":  "Sitecore.Commerce.Plugin.SQL.EntityStoreSqlPolicy, Sitecore.Commerce.Plugin.SQL",
                                         "TrustedConnection":  true,
                                         "UserName":  "xxxxxx",
                                         "Password":  "XXXXXX",
                                         "Server":  "MACHINENAME\SQLEXPRESS",
                                         "Database":  "SitecoreCommerce_SharedEnvironments",
                                         "AdditionalParameters":  "",
                                         "ConnectTimeout":  120000,
                                         "CleanEnvironmentTimeout":  120000 

  • Your Sitecore admin account settings are correct if you are not using the defaults
  • Your host is correct if you have changed it as mentioned above 

  "$type":  "Sitecore.Commerce.Plugin.Management.SitecoreConnectionPolicy, Sitecore.Commerce.Plugin.Management",
                                         "Host":  "",
                                         "SitecoreDatabase":  "master",
                                         "UserName":  "admin",
                                         "Domain":  "sitecore",
                                         "Password":  "b"

Make sure you are thorough with all the JSON files - if either of these fail you will have to go and clear out the  tables before you can run them again. 

DELETE FROM tablename

Also if you do have to run them again, restart the CommerceAuthoring site

Rerun the http://localhost:5000/commerceops/Bootstrap() command to read in any config changes you have made 

Then re run the two commands 

At this stage you should be breathing vast sighs of relief and be as happy as a sand boy

Final configuration

Don't forget to carefully merge the new settings into your web config and watch out for duplicates

Also note one of the merge files is merged into the /Views web.config, I mean you'd have to be half asleep to try and put them anywhere else wouldn't you ....

Reindex the Sitecore and Commerce Server indexes

Check you have sorted your index config before this especially is you are running Solr

Last thoughts 

Bring on Commerce 9 even if it does have JSON configuration , its uses the new Sitecore Installation Framework so it's just going to keep getting easier: 

Sitecore Commerce Server profile definitions not found

Sitecore Commerce catalog web service error

Also if your Commerce Server Manager wont let you view Profile definitions, make sure that you have added localhost into your trusted sites using IE Internet options, silly old enhanced security !

Sitecore Authorization Manager needs to have your runtime accounts assigned to the administrator roles of the Catalog and Profile web services, usually done as part of the install but can be checked by running azman.msc

If the authorization stores are missing add them from the 2 web services folders





Other Resources:  #ecommerce

Me on Twitter:  @NZsitecore