Guide - Configuration Framework

1 Introduction

This document approaches the configuration framework of Intershop Commerce Management from the configuration perspective. It is addressed to administrators or DevOps who configure and maintain Intershop Commerce Management instances. This document does not describe implementation details of the configuration framework. For details about the framework implementation, refer to Concept - Configuration (valid to 7.10.11).

Info

Prior to Intershop version 7.7 the information provided in this document were part of the Administration and Configuration Guide that can be found in the Knowledge Base.

Intershop Commerce Management provides a unified interface for administrators to get and load configuration settings to installations at system-level to application-level (i.e., preferences) from multiple sources. The central entry point is the configuration engine that reads the configuration.xml file where the reader, writer, finder, and scopes are defined for (and comprise) the ConfigurationSets. The file is found in <IS.INSTANCE.SHARE>/system/config/cluster and the source file in <core-cartridge-source>/staticfiles/share/system/config/cluster.

Note

All relevant setup options are to be configured in advance via dedicated deployment script files, before actually executing the deployment. So be aware that if you modify the Intershop Commerce Management configuration after it is deployed, the next deployment will override all changes with the settings specified for your deployment.

1.1 Glossary

The following components comprise the framework for loading configuration settings:

ConceptDescription
configuration.xmlThis file contains all finders, readers and writers that will construct your configuration sets. The configuration scopes and configuration sets are defined here.
Configuration SetThe configuration set is the store for configuration settings. Defined in the configuration.xml file, the configuration set is a grouping of sources, locations and access to read from or write values to a source. A configuration set can belong to more than one scope.
Configuration ManagerProvides an entry point to get configuration objects. The configuration manager parses configuration.xml, and places any readers, finders and scopes into the engine.
Configuration EngineRetrieves the URIs from the finders which are then used to get configuration sets from the readers. These are then added to a configuration set manager as configuration sets.
FinderResolves the URI of the configuration set source.
ReaderReads the source provided by the finder and returns the configuration set.
Configuration Scope

Each configuration source (a file, database, etc.) belongs to a special scope. If the scope is dependent on a higher-ranking scope, configuration values are taken from the higher-ranking scope. The values are then applied to initializing the finder and sets.

You can use placeholders in the attributes defined in the configuration.xml file.

<scope name="system" />
<scope name="ish" depends="system" />
<set finder="system" scope="system,ish,startup,instance,cluster,server,domain" />
<set finder="property" scope="ish,startup,instance,cluster,server,domain" required="true" filename="${system.intershop.HomeDirectory}/intershop.properties" />

The scope ${system.intershop.HomeDirectory} is only possible because the system scope is loaded. The scope attribute of the set shows the sets that are used. The placeholders serve an essential role because they allow the specific configuration for the environment and/or data center to be applied.

Scopes specify where to look for configurations (or rather, the context of application for the writer, reader and finder) across an entire system or within a specific domain. Some scopes have dependencies on other scopes higher up in the heirarchy. For example the instance scope configuration depends on some startup scope properties that must first load some system scope properties. Therefore in our example, the instance scope has a dependency on the system scope. The scope defines the extent of application for the configuration.

WriterWrites to the URI provided by the finder in the configuration set.

1.2 References

2 Defining Configuration Sets

For every configuration set the finders and writers must be registered and the reader classes must be declared within configuration.xml. If a class is declared and the requirement is set true and none is found, an exception will be thrown.

A finder returns a list of URIs. Each URI will be converted to a configuration set.

The order of configuration sets is important. Within configuration.xml, the sets must be ordered in the sequence they are loaded. This also means that the first value for a specific key is applied. If the same key is found later in the list of configurations, the value is discarded. See Arranging Configuration Sets for a list of where to place your configurations. Configurations should be loaded in the following sequence:

(1) System properties, define properties from the system.

(2) <IS.INSTANCE.LOCAL>/intershop.properties, for <IS.INSTANCE.DIR> properties.

(3) <IS.INSTANCE.SHARE>/system/config/cluster/environment.properties, defines one value for the current environment.

(4) <IS.INSTANCE.LOCAL>/config/[environment]_[feature].xml, defines the instance-specific (local) configuration.

(5) Preference table, defines properties in the data base that can be read from/written to in the backoffice.

(6) <IS.INSTANCE.SHARE>/system/config/domains/[domain]/[environment]_[feature].xml, defines domain specific business configuration.

(7) <IS.INSTANCE.SHARE>/system/config/cartridges/[environment]_[feature].xml, defines the default configuration of the cartridge.

(8) <IS.INSTANCE.SHARE>/system/config/cluster/[environment]_[feature].xml, defines the configuration for this cluster.

For every configuration set the finders and writers must be registered and the reader classes must be declared within configuration.xml.

Finder

File Location

Description

app-folder

<IS.INSTANCE.SHARE>/system/config/apps

Looks into the apps-folder for the fully qualified <filename> and extension to be read

system

-

Returns a URI with the scheme "ish-system." Reads the system environment.

cartridge

<IS.INSTANCE.SHARE>/system/config/cartridges/[environment]_[feature].xml

Returns a URI with the scheme "ish-site cartridge." Returns a list of cartridges.

cartridge-folder

<IS.INSTANCE.SHARE>/system/config/cartridges/

When enabled, returns the configuration filename

applicationprefs*

-

Searches for the application preference and domain preferences as fallback

defaultprefs

-

Returns a URI with the scheme "ish-defaultPreference." Default values are derived from PreferenceDefinitionPO.

preference

-

Returns a URI with the scheme "ish-preference."

domain-folder

<IS.INSTANCE.SHARE>/system/config/domains/[domain]/[environment]_[feature].xml

Returns a URI with the scheme "ish-domainFolder." Reads settings with domain-specific dependencies.

property

-

Finds the fully qualified <filename> to be read. If set as "true", raises an exception if the file does not exist.

xml

-

Finds the fully qualified <filename> to be read. If set as "true", raises an exception if the file does not exist.

transient

-

Returns a URI with the scheme "ish-transient."

Promotion preferences are not supported.

The writer saves the configuration. You must define at least one writer that will retrieve the values of your configuration set. Below is the syntax for writer registration and a list of available writers:

Writer

Description

transient

Updates the given configuration set.

property

Writes the configuration set to the given URI as a property file, subsequently updates the given configuration set.

3 Arranging Configuration Sets

The range or extent of the configuration is determined by the configuration scope where the configuration sources are located. Scopes are defined in the configuration.xml file and are dependent on scopes higher up in the scope hierarchy. If the configuration you want to load depends on values of a broader scope, these must be loaded first.

For example, if you load a configuration for a specific instance (scope="instance"), you must first load the startup configuration (the startup scope), which in turn is dependent on the system properties (contained in the <IS.INSTANCE.DIR> directory) contained in the startup scope. Thus, a configuration for the instance scope cannot be properly loaded unless the configuration values on which it depends (derived from startup scope, higher in the hierarchy) are loaded first.

Another thing to keep in mind is the use of *.properties files and the use of preferences. Preference databases hold values that tend to be applied to business data (e.g., data centers) across an installation, and are generally not application specific. Property files on the other hand are typically system processes (e.g., services for a single location) where a single property file holds settings, or an XML file that contains all of the property files handles the settings. Depending on the order of the configuration sets in the configuration.xml file, you should save your configurations as designated by the table below.

Configuration is applicable to...

Location

Domain or site-specific

<IS.INSTANCE.SHARE>/system/config/domains/<domain-name>

Domain or site/cartridge specific

<IS.INSTANCE.SHARE>/system/cartridges/<cartridge>/release/config or IS_TARGET/<cartridge>/release/config (depends on the cartridge location)

Cartridge configuration

<IS.INSTANCE.SHARE>/system/config/cartridges

Instance or server specific

<IS.INSTANCE.LOCAL>/config

4 Managing your Configurations

It is very important that the administrator clearly understand the location of the configuration sources, and the environment of the configuration source. A source located in a system folder is in most cases applied to a specific instance configuration in a particular environment. It should also be noted that some configuration sources are best managed with a *.xml file or a preference table, while for others it makes more sense to read a single or a set of property files.

The file environment.properties defines the environment for the ConfigurationSet with respect to the following characteristics:

  • Process
    A process environment must have a "default" set of values; these values are then overwritten by other environments such as development, test (QA, customer, etc.), and production.
  • Application
    An application environment denotes the type of Intershop Commerce Management installation, such as edit, live or both.

Note

The value in environment.properties is set upon deploying Intershop Commerce Management via the environment setting in the settings.gradle file.

The environment for your configurations must be placed in the file name of the configuration files. The file environment.properties defines the current environment that you are in (for example, datacenter1). Within this file, there is the key-value pair environment = <value>.

You can view the the configuration for a specific scope (Application Server in our example) in the System Management application. Refer to its online help for details.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets