Commerce Engine environments
Sitecore XC software architecture uses the concept of environments to allow for different Commerce Engine configurations. Commerce environments mean that you can have separately configurable pools of data and service functionality, running in single or multiple Commerce Engine service instances, based on your deployment requirements. When a client makes a call to the Commerce Engine, it specifies the target environment in the call header.
A Commerce Engine environment is a configuration defined by a collection of policies that control Commerce Engine behavior. The environment configuration determines how a call to the engine is handled, and a Commerce dataset. You can therefore tailor Commerce Engine functionality according to the requirements of the calling client. Identical engine calls (for example, a request for product details) can function differently depending on the configuration of the target environment identifier specified in the call header.
For example, you can configure different caching behavior between environments, to reflect the level of traffic expected from each Commerce Engine client. In a production deployment, a request for product details coming from a storefront (content delivery role) would typically target a Shops environment, and the data would likely be read from a cache, to minimize the impact on performance. However, when responding to the same request targeting the Authoring environment, the Commerce Engine would likely retrieve the data directly from the database, to provide the most up-to-date information.
You define a Commerce environment in the environment configuration JSON file. The environment JSON file contains information on specific Commerce Engine policies, either as references to policy sets outside the JSON file, or as explicit policy configuration within the file, to be implemented only for that Commerce Engine environment itself.
Environment configuration file
Each Commerce environment is defined in a distinct environment configuration JSON file.
The Sitecore XC solution includes several environment configuration files to support the sample Habitat and Adventure Works datasets and environments in the Sitecore.Commerce.Engine.*.zip package. Commerce Engine environment files are stored in the wwwroot\data\Environments folder. The sample solution includes the following default environment files, for the Habitat and the Adventure Works environments, respectively:
-
Adventure Works
-
Plugin.AdventureWorks.CommerceAuthoring-1.0.0.json -
Plugin.AdventureWorks.CommerceShops-1.0.0.json -
Plugin.AdventureWorks.CommerceMinions-1.0.0.json
-
-
Habitat
-
Plugin.Habitat.CommerceAuthoring-1.0.0.json -
Plugin.Habitat.CommerceShops-1.0.0.json -
Plugin.Habitat.CommerceMinions-1.0.0.json
-
Each environment JSON file contains two key properties that correlate Commerce Engine functionality and a dataset:
-
The environment name, that is, the environment specified in the call header to the Commerce Engine.
-
The artifact store ID value that binds a Commerce data set with the specified environment name. The artifact store ID value is a key that the Commerce Engine uses to store Commerce data against. The artifact store ID defines the set of data that any calls to the Commerce Engine (for that environment name) work against.
As an example, the following shows a sample of the default Plugin.Habitat.Commerce-Authoring-1.0.0.json file, that contains policies defining the behavior of the Habitat Authoring environment ("Name": HabitatAuthoring") and associates with the artifact store ID value that represents the sample Habitat data set:
The differences in configuration between these default Commerce Engine environments reflect the intended purpose for each one.
The following is an example of a reference to the Caching policy set within the "Policies" collection of a Commerce Engine environment JSON file:
{
"$type": "Sitecore.Commerce.Core.PolicySetPolicy, Sitecore.Commerce.Core",
"PolicySetId": "Entity-PolicySet-CachingPolicySet"
},
For example, in the Authoring environment configuration, the PromotionsRequireApproval parameter (in the Global Promotions policy) is set to false because business users are usually testing promotions in this environment and do not require approval to publish them. In the Shops environment, however, this same parameter is set to true, so that a business user cannot publish a promotion to a storefront without approval from the appropriate business user (the Promotion Manager role).
You can also create your own environment and customize the configuration as required.
If you make changes to the environment JSON files, you must bootstrap the Commerce Engine to make sure the changes are propagated to the Global database.
Data isolation
Environments can share the same persistent store as other environments or be separated into their own exclusive persistent store.
Every Commerce environment has an Artifact Store ID, which is a key that the Commerce Engine stores data against in Commerce databases. The Artifact Store ID defines the set of data that any calls to the Commerce Engine (for that environment) work against.
For example, the Sitecore XC solution provided in the Sitecore Commerce Engine SDK includes default environments for two distinct sample shop datasets, that is, the Habitat shop, and the Adventure Works shop. Each dataset has an artifact store ID associated with it.
There are separate authoring and shops environments configured for each sample dataset:
-
HabitatAuthoring - this environment works against the Habitat dataset. The Authoring environment defines how the Commerce Engine behaves in response to requests originating from the Business Tools.
-
HabitatShops - this environment also works against the Habitat dataset (it has the same artifact store ID value as the HabitatAuthoring environment). In a typical deployment, the Shops environment defines how the Commerce Engine behaves in response to requests that originate from the Storefront.
-
AdventureWorksAuthoring - this environment works against the Adventure Works dataset. In a typical deployment, the Authoring environment defines how the Commerce Engine behaves in response to requests originating from the Business Tools.
-
AdventureWorksShops - this environment also works against the Adventure Works dataset (it has the same artifact store ID value as the AdventureWorksAuthoring environment). In a typical deployment, the Shops environment defines how the Commerce Engine behaves in response to requests that originate from the Storefront.
Although the sample solution included in the Sitecore Commerce Engine SDK package provides distinct environment files for the Shops environment and for the Authoring environments, the default deployment actually only uses the configuration defined in the Plugin.Habitat.CommerceAuthoring-1.0.0.json file. That is, in a default deployment, Commerce Engine calls originating from the SXA Storefront or from the Business Tools all target the same HabitatAuthoring environment.
The default HabitatAuthoring and HabitatShops environments share the same artifact store ID, as declared in their JSON files:
If you configure multiple storefronts to use different Commerce shops environments, you must ensure that these Commerce environments' configuration and the configuration of the default environment specified in the Sitecore.Commerce.Engine.Connect.config file all use the same artifact store ID value.