Global environment configuration file

Abstract

How to change the global environment configuration for the Commerce Engine.

Each instance of the Commerce Engine contains a Global.json file that defines the global environment configuration ("Name": "GlobalEnvironment") for that Commerce Engine service. The content of the Global.json file is loaded into system memory when a Commerce Engine service starts. For example, the Global.json file contains the connection string that the Commerce Engine uses to make the initial connection to the Global database that the remainder of the configuration is loaded from.

The Global.json environment file is located in the C:\inetpub\wwwroot\<CommerceEngine>\wwwroot\bootstrap folder.

The following shows an example of the Global.json file that is included as part of the sample solution package Sitecore.Commerce.Engine.SDK. A description of the content of each section of the file follows.

Note

In your deployment, you should limit modifications to the Global.json file to the policies collection section, for example, to change a parameter value, or to add a new global configuration policy. This applies to any Commerce Engine environment configuration files.

{
  "$type": "Sitecore.Commerce.Core.CommerceEnvironment, Sitecore.Commerce.Core",
  "Id": "GlobalEnvironment",
  "ArtifactStoreId": "{6be385f1-93dc-4299-9dd4-934f6ba42eaa}",
  "IsPersisted": false,
  "Name": "GlobalEnvironment",
  "Policies": {
    "$type":  System.Collections.ObjectModel.ReadOnlyCollection`1[[Sitecore.Commerce.Core.Policy, Sitecore.Commerce.Core]], mscorlib",
    "$values": [
      {
        "$type": "Sitecore.Commerce.Plugin.Management.ManagementCachePolicy, Sitecore.Commerce.Plugin.Management",
        "CurrencySetsCacheName": "CurrencySets",
        "FulfillmentCacheName": "Fulfillment",
        "PaymentsCacheName": "Payments",
        "CountriesCacheName": "Countries",
        "ItemsCollectionCacheName": "ItemsCollection",
        "ItemsCacheName": "Items",
        "Expiration": 86400000,
        "AllowCaching": true
      },
      {
        "$type": "Sitecore.Commerce.Plugin.BusinessUsers.EnvironmentBusinessToolsPolicy,Sitecore.Commerce.Plugin.BusinessUsers",
        "EnvironmentList": {
          "$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
          "$values": [
            "AdventureWorksShops",
            "AdventureWorksAuthoring",
            "HabitatAuthoring",
            "HabitatShops"
          ]
        }
      },
      { 
        "$type": "Sitecore.Commerce.Plugin.SQL.EntityStoreSqlPolicy, Sitecore.Commerce.Plugin.SQL",
        "PolicyId": "Global",
        "AllowAdmin": true,
        "Database": "PlaceholderForGlobalDatabaseName",
        "EffectiveDate": "0001-01-01T00:00:00",
        "IsVisible": false,
        "Password": "PlaceholderForGlobalDatabasePassword",
        "Server": "PlaceholderForGlobalDatabaseServer",
        "TrustedConnection": false,
        "UserName": "PlaceholderForGlobalDatabaseUserName",
        "View": "EntityStoreSqlPolicy",
        "Version": "10.0.0",
        "AdditionalParameters": "",
        "ConnectTimeout": 20,
        "CommandTimeout": 180,
        "CleanEnvironmentCommandTimeout": 120000
      },
      {
        "$type": "Sitecore.Commerce.Core.DeploymentPolicy, Sitecore.Commerce.Core",
        "DeploymentId": "PlaceholderForDeploymentId",
        "DeploymentVersion": "1.0.0",
        "ParentNodeId": "Hub01"
      },
      {
        "$type": "Sitecore.Commerce.Core.ControllerMethodRolesPolicy, Sitecore.Commerce.Core",
        "ControllerMethodRegularExpression": "/commerceops/",
        "AuthorizedRoles": [
          "sitecore\\Commerce Business User",
          "commerce\\runtime"
        ]
      },
      {
        "$type": "Sitecore.Commerce.Core.ControllerMethodRolesPolicy, Sitecore.Commerce.Core",
        "ControllerMethodRegularExpression": "/api/",
        "AuthorizedRoles": [
          "sitecore\\Commerce Business User",
          "commerce\\runtime"
        ]
      },
      {
        "$type": "Sitecore.Commerce.Plugin.Management.SitecoreConnectionPolicy, Sitecore.Commerce.Plugin.Management",
        "Host": "PlaceholderForSitecoreHost",
        "SitecoreDatabase": "PlaceholderForSitecoreDatabase", 
        "UserName": "PlaceholderForSitecoreUsername",
        "Domain": "PlaceholderForSitecoreDomain",
        "Password": "PlaceholderForSitecorePassword",
        "ConnectionLeaseTimeout": 60000,
        "AuthRequestUrl": "sitecore/api/ssc/auth/login"
        "Protocol": "https",
        "AllowAnonymousUser": "false"
      },
      {
        "$type": "Sitecore.Commerce.Plugin.Content.DefaultContentPathsPolicy, Sitecore.Commerce.Plugin.Content",
        "ContentPaths": {
          "$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
          "$values": [
            "/sitecore/Commerce/Commerce Control Panel"
          ]
        }
      },
      {
        "$type": "Sitecore.Commerce.Plugin.SQL.EntityShardingPolicy, Sitecore.Commerce.Plugin.SQL",
        "Expressions": {
          "$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
          "$values": [
            "Entity-Content.*?$",
            "Content-.*?$",
            "ContentItem-.*?$",
            "ContentPath-.*?$"
          ]
        },
        "TableName": "ContentEntities"
      },
      {
        "$type": "Sitecore.Commerce.Plugin.SQL.ListShardingPolicy, Sitecore.Commerce.Plugin.SQL",
        "Expressions": {
          "$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
          "$values": [
            "^List-ContentPath.*?$",
            "^List-ContentItem.*?$",
            "Entity-Content.*?$",
            "ContentItem-.*?$",
            "ContentPath-.*?$"
          ]
        },
        "TableName": "ContentLists"
      }
    ]
  }
}

Global environment configuration policies and parameters

The Global.json file is composed of multiple sections, each defining related policy properties.

The ManagementCachePolicy policy controls the caching of item model objects from the Commerce Control Panel (in Sitecore Content Editor).

The following table describes the properties of the ManagementCachePolicy policy:

Property

Description

Default value

CurrencySetsCacheName

Name of the cache where currency sets are stored.

CurrencySets

FulfillmentCacheName

Name of the cache where fulfillment options and types are stored.

Fulfillment

PaymentsCacheName

Name of the cache where payment options and payment types information is stored.

Payments

CountriesCacheName

Name of the cache where countries and regions are stored.

Countries

ItemsCollectionCacheName

Name of the cache where content item collections are stored.

ItemsCollection

ItemsCacheName

Name of the cache where items are stored.

Items

Expiration

The length of time after which a cache entry expires, in milliseconds.

86400000

AllowCaching

Enables or disables caching for the entity.

true

The EnvironmentBusinessToolsPolicy policy lists the environments that are accessible from the Business Tools. Typically, this policy is defined on the instance of the Commerce Engine that is running the Authoring service.

The following table describes properties of the EnvironmentBusinessToolsPolicy policy:

Property

Description

Default value

EnvironmentList

Lists the environments that business users can access when using the Sitecore Experience Commerce Business Tools.

  • AdventureWorksShops

  • AdventureWorksAuthoring

  • HabitatAuthoring

  • HabitatShops

The EntityStoreSqlPolicy policy defines global database configuration. The following table describes properties of the EntityStoreSqlPolicy policy:

Property

Description

Default value

PolicyId

Name of the policy that governs global database configuration.

Global

AllowAdmin

Allows a range of database administration commands.

true

Database

Name of database that defines the global environment.

No default.

The value is specified during deployment.

EffectiveDate

Date that the database becomes effective.

001-01-01T00:00:00

Password

Global environment database password.

No default.

The value is specified during deployment.

Server

Global environment database server.

No default.

The value is specified during deployment.

TrustedConnection

Determines whether or not to use a trusted connection.

false

UserName

User name for the global environment database.

No default.

The value is specified during deployment.

Version

Running version of the Sitecore XC.

10.*.*

AdditionalParameters

Allows to define additional parameter.

No value defined.

Optional parameter.

ConnectTimeout

Time to wait connection to open, in seconds.

20

CommandTimeout

Time to wait command to complete, in seconds.

180

CleanEnvironmentCommandTimeout

Time to wait for a CleanEnvironmentRequest (in Postman) to complete, in seconds.

120000

The following table describes properties of the DeploymentPolicy policy.

Property

Description

Default value

DeploymentId

Unique ID that identifies a deployment.

No default.

The value is specified during deployment.

DeploymentVersion

Identifies the version of the deployment.

1.0.0

ParentNodeId

Identity of the parent node.

Hub01

The ControllerMethodRolesPolicy controls access to the Commerce Engine APIs. For example, it is used to determine which user can execute which operations.

The Global.json file defines two instances of the ControllerMethodRolesPolicy policy, one for CommerceOps, and one for the Commerce Engine API.

The following table describes properties for the instance of the ControllerMethodRolesPolicy policy that defines the Commerce API:

Property

Default value

ControllerMethodRegularExpression

/api/

AuthorizedRoles

sitecore\\Commerce Business User

commerce\\runtime

The following table describes properties for the instance of the ControllerMethodRolesPolicy policy that defines the Commerceops route:

Property

Default value

ControllerMethodRegularExpression

/Commerceops/

AuthorizedRoles

sitecore\\Commerce Business User

commerce\\runtime

The SitecoreConnectionPolicy contains properties that define the connection to the Sitecore host.

The following table describes properties of the SitecoreConnectionPolicy policy:

Property

Description

Default value

Host

The name of the Sitecore host.

No default.

The value is specified during deployment.

SitecoreDatabase

The name of the Sitecore master database.

No default.

The value is specified during deployment.

UserName

The user name required to connect to the Sitecore host.

No default.

The value is specified during deployment.

Domain

Domain of the Sitecore host.

No default.

The value is specified during deployment.

Password

User password for authentication.

No default.

The value is specified during deployment.

ConnectionLeaseTimeout

Number of milliseconds after which an active connection to the Sitecore host is closed.

60000

AuthRequestUrl

The URL for the authorization request.

sitecore/api/ssc/auth/login

Protocol

The protocol used to communicate with the host.

https

AllowAnonymousUser

Determines whether or not authentication is required to connect to the host.

false

The DefaultContentPathsPolicy contains properties that defines the path to the Sitecore Commerce Control Panel.

The following table describes properties of the DefaultContentPathsPolicy policy:

Property

Description

Default value

ContentPaths

Path to the Commerce Control Panel in Sitecore.

/sitecore/Commerce/Commerce Control Panel

The EntityShardingPolicy contains properties that defines database shard names for ContentEntities .

Property

Description

Default value

Expressions

Regular expressions used for ContentEntities table names.

"Entity-Content.*?$"

"Content-.*?$"

"ContentItem-.*?$"

"ContentPath-.*?$"

The DefaultContentPathsPolicy contains properties that defines database shard names for ContentLists list.

Property

Description

Default value

Expressions

Regular expressions used for ContentLists database table names.

"^List-ContentPath.*?$"

"^List-ContentItem.*?$"

"Entity-Content.*?

"ContentItem-.*?$"

"ContentPath-.*?$"