Document Tree
Document Properties
Last Modified
Added to KB
Public Access
Doc Type
  • ICM 7.10
  • ICM 11
  • ICM 12
Guide - Configuration Framework


This document approaches the configuration framework of Intershop Commerce Management from the configuration perspective. It is addressed to administrators or DevOps engineers 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 from 7.10.12).

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 files where the reader, writer, finder, and scopes are defined for (and comprise) the ConfigurationSets. These files are searched in all cartridges in reverse order as resource  /resources/CARTRIDGE_NAME/config/configuration.xml.


The following components comprise the framework for loading configuration settings:




This file contains all finders, readers and writers that will construct your configuration sets. The configuration scopes and configuration sets are defined here.

Configuration Set

The 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 and can be prioritized to allow to redefine and specialize configuration values.

Configuration Manager

Provides an entry point to get configuration objects. The configuration manager parses configuration.xml resources, and places any readers, finders and scopes into the engine.

Configuration Engine

Retrieves 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.


Resolves the URI of the configuration set source.


Reads 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 depends 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 a configuration.xml file.

<scope name="system" />
<scope name="ish" depends="system" />
<set finder="system" scope="system,ish,startup,instance,cluster,server,domain" />
<set finder="file" scope="instance,cluster,server,domain" fileName="${IS_CLUSTER_CONFIG}/" priority="60"/>

The scope ${IS_CLUSTER_CONFIG} 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 hierarchy. 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.


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


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 to 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>/, for <IS.INSTANCE.DIR> properties.

(3) <IS.INSTANCE.SHARE>/system/config/cluster/, 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 database that can be read from/written to in the back office.

(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.


File Location




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



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



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



When enabled, returns the configuration filename



Searches for the application preference and domain preferences as fallback



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



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



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


Finds the resource <resourceName> using the System-ClassLoader, or if <cartridge> is set, using the cartridge-Resource-ClassLoader. If “required“ is set as "true", raises an exception if the file does not exist.



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


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



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



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:




Updates the given configuration set.


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

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 depends 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 using their order in the configuration.xml file and the priority attribute, you should save your configurations as designated by the table below.

Configuration is applicable to...


Domain or site-specific


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


Instance or server specific


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 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.

The system ships with build in configuration sets which define values in properties files inside cartridges. In order to allow to distinguish between different environments (like “production“ or “test“) file and domain-based configuration sets are supported.


The environment for your configurations must be placed in the file name of the configuration files. The file 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.

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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to if you experience login issues,
or if you want to register as customer.