Document Properties
Last Modified11-Mar-2020
Added to KB18-Jul-2019
Public AccessEveryone
Doc TypeGuidelines, Concepts & Cookbooks
ProductICM 7.10

Concept - Configuration (valid from 7.10.12)

1 Introduction


This concept is valid from ICM version 7.10.12. Information on previous versions can be found in Concept - Configuration (valid to 7.10.11).

The configuration framework is designed to let the administrator (not the developer) decide from where to read a configuration. The purpose of the configuration framework is to have the ability to ask one manager for a property, but to read, if necessary, from multiple sources.

The terms property and preference are used as synonyms in this context. The term configuration source is a placeholder for anything that can be a source for configurations, e.g., a file, a database table, an external resource etc.

The heart of the configuration is the file configuration.xml. This file includes the configuration of the configuration engine instance used at ConfigurationMgr.

DIA Configuration SimpleFlow

2 Code Examples

Using the configuration framework is quite simple, as illustrated in the following examples. Every access is started at the ConfigurationMgr (which starts a configuration engine and loads the configuration.xml).

2.1 Access a Standard Configuration (Server and Domain)

import com.intershop.beehive.core.capi.configuration.ConfigurationMgr;

// short notation to get string values
String  configString = ConfigurationMgr.getString("config.key.string","defaultValue")

// long notation to get many types and other scopes
Boolean configBool = ConfigurationMgr.getInstance().getConfiguration().getBoolean("config.key.boolean", true);

// domain configuration
Domain eTest = NamingMgr.getManager(DomainMgr.class).getDomainByName("eTest");
String  configDomainString = ConfigurationMgr.getInstance().getConfiguration(eTest).getString("config.key.string", "defaultValue");

// or via domain - same thing other notation
String  configDomainString2 = eTest.getConfiguration().getString("config.key.string", "defaultValue");

2.2 Access a Specific Configuration

These configuration examples are mostly used for debugging purposes or visualization in the SMC.

// get a configuration for scope=instance
Configuration configInstance = ConfigurationMgr.getInstance().getInstanceConfiguration();

// get a configuration for scope=cluster
Configuration configCluster = ConfigurationMgr.getInstance().getClusterConfiguration();

// full access to the configuration
Configuration yourConfig = ConfigurationMgr.getInstance().getConfiguration(String scope, ConfigurationContext context);

2.3 Access via Object Path in Templates

The object path is often used in templates and queries. It is possible to access the configuration via the object path notation.

<isprint value="#CurrentSite:Configuration:String("<parameter>")#" />
<isprint value="#CurrentSite:Configuration:Integer(<group>.<subgroup>.<parameter-of-subgroup>)#" />

3 configuration.xml

This file is located at ${IS_SHARE}/share/system/config/cluster; the source file can be found in <core-cartridge-source>/staticfiles/share/system/config/cluster.

  • The file contains any
    • ConfigurationFinder that you want to use
    • ConfigurationReader that you want to use
    • ConfigurationWriter that you want to use
    • ConfigurationScopes that you define
    • ConfigurationSet that the finder/reader/writer combination will create and that you can access and read properties
    <reader class="..." />
    <finder name="..." class="..." />
    <writer name="..." class="..." />
    <scope name="..." depends="..." />
    <set finder="..." scope="..." writer="..." defaultWriter="..." writableKeys="..." />
  • The readers section defines the readers to use
    • class: the class name of the reader; if no class is found, an exception will be thrown
  • The finders section defines the finders to use
    • name: the name by which this finder will be registered
    • class: the class name of the finder to use; if no class is found, an exception will be thrown
  • The writers section defines the writers to use
    • name: the name by which this writer will be registered
    • class: the class name of the writer to use; if no class is found, an exception will be thrown
  • The scopes section defines the different scopes for which configurations will be created
    • name: the name of the scope
    • depends: if a scope depends on the existence of other scopes
  • The set section defines the configuration sets that will be found and read
    • finder: the finder to use in order to find an URI a proper reader can read and provide a configuration set
    • scope: the comma-separated list of scopes for which this configuration set is intended
    • writer: the name of a writer to use if this set should also be written
    • defaultWriter: used if the writer of this set is the default writer
    • writableKeys: the comma-separated list of keys the writer can write
    • any other attribute of this tag will be treated as a bean property if the defined finder and a setter method with the given attribute name will be triggered; e.g., <set fileName="..."/> will trigger the setFileName(...) method


The order of the configuration sets (and associated writers) in this file is important. If you have to read from two different configuration sources, the property of the first will be returned as defined in the file.

4 Scopes

The configuration engine can provide different configurations for different purposes. To this end, the concept of scopes was introduced. A scope is a logical structuring of configurations that are needed for this purpose.

Stating that a scope depends on (an)other scope(s) means that in order to load configurations for this scope (e.g., instance), you initially have to load all configurations on which this scope depends ( startup). As startup uses the system configuration, which gives you any system properties (intershop.HomeDirectory), the instance scope cannot be properly loaded as long as it depends on values from the startup scope.

The fact that one scope depends on another scope does not automatically mean that if you request a configuration for this scope, you will also have configuration sets of the dependent scopes in it. That is, if you request a configuration for the scope instance which depends on startup, any startup configuration set is not necessarily in the instance scope.

The following picture outlines the scopes currently used.

DIAG Configuration instances

5 System Properties

The system properties include all properties defined for the scope system. This includes:

  • VM properties (command line argument -Dproperty=value)
  • System environment variables

System environment properties take preference over Java VM properties.

Those properties will be available inside the configuration framework using the following keys:

  • Original key of the property (e.g., PATH)
  • 'system.' plus the original key of the property (e.g., system.PATH)

As operation systems like Linux and Windows have restrictions with environment variables, the final property lookup via the configuration framework executes the following steps for the system scope:

  1. Transform the key as follows:
    1. Make the key uppercase.
    2. Replace each dot ('.') by an underscore ('_').
    3. Replace each dash ('-') by an underscore ('_').

transformation example

intershop.jdbc.dataSourceName INTERSHOP_JDBC_DATASOURCENAME

  1. Try a lookup using the transformed key.
  2. If this is a success, the value is returned.
  3. If this is a failure, try another lookup using the original key.

This allows to override properties defined in a scope below the system scope using system environment properties that are restricted by the OS.

Sometimes (in rare cases) the property key is required to follow a strict naming (e.g., camel case). So there is another option to add properties to the system scope: there are properties supported that follow the naming scheme ISH_ENV_* (* can be anything supported by the OS). The values of all these properties have to follow a special syntax:


For instance there may be 2 ISH_ENV_* properties that may be defined like:


If these properties are defined like that, the following properties will be defined inside the configuration framework:




When working with system properties, be aware of the following restrictions for Windows or Linux:

OSsupports minus ('-')supports dot ('.')supports case sensitivity

6 Finders

There is an implicit list of finders which provide URIs that can be read by the readers below.

Finder scheme




read system and environment variables. All system variables will be prefixed with system.
java -Dfoo=bar the value bar is accessible via


  • matches: the regular expression for the files to be read
  • fileExtensions: the extensions of the files to be read

folder is predefined with ${IS_SHARE}/system/config/apps. The file name must match the "matches" attribute.


  • matches: the regular expression for the files to be read
  • fileExtensions: the extensions of the files to be read

folder is predefined with ${IS_TARGET}/<cartridge-name>/release/config. The file name must match the "matches" attribute.

The folder can be part of each source cartridge ${IS_SOURCE}/<cartridge-name>/staticfiles/cartridge/config and will be deployed automatically.


  • enabled: flag to enable the sets (default true)
  • cartridges: list of cartridges
folder is predefined with ${IS_SHARE}/system/config/cartridges.


default values from PreferenceDefinitionPO


  • matches: the regular expression for the files to be read
  • fileExtensions: the extensions of the files to be read

folder is predefined with ${IS_SHARE}/system/config/domains.


  • configFilePath: the prefix for the files to be read

read network interfaces to define instance-specific file


preference values from PreferencePO


  • fileName: the fully qualified file name to be read
  • required: true/false on true - raises an exception of "file does not exist"

read a single properties file


  • fileName: the fully qualified file name to be read
  • required: true/false on true - raises an exception of "file does not exist"

read a single XML file

6.1 Placeholders in Set Declaration

Configuration set will be configured with a finder and specific attribute values for this finder. Each attribute value can use the placeholder "${key}" to reference an existing property of an upper scope. For example the sets for domain scope can use "cluster" scoped configuration values.

The standard configuration.xml contains placeholders for system-specific folders and environments. The way it works, for example for environments, is shown below:

  • The environment is defined in (e.g., "environment=PRD") (is defined in scope "instance" first).
  • All "PRD"-specific configurations can be placed in "" if the configuration.xml contains the

    <set finder="property" scope="cluster,server,domain" fileName="${IS_SHARE}/system/config/cluster/${environment}.properties"/>
  • The domain-specific configuration is more complex since a regular expression is used to check the matched files (e.g.,

    <set finder="domain-folder" scope="domain" matches="^${environment}_[\w&&[^_]]*$" fileExtensions="properties,xml"/>
  • In case domain properties should be environment and staging type dependent (staging.system.type mostly defined at, an additional line in the configuration.xml will load such property files (e.g.,

    <set finder="domain-folder" scope="domain" matches="^${environment}_${staging.system.type}_[\w&&[^_]]*$" fileExtensions="properties,xml"/>

7 Readers

This is the list of currently available readers (package names are abbreviated).

Reader (read URI)



reads system environment


provides access to the transient configuration set


only returns a configuration set for files ending with .properties


only returns a configuration set for files ending with .xml


provides a configuration set that reads from preferences tables


provides a configuration set that reads from preference definitions tables


provides a combined configuration set that has instances of configuration sets read from a folder that corresponds to the domain name (e.g., from ${IS_SHARE}/system/config/domains/<domain-name>_)


provides a configuration combined set with instances of configuration sets for configuration files from ${IS_SHARE}/system/config/cartridges/_ for cartridges that are assigned to the current site

8 Writers

The following writers are currently used:




immediately updates the given configuration set, does not write the configuration to another place


writes the given configuration set to the given URI as a property file, updates the given configuration set afterwards

There should be at least one default writer in your system that will get any values set to the configuration framework - and not to lose them. Therefore, the transient writer has been created which updates the transient configuration set.

A writer will only be used to write keys he is allowed to write. To this end, the getWritableKeys() function is used to check if a writer can write these keys. If no writer is found to write a key, the default writer will be used (if one is given).


  • This file defines the current environment you are in, which can be production, development, datacenter1, etc.
  • There is a key-value pair in this file: environment= someValue.
  • You can define specific properties for your environment and use the overriding mechanism for configurations to first read your environment properties and then your default properties.

10 Reloading

For development purposes, a reloading mechanism of property files has been implemented. It can be enabled by setting intershop.configuration.CheckSource in to true. The delay for checking (and necessarily reloading) the property files can be set using intershop.configuration.CheckSourceInterval (which specifies the reloading interval in milliseconds).

11 Configuration Locations

11.1 Configuration of Developer

A developer wants to open up an implementation for configuration values. So the developer has to include a line to get the configuration from the framework.

String value = ConfigurationMgr.getString(key,  defaultValue );

Providing a default value in here is the direct and best way to do it, because the code does not depend on a further configuration step.

A developer of an application type can override this defaultValue via a cartridge property file, located in the cartridge source directory <cartridge>/staticfiles/cartridge/config. These configurations are included with the configuration finder "cartridge".

11.2 Configuration of Administrator

Depending on the order in configuration.xml, you can put your configuration to these locations:



domain/site-specific configuration


domain/site-specific and cartridge-specific

IS_SHARE/system/cartridges/<cartridge>/release/config or IS_TARGET/<cartridge>/release/config (depending on cartridge location)

not site-specific / configuration coming with cartridges




11.3 Configuration of Business User

Configuration values of business users should be stored in the database. Therefore, two possibilities are available at the moment:

  • Application preferences (for functionality and behavior) and
  • Domain preferences (for data-related configuration)

The developer of the business management application is responsible to decide which is the correct location of the property.

12 Service Configurations

With Intershop 7 a new scope was introduced. The name of this scope is service and as it implies, it is used for the Managed Service Framework.

A new finder, reader, and writer have been created for this scope. The finder creates URIs for the service scope which only the reader can read and for which only the writer is allowed to write.

The reader creates configuration sets which will look into the ServiceConfigurationPOAttributeValuePO table using the ServiceConfigurationPO which has to be provided in the context used to get the configuration values from the set.

The writer, on the other hand, writes in the same table, also using the ServiceConfigurationPO provided in the context.

The service scope is somehow a standalone scope. If someone requests configurations from this scope, only one reader is triggered returning only one type of configuration set. You currently can be sure that this scope does not contain other properties than properties from the ServiceConfigurationPOAttributeValuePO table, e.g., values from the or PreferencePO table are not included. But of course, this can be changed any time by updating the configuration.xml file.


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