Commerce Engine policies

Abstract

Overview and examples of Commerce Engine policies and how to configure them.

You use policies to define Commerce Engine configuration. A policy is a group of settings that control the behavior of a specific piece of functionality within the Commerce Engine.

Each Commerce plugin contributes a set of policies that define behavior for the functionality provided by the plugin. For example, the Search plugin provides policies that govern the type of entity to be added to the Search index (the SearchScope policy), and which View fields to index for a particular entity (the Indexable policy). The Commerce Core plugin provides an EntityCaching policy that determines the caching behavior for commerce entities.

For a list of Commerce Engine policies and the parameters available in each policy, see the List of Commerce Engine policies section at the end of this topic.

The following is an example of an Entity Caching policy:

{ 
  "$type": "Sitecore.Commerce.Core.EntityCachingPolicy, Sitecore.Commerce.Core", 
  "EntityFullName": "Sitecore.Commerce.Plugin.Content.ContentPath", 
  "AllowCaching": true, 
  "Priority": "Normal", 
  "Expiration": 86400000, 
  "HasNegativeCaching": true, 
  "CacheName": "ContentPaths", 
  "EntityIdPrefix": "Entity-ContentPath" 
} 

Every policy has a default configuration, and unless explicitly configured otherwise, the Commerce Engine uses the policy's default settings to determine behavior for the functionality it defines.

You can configure policy behavior explicitly by including the policy in a policy set file (for global configuration in more than one environment), or by including the policy in an individual environment configuration (JSON) file. When you specify a policy in an environment configuration file, that local configuration overrides the default policy behavior.

An overview of how policies in plugin are exposed for configuration in policy sets and environment configuration files.

Policy sets

A policy set is a file that contains a collection of policies, with a specific configuration. You use policy sets to group policies that you want to use in more than one environment, so that you do not need to repeat the same policy configuration in each environment JSON file.

The Sitecore XC solution includes the following default policy set files in the Commerce Engine SDK.*.zip package, in the wwwroot\data\Environments folder:

  • Core.ControllerMethodRoles.PolicySet-1.0.0.json

  • Plugin.AccessByRoles.PolicySet-1.0.0.json

  • Plugin.Caching.PolicySet-1.0.0.json

  • Plugin.Catalog.PolicySet-1.0.0.json

  • Plugin.CatalogIndexing.PolicySet-1.0.0.json

  • Plugin.Content.PolicySet-1.0.0.json

  • Plugin.LocalizeEntities.PolicySet-1.0.0.json

  • Plugin.Minions.PolicySet-1.0.0.json

  • Plugin.Payments.Braintree.PolicySet-1.0.0.json

  • Plugin.Plugin.PolicySet-1.0.0.json

  • Plugin.Relationships.PolicySet-1.0.0.json

  • Plugin.Search.Azure.PolicySet-1.0.0.json (for the Azure search provider)

  • Plugin.Search.PolicySet-1.0.0.json

  • Plugin.Search.Solr.PolicySet-1.0.0.json (for the Solr search provider)

  • Plugin.SQL.PolicySet-1.0.0.json

  • Plugin.SQL.Sharding.PolicySet-1.0.0.json

  • Plugin.Validation.PolicySet-1.0.0.json

  • Plugin.Versioning.PolicySet-1.0.0.json

  • Plugin.ViewTemplateComposer.PolicySet-1.0.0.json

  • Plugin.Workflow.PolicySet-1.0.0.json

To ensure that a Commerce environment inherits the behavior defined in a particular policy set, you must include a reference to that policy set in the environment's JSON file.

For example, to apply caching behavior specified in the global Caching policy set to a specific environment, you add an entry for that policy set in the Policies collection of the environment JSON file (for example, Plugin.Habitat.CommerceShops.1.0.0.json), as follows:

   {
     "$type": "Sitecore.Commerce.Core.PolicySetPolicy, Sitecore.Commerce.Core",
        "PolicySetId": "Entity-PolicySet-CachingPolicySet"
   },

Note

If you change the policy configuration in any policy set file, the behavior changes for any environment that references the policy set file.

Local policy configuration

You define policy configuration for a single environment, by adding a policy to the environment's configuration (JSON) file.

For example, the Carts plugin includes policies that govern cart behavior. One policy, the CalculateCart policy, determines whether (and when) the Commerce Engine recalculates a cart total. Promotions, line prices, shipping costs, or other cart operations affect the cart total. For optimized performance, particularly in a Shops environment, the AlwaysCalculate parameter is set to false by default.

However, in an Authoring environment, you might want to enable the AlwaysCalculate parameter so that a business user can test a new promotion, for example, and ensure that any discounts are applied to the cart total correctly, in real time.

To enable the parameter for the Authoring environment only, you would add an instance of the Calculate Cart policy to the Policies collection in the environment JSON file (for example, Plugin.Habitat.CommerceAuthoring.json) and set the AlwaysCalculate parameter to true as follows:

  {
    "$type": "Sitecore.Commerce.Plugin.Carts.CalculateCartPolicy, Sitecore.Commerce.Plugin.Carts",
        "AlwaysCalculate": true
  },

Because the Calculate Cart policy is explicitly included in the environment JSON file, the Commerce Engine uses the setting in the file to override the default behavior of the Calculate Cart policy, for that specific environment.

Note

If you make any changes to an environment JSON file, you must bootstrap the Commerce Engine to propagate the changes to the Global database.

List of Commerce Engine policies

Policies for the different Commerce Engine services are defined in the plugins that provide those micro-services. The following table summarizes all of the policies available by micro-service. Click the link in the policies column to go to a more detailed topic on those specific policies.

Commerce plugin

Policies

Sitecore.Commerce.Core

Core policies

Sitecore.Commerce.Plugin.Views

Views policies

Sitecore.Commerce.Plugin.Orders

Orders policies

Delayed Availability policies

Sitecore.Commerce.Plugin.Returns

Returns policies

Sitecore.Commerce.Plugin.Carts

Cart policies

Sitecore.Commerce.Plugin.Customers

Customer policies

Sitecore.Commerce.Plugin.Pricing

Pricing policies

Sitecore.Commerce.Plugin.Promotions

Promotions policies

Sitecore.Commerce.Plugin.Coupons

Coupons policies

Sitecore.Commerce.Plugin.Entitlements

Entitlements policies

Sitecore.Commerce.Plugin.Catalog

Catalog and Relationship policies

Sitecore.Commerce.Plugin.Availability

Availability policies

Sitecore.Commerce.Plugin.Inventory

Sitecore.Commerce.Plugin.Preorderable

Sitecore.Commerce.Plugin.Backorderable

Inventory policies

Sitecore.Commerce.Plugin.Payments

Payment policies

Sitecore.Commerce.Plugin.Fulfillment

Fulfillment policies

Sitecore.Commerce.Plugin.Search

Search policies