Essential Settings and Policies in Sitecore Commerce 9

Overview

This post is a practical high-level walk-through on essential Commerce configuration settings. This is not a detailed , but rather a quick technical guide explaining , something we had to deal with (and document for our clients) on a regular basis. Detailed documentation can be found in Commerce Engine Configuration, Commerce Connect Configuration and Commerce Engine and Storefront configuration settings sections on doc.sitecore.com and the following references below.

Postman Environment Configuration

• • Postman is a recommended tool for manually interacting with Commerce APIs. To get started you'll need to import environment and API collections into your Postman app (ere and here are a couple of more detailed walkthroughs on setting up Postman to work SXC9). One important thing to remember is that you may need to tweak Environment settings in Postman to point to your target Commerce Engine and Identity Server instances. Here's how:

    • Select the target environment and click on the settings button 

    • Make sure the values of ServiceHost, OpsApiHost, AuthoringHost, MinionsHost, and ShopsHost are properly configured to point to your target environment(s). ServiceHost and AuthoringHost usually point to the same instance n case of on-premise install on a development workstation, your Authoring, Minions, Ops, and Shops can all point to the same instance like in the below example (this will not be the case with Azure install and/or on-premise QA/UAT/PROD installations).

    • Configure SitecoreIdServerHost to point to your Sitecore Identity Server instance

    • Configure Sitecore username and password to be used for API calls from Commerce Engine to Sitecore CM. This doesn't need to be an admin account configuring role on a given account should be enough. 

Sitecore Commerce 9 Configuration Files

Configuration Bootstrap Operation

• • One thing to keep in mind is that Commerce Engine is actually reading most of its configuration and policy settings from its Global database, ignoring most of what is in its configuration files, except when the configuration is loaded into Global DB during Bootstrap operation. Whenever changes are made to Commerce configs or policies then Bootstrap operation need to be executed to update records in the Global (configuration) database. Refer to this article on doc.sitecore.com for more details on SXC9 bootstrap operation.

    SXC9 usually installs multiple application roles: Authoring, DevOps, Minions, and Shops are separate instances, running the same code and configured very similarly to each other with just a few important differences. More details can be found in Sitecore documentation following links in this post or the purpose of this walkthrough I need to mention that during Bootstrap operation on on-premise installation (standalone/VM/development workstation) config settings by default would be retrieved from your authoring environment and in case of SXC running as Azure App Services configs would usually come to DevOps.

Essential Commerce Engine Configuration Files and Policies

Configuration Files

• • All SXC Configuration files and policies can be found under /wwwroot path on each CE instance (remember there are four Commerce Engine roles plus a couple more we're going to cover below). There are two main configuration files to look for: [Your CE Instance]/wwwroot/config.json and [Your CE instance]/wwwroot/bootstrap/bootstrap.json.

./wwwroot/config.json

• • This is the top-level configuration file, which contains the AppSettings section for Commerce Engine (ASP.NET Core) app plus logging and security configurations. Below are details on some of the settings to look for:

    • EnvironmentName: as was mentioned above those four Commerce Engine roles run the same code and have almost identical configurations. This is one of the few settings that need to be set differently on different roles. Unless you decided to create your own environment, out of the box CE comes with Habitat and AdventureWorks environments, so the value of this setting need to be set according to web app role, e.g. HabitatAuthoring, HabitatMinions, HabitatOpsApi and HabitatShops
    • AllowedOrigins: Clients making calls to any given CE instance need to be included in this list of allowed origins (or their calls will be rejected)
    • AntiForgeryEnabled: highly recommended to set to true on production, but can be set to false for debugging purposes or/and to allow calls from Postman
    • ApplicationInsights: Azure App Insights configuration app Insights is Microsoft's recommended logging solution and proper alternative to file-based logs
    • Logging and Serilog: Logging configuration for file logs, which (when this is enabled) can be found under [Your Application Root]\wwwroot\logs
    • Certificates: Sitecore CMS (both CM and CD) communicates with Commerce Engine via Commerce Connect, in which case certificates are used for authentication. Certificate thumbprint values should match in this setting on the Commerce Engine end and in certificateThumbprint node of App_Config\Include\Y.Commerce.Engine\Sitecore.Commerce.Engine.Connect.config file on Sitecore CM and CD instances.

./wwwroot/bootstrap/Global.json

• • This config file controls some of the main aspects related to the application startup/bootstrap process. Here are the main settings to look for:

    • Policies/..EnvironmentBusinessToolsPolicy/EnvironmentList: List of all available Commerce environments. You may choose to create custom ones and/or remove unused environments, in which case this list will need to be modified.

    • SitecoreConnectionPolicy: Host, connection, and credentials for Commerce Engine to be able to communicate with your Sitecore CM instance.

Essential Commerce Engine Policies

• • Sitecore Commerce policies are meant to be used as settings/rules for various Commerce Entities. Each Commerce Entity has "Policies" collection property with one or more policies in it. More information on SXC9 policies can be found here.

Here is the list of OOTB policies we had to change the most often:

Plugin.[your environment name].CommerceAuthoring.json, Plugin.[your environment name].CommerceMinions.json and Plugin.[your environment name].CommerceShops.json

• • OOTB SXC 9 installation comes with two sets of policies - one for "Habitat" and one for "AdventureWorks" environments (so in this case "Habitat" and "AdventureWorks" will be in place of [your environment name] in the above files). These policies each contain a set of child policies to control various runtime aspects of configured environments running in different application roles. Authoring, Minions, and Shops are usually configured similar to each other, but there is some differences cache duration is much longer on shops vs authoring, Minions would have minions-related settings that other web apps won't). When you choose to create your custom environments, these files will need to be properly created, configured, and referenced from your \wwwroot\bootstrap\Global.json". This blog post has more details on how to create custom environments in SXC9.

PlugIn.Search.Solr.PolicySet-1.0.0.json

• • Solr connection info (when running Solr on your local machine make sure to add "/solr" at the end of "SolrUrl", e.g. "https://localhost:8983/solr"

PlugIn.Minions.PolicySet-1.0.0.json

• • Lists Commerce Minions running on a given instance. Minions are like services or cron jobs, executed on a regular basis. All minion jobs would usually run on a dedicated "Minons" web role. Any Minion job specified in this policy would wake up every XX seconds and process items from a given list in batches. Below are the minion configuration parameters:

    • ListToWatch: Commerce List of entities to watch for, once processed, entities would be disassociated from a given list
    • FullyQualifiedName: Minion's implementation class
    • ItemsPerBatch: How many items to process in each batch
    • SleepBetweenBatches: number of seconds to wait before processing the next batch of items
    • Entities: types of Commerce Entities to process

PlugIn.CatalogIndexing.PolicySet-1.0.0.json

• • SXC9 maintains its Catalog, Customers, and Orders indexes in Solr indexing jobs are performed by minions called FullIndexMinion and IncrementalIndexMinion. This policy configures how indexing minions will perform their job on given Commerce entities. OOTB indexing configuration might be sufficient for your project, but if not then feel free to refer to this blog post for details on how to include custom fields into Commerce index.

Plugin.SQL.PolicySet-1.0.0.json

• • Connection info for your SXC "Shared" database, where Commerce (entities are persisted). The SXC "Global" DB (where SXC configuration settings and policies are persisted) is configured in a different SitecoreConnectionPolicy, which can be found in your \wwwroot\Global.json config.

SXC9 Configuration settings in Sitecore Configuration Files

• • Sitecore Commerce Connect framework is installed as a package on Sitecore CM and CDs. It adds needed content items, DLLs, and configurations to enable communication between Sitecore CM/CD and Commerce Engine. Commerce Connect provides a set of DLL to translate Connect API calls into restful calls to Commerce Engine instances. CM would mostly communicate with CE Authoring and CDs would talk to one or more instances of CE Shop. Most SXC Commerce Connect config files can be found on your Sitecore CM and CD instances under App_Config\Include\Y.Commerce.Engine folder.

Sitecore.Commerce.Engine.Connect.config

• • This is one file we had updated or patch more often than the rest, and below are some of its settings explained

    • shopsServiceUrl: Url of CE instance to work with CM would usually connect to Authoring CE and CDs would usually talk with Shops CE(s)
    • defaultEnvironment: Default/fallback Commerce environment - change this if you chose to use your own custom environment
    • defaultShopName: default storefront/shop to use Commerce storefronts are all configured in Sitecore Content Tree under /sitecore/Commerce/Commerce Control Panel/Storefront Settings/Storefronts
    • certificateThumbprint: Certificates are used by Commerce Engines to authenticate requests coming from Sitecore CM CDssame certificate need to be used and configured on both sides. On Sitecore CM and CDs thumbprint would be set in the above setting and each Commerce Engine should have the same thumbprint set in "Certificates" section in its .\wwwroot\config.json file.

SXC9 Configuration settings in Sitecore Content Tree

• • There are a few Commerce-related settings in Sitecore CM and CDs to keep in mind.

Commerce Control Panel

• • SXC9 settings, related to Commerce Engine and Commerce storefronts, made accessible to Sitecore Content Editors / Merchandisers, this document provides details on each setting/configuration value

SXA Site Configuration Settings

• • When eCommerce website is built with SXA Tenant and Site then some of the Commerce-related settings will go into Site settings. This guide provides detailed information on SXA Storefronts ere are just a few settings to keep in mind:

    • "Selected Catalog" on [your tenant]/[your site]/Home/Catalogs: choose Commerce Catalog(s) to be used by your SXA Storefront Site
    • [your tenant]/Commerce/Catalog Configuration: Catalog and starting category to be used by site navigation menu(s)
    • "Use Direct Navigation" on /sitecore/Commerce/Commerce Control Panel/Storefront Settings/Storefronts/[your storefront]/Catalog Configuration. Switch between "wildcard" and "direct" navigation modes ore details on direct navigation can be found here.

    ---

References

• • • Commerce Engine Configuration,
    • Commerce Connect Configuration
    • Commerce Engine and Storefront configuration settings
    • Bootstrap the Commerce Engine
    • Sitecore Commerce 9 Policies
    • Setting up a new SXC9 Environment
    • Adding custom fields to SXC9 index (TBD)
    • Sitecore Commerce Connect framework