Document Properties
Last Modified
Added to KB
Public Access
Doc Type
Guidelines, Concepts & Cookbooks
  • IOM 3.0
  • IOM 3.1
  • IOM 3.2
  • IOM 3.3
  • IOM 3.4
  • IOM 3.5

Guide - IOM Standard Project Structure

Table of Contents

Product Version


Product To Version



1 Introduction

IOM projects cannot have individual project layouts if they are to run in the Intershop CaaS environment, as this environment cannot be customized invididually for each project. Instead, IOM projects must use a predefined project layout to support the generic installation of projects in the Intershop CaaS environment.

1.1 References

2 Prerequisites

2.1 Docker

IOM is provided in form of Docker images. IOM projects have to add custom applications and configurations to these images. The customized images then have to be put into the Intershop CaaS environment for execution. To be able to manage these images, Docker v.19 is required.

2.2 IOM Docker Images

IOM is provided in form of Docker-images.

The images required as base for projects are available at:



Adapt the tag (version number), if you use a newer version of IOM. For a full list of available versions see Overview - IOM Public Release Notes. is a private docker registry. Private Docker registries require authentication and sufficient rights to pull images from them.

2.3 caas2docker

caaS2docker is a small package consisting of a shell script and configuration, which helps to create customized IOM project-images. 

This tool is provided as a Maven artifact, with following properties:

  • GroupID: com.intershop.oms
  • ArtifactID: caas2docker
  • Packaging: tar.gz
  • Version:


Adapt the version, if you use a newer version of IOM. For a full list of available versions see Overview - IOM Public Release Notes.

3 Differences and Migration From Older Version

3.1 Move of Mail Templates and XSL Templates From Configuration Artifact to Customization Artifact

The current version Standard IOM project structure was introduced along with the shift from Ansible4IOM/CaaS4Ansible4IOM to Kubernetes. The main reason for the new version was a different distribution of content to the two artifacts configuration and customization. This change was caused by the requirements of Kubernetes, where SQL-configuration is put into an init-Container and all remaining parts are placed into the app container. In order to have an 1:1 relation between the two Maven-artifacts of Standard IOM projects to the two different containers, mail templates and XSL templates were moved from the configuration artifact to the customization artifact.

3.2 Server Types Backend, Frontend, Standalone Are Not Supported Any Longer

The current version of IOM standard project structure requires IOM 3.0 and newer. This IOM version uses a single server type only: cluster.

If your CaaS project contains any server-type-specific files (e.g. etc/base/project.<server-type>.properties) you have to ensure, that these files reference server type cluster only.

4 caas2docker and Older Standard IOM Projects

Nevertheless caas2docker can be used with projects following the older version of IOM standard project structure too, if you migrate the configuration files to server type cluster. In this case there will be no 1:1 relation between artifacts configuration and customization to the according docker images. The app docker image will become a mixture of both project artifacts, but this will not be reflected by the versioning of the app docker-image. It is tagged with the version of the customization artifact only.

5 IOM Standard Project and IOM Development Environment

When working with IOM Development Environment, caas2docker provides the required project images. caas2docker is able to access and use the Maven artifacts as defined by the IOM standard project structre. It is also able to access the expanded directory structure of these artifacts directly.

In a development context this might be helpful, as fewer time will be required until the IOM Development Environment is restarted with an updated image.

standard project and devenv4iom maven

6 IOM Standard Project Provisioning

IOM standard projects have a standardized project layout, in order to be installed automatically in the Intershops CaaS environment. In general, IOM standard projects consist of two parts which both have to be provided as Docker-images. These parts are the config image and the app image.

The project owner has to provide information about these two Docker images within the values file to be used by IOM Helm charts. Additionally, the project owner can define which environment type to use, allowing him to apply different configurations for different types of environment (e.g. production, integration, etc.). For more information, see Guide - Operate Intershop Order Management 3.X.


6.1 Relation Between Docker Images and Maven Artifacts

There is a 1:1 relation between Maven artifacts and Docker images.

The content of the configuration artifact will become part of the config image and the content of the customization artifact will become part of the app image. The version numbers of both artifacts are reflected by identical version numbers of according Docker-images.

The project specific Docker images are both based on IOM Docker images provided by Intershop. The documentation of CaaS2Docker will provide you more information.

6.2 Configuration Artifact

The configuration artifact has to be a .tgz file, holding directory for sql configuration.

More information about every aspect of the configuration artifact can be found within the sections below.

directory structure of configuration artifact

6.3 Customization Artifact

The customization artifact has to be a .tgz file holding directories for:

  • Mail templates
  • XSL templates
  • Custom properties
  • Custom deployment artifacts and
  • Test data

More information about every aspect of the customization artifact can be found within the sections below.

directory structure of customization artifact

6.4 Maven Repository for IOM Standard Project Artifacts

Configuration and customization artifacts have to be provided by a single Maven repository. Both artifacts have to use identical group-IDs. The following box shows an example of a Maven repository providing both IOM standard project artifacts.

example: directory structure of maven repository
└── intershop/
    └── oms/
        ├── CaaS-test-config/
        │   ├── maven-metadata.xml 
        │   └──
        │       └── config/
        │           ├── CaaS-test-config-
        │           ├── CaaS-test-config-
        │           └── maven-metadata.xml 
        └── CaaS-test-customization/
            ├── maven-metadata.xml 
                └── config/
                    ├── CaaS-test-config-
                    ├── CaaS-test-config-
                    └── maven-metadata.xml 

7 SQL Configuration

project provisioning

SQL configuration has to be part of configuration artifact of CaaS project.

7.1 Overview

SQL configuration of projects is always a mixture of configuration of IOM standard features and project specific database artifacts.

SQL scripts are used to:

  • Create new database objects, including stored procedures,
  • Fill some core tables with required data,
  • Fill business configuration tables with data,
  • Possibly duplicate custom enumeration values definition from Java to the database to handle a chicken-egg problem,
  • Modify existing objects and data during version upgrades.

The database objects and data required by the IOM core product and their possible modifications are provided by the standard IOM product in the form of an initial dump and SQL scripts. These core SQL scripts are always performed prior to the project specific scripts, during project setup or version upgrades.

Table definitions and database functions provided for configuration of IOM can be considered as APIs that may change between core IOM Versions. The project-specific SQL scripts may rely on these APIs and must therefore be kept up to date during IOM version upgrades.

When working with different IOM versions, it may be necessary to also have different versions (branches) of the project scripts.

7.1.1 Project Specific SQL Scripts

Database initialization and configuration of project-specific customizations must be implemented with a set of SQL scripts organized in a given directory structure (see below). These scripts will always be performed after the scripts of the IOM core product.


The project specific database objects are not created during DB-initialization of the product. These object definition will also not be migrated by the IOM standard product. The project has to care for migration by itself.

The directory structure of the sql-config directory does not contain any information about project versions. For this reason, it is recommended to have a dedicated sql-config directory for each project version and to avoid migrations over more than one version at a time. This rule can be mitigated using careful script logic:

  • All scripts must be idempotent: The SQL code has to produce exactly the same result, when running again.
  • Moreover the scripts may contain tests to check if a data migration step was already performed in order to avoid repeated data updates, which can be time consuming and generate unnecessary table and index bloat.

7.2 sql-config Directory Structure

The sql-customization directory is split into three main sub-directories.

directory structure of sql-configuration
├── dbinit/
│   ├── 001_....sql
│   └── <N>_*.sql
├── dbmigrate/
│   ├── 001_....sql
│   └── <N>_*.sql
└── config/
    ├── base/
    │   ├── 001_....sql
    │   ├── 003_....sql
    │   └── <N>_*.sql
    └── env/
        ├── <env-name 1>/
        │   ├── 002_....sql
        │   └── <N>_*.sql
        ├── <env-name 2>/
        │    └── ...
        └── ...


  • SQL scripts to create database objects required by project specific customizations
  • SQL scripts to fill tables with initial data


  • SQL scripts to modify project specific database objects
  • SQL scripts to modify or delete some project data, (except configurations)

The two folders dbinit and dbmigrate are meant to organize the scripts according to their content. They will always be both executed, so you could decide to use only one of them.


  • SQL scripts to fill project specific tables created before
  • SQL scripts to fill standard (core) tables with the project business configuration
  • Provides support for environment specific configurations (e.g. production, integration test, development, etc.). Scripts in base sub-directory are always executed, whereas scripts located in one of the env sub-directories are executed only when the environment setting of current installation matches the directory name found in env sub-directory.

7.2.1 Order of Execution

The content of dbinit, dbmigrate and config are executed one after another, in this order.

All SQL scripts must have a numerical prefix. This prefix defines the order of execution within one of the three main folders starting with the lowest number.
Within config, only the numerical prefix is used to determine the execution order. The location within the sub folders base or env/<env-name> does not matter.

7.2.2 Error Handling

Each script will be processed by a separate call to the Postgres SQL client psql. In case of an error, the container (IOM init-container) will fail and Kubernetes will restart the Pod until the init Container succeeds or the timeout is passed. Only the changes performed by the current script will be rolled back. Modifications done by the previous scripts remain.

7.3 Synchronization of Java Enums

Most IOM Java Enums (or IOM Specific "extensible Enum") exist as database tables too and many SQL scripts need to refer to some of them. There is a process during the application startup that takes care of the synchronization.

This causes a chicken-egg issue as the SQL scripts must run prior to the application start during set up or upgrade processes. To solve it, such new Enum values have to be added by script as well, either in the folder dbinit or dbmigrate to register them within the database prior to the application start and make them available for following SQL scripts.

7.4 Development Scope

IOM Development Environment (devenv-4-iom) provides a process, which is able to execute sql-scripts from a directory matching the structure described above. For testing of single aspects of SQL configuration it is also possible to execute single SQL scripts.

7.5 Runtime Scope

During runtime, the SQL configuration to be executed is selected by the Helm parameter caas.envName, see section Parameters in Guide - Operate Intershop Order Management 3.0.

8 Mail Templates

project provisioning

Mail templates have to be part of the customization artifact of IOM standard projects.

8.1 Overview

Mails can be customized by projects by adding new mail templates, mail images, etc. or by overwriting existing ones.

8.2 Directory Structure

directory structure of mail templates
├── mails_customers/
│   └── ...
└── mails_operations/
    └── ...

Mail templates belonging to a project, have to be placed into the directory templates within the project package.

All sub-directories and files located in mail-templates will be copied to the directory $OMS_VAR/templates within the IOM project image. Therefore you have to use the directory structure as used in $OMS_VAR/templates too. For more information see sections Default E-mail templates and custom templates in Reference - IOM Customer E-mails. Also see Concept - IOM Customer E-mails.

There is no support for environment specific mail templates.

8.3 Development Scope

When using the IOM Development Environment (devenv-4-iom), a script is provided, which is able to roll out custom mail templates into the development environment. 

9 XSL Templates

project provisioning

Xsl templates have to be part of customization artifact of CaaS project.

9.1 Overview

Documents can be customized by projects by adding new XSL templates or by overwriting existing ones.

9.2 Directory Structure

directory structure of mail templates
├── configuration/
│   └── ...
├── shop_default/
│   └── ...
├── utils/
│   └── ...
└── ...

XSL templates belonging to a project have to be placed into directory xslt within the project package.

All sub-directories and files located in xslt will be copied to directory $OMS_VAR/xslt of the IOM project-image. Therefore you have to use the directory structure as used in $OMS_VAR/xslt too. For more information see Reference - IOM Customer E-mails 3.0.

There is no support for environment specific xsl templates.

9.3 Development Scope

When using IOM Development Environment (devenv-4-iom), a script is provided, which rolls out custom XSL templates into a running IOM Development system. 

10 Custom Deployment Artifacts

project provisioning

Custom deployment artifacts have to be part of the customization artifact of CaaS project.

10.1 Overview

Projects requiring beans (e.g. decision beans, etc.) have to provide them as custom deployment artifacts.

10.2 Directory Structure

directory structure of custom deployment artifacts
└── artifacts/
    ├── <custom deployment artifact 1>
    └── ...

The root directory holding custom deployment artifacts is named customization. All files located in customization/artifacts, the custom artifacts, will be copied to directory $OMS_VAR/customization of the installation to be customized.

One file can be placed directly in the root of customization: This file has three purposes: 

  • Defining, which custom deployment artifacts will be deployed.
  • Defining the (relative) load-order of deployment artifacts.
  • Tagging the custom deployment artifact as a singleton deployment. Hence, it will be deployed on the one application server only, which is running singleton applications. See Guide - Intershop Order Management - Technical Overview.

To mark a deployment artifact to run only on the application server that runs singleton applications, prefix the artifact name in with ##exec-backend-apps-placeholder##.


Only the configuration should be environment specific, not the project implementation. Therefore, there is no support for environment-specific deployment artifacts.

10.3 Development Scope

IOM Development Environment (devenv-4-iom) provides different processes for handling custom deployment artifacts:

11 Configuration of Logging

11.1 Standard Logging Configuration of IOM

The following box shows the default logging configuration of IOM. This configuration helps to understand the main concepts of logging in IOM:

  • There are different console-handlers logging to stdout. All these handlers use a common formatter, named JSON. The main reason for the existence of different log-handlers is the ability to control the log level of each handler separately by Docker environment variables.
  • Each handler is responsible for logging output of different Java packages. Which ones can be seen in the second part of the configuration, which assigns Java package names to the log-handlers.
  • The CONSOLE handler has no explicit assignments of Java packages. This handler is assigned to root-loggers, which do not need assignments. Instead of it this log-handler handles all unassigned java-packages too.
  • Another handler without package assignments is CUSTOMIZATION. In difference to CONSOLE, this handler will not log any messages, as long no Java packages are assigned. The assignment of Java packages has to be done in project configuration and will be described below in more detail.
default logging configuration of IOM
# configure predifined log-handlers

/subsystem=logging/console-handler=CONSOLE:       named-formatter="JSON", level="${env.OMS_LOGLEVEL_CONSOLE}"
/subsystem=logging/console-handler=IOM:           named-formatter="JSON", level="${env.OMS_LOGLEVEL_IOM}"
/subsystem=logging/console-handler=HIBERNATE:     named-formatter="JSON", level="${env.OMS_LOGLEVEL_HIBERNATE}"
/subsystem=logging/console-handler=QUARTZ:        named-formatter="JSON", level="${env.OMS_LOGLEVEL_QUARTZ}"
/subsystem=logging/console-handler=CUSTOMIZATION: named-formatter="JSON", level="${env.OMS_LOGLEVEL_CUSTOMIZATION}"

# assign java-packages to log-handlers

/subsystem=logging/logger=bakery:                    handlers=[IOM],       use-parent-handlers="false", level="ALL"
/subsystem=logging/logger=com.intershop.oms:         handlers=[IOM],       use-parent-handlers="false", level="ALL"
/subsystem=logging/logger=com.theberlinbakery:       handlers=[IOM],       use-parent-handlers="false", level="ALL"
/subsystem=logging/logger=org.jboss.ejb3.invocation: handlers=[IOM],       use-parent-handlers="false", level="ALL"
/subsystem=logging/logger=org.hibernate:             handlers=[HIBERNATE], use-parent-handlers="false", level="ALL"
/subsystem=logging/logger=org.quartz:                handlers=[QUARTZ],    use-parent-handlers="false", level="ALL"

11.2 Centralized Controlling of Log Level of Customization Artifact

The simplest logging configuration for projects can be realized by assigning all Java packages of the customization artifact to the CUSTOMIZATION log-handler. When doing so, the log level of the customization artifact can be controlled at runtime, simply by setting the Docker environment variable OMS_LOGLEVEL_CUSTOMIZATION.

The assignment of the Java packages belonging to the customization artifact is realized by adding additional entries to

The following box shows a configuration example. You can apply this settings to your own project. To do so, replace the Java package names with the names used in your project.
/subsystem=logging/logger=com.my_company.iom_customization: handlers=[CUSTOMIZATION], use-parent-handlers="false", level="ALL"

11.3 Use Different Log Levels for Different Packages of Customization Artifact

If you want to use different log levels for different Java packages of your customization artifact, you have use different logger configurations for the packages you want to log with different levels. The Docker environment variables OMS_LOGLEVEL_CUSTOMIZATION defines the lowest log level to be logged. In combination with the configuration shown below, the logging system will show the following behavior:











/subsystem=logging/logger=com.my_company.iom_customization.pkg1: handlers=[CUSTOMIZATION], use-parent-handlers="false", level="ALL"
/subsystem=logging/logger=com.my_company.iom_customization.pkg2: handlers=[CUSTOMIZATION], use-parent-handlers="false", level="WARN"

12 Custom Properties

project provisioning

Custom properties have to be part of the customization artifact of the CaaS project.

12.1 Overview

12.1.1 contains properties that can be controlled by the IOM project. The complete list of properties can be found in Reference - IOM Properties 3.0.


There are other configurations that are mainly used to control the behavior of the Wildfly application server. These are located in the file of the IOM product. The project might bring an according file, which is applied additionally to the file. This enables projects to overwrite settings made in or to add new settings. It is impossible to overwrite any property, which is defined in

12.1.3 quartz-jobs-cluster.xml

quartz-jobs-cluster.xml is deprecated since 3.0, use quartz-jobs-custom.xml instead.

It is possible to overwrite quartz-jobs-cluster.xml. This can be done globally or on certain environments only. Environment-specific quartz-jobs-cluster.xml will always overwrite a quartz-jobs-cluster.xml defined in base.

12.1.4 quartz-jobs-custom.xml (IOM version >= 3.0)

It is possible to delete standard IOM jobs, overwrite standard IOM jobs and to add custom jobs by defining them in quartz-jobs-custom.xml. IOMs standard jobs are defined in quartz-jobs-cluster.xml. During runtime of IOM, both configuration files are loaded, first quartz-jobs-cluster.xml and then quartz-jobs-custom.xml. This makes it possible to delete and overwrite IOM standard jobs. Furthermore it allows to define custom jobs as well.

quartz-jobs-custom.xml can be defined globally or for certain environments only.

Use the following template to modify or add job configuration of your project:

<?xml version="1.0" encoding="utf-8"?>
      All job information are held in RAM only, they are not persisted anywhere.
      Additionally, this file will never change during runtime, since it is part of the Docker image (product- or project-image).
      Hence, all pre-processing-commands and processing-directives have very limited impact.
      When the IOM application server starts, there cannot be any jobs, that could be deleted or overwritten.
      But, this file is loaded after quartz-jobs-cluster.xml, which defines the standard IOM jobs. This makes it possible to
      * Delete standard jobs, by using the according pre-processing-command (see,
      * Overwrite standard jobs, by redefining them here,
      * Or simply add own jobs. In this case, it is a good idea, to assign them to group CUSTOM.
    <!-- clear all jobs and trigger of group CUSTOM -->
    <!-- enable overwriting of existing jobs -->
    <!-- add custom jobs and triggers here -->

quartz-jobs-custom.xml supports the template variable ${platform.version}, which is automatically replaced by the current version of IOM. This mechanism should help you to lower maintenance efforts when referencing resources of the IOM platform.

All the standard Quartz jobs defined by IOM only trigger tasks defined by application Control, which is a singleton application running on one IOM application server only. However, the Quartz sub-system itself is rolled out and activated on all IOM application servers. Hence, using the Quartz sub-system does not restrict execution of jobs to a single IOM application server. See section Quartz Jobs in Guide - Intershop Order Management - Technical Overview.

12.1.5 initSystem.project.cluster.cli

Some configuration settings cannot be changed by, since more sophisticated CLI code is required. In this case, projects can place Wildfly CLI code directly into initSystem.project.cluster.cli file at the custom properties directory structure.

Intershop does not recommend this kind of project customization/configuration, since it will make upgrades much more difficult. You cannot rely on sub-systems, which are bundled with the current version of Wildfly. When upgrading IOM, the Wildfly version might be upgraded as well, and with it the sub-systems bundled with Wildfly might change too.

For more information, please see

12.2 Directory Structure

The root directory holding custom properties is named etc, reflecting the name of the according configuration directory of the IOM product. Within etc the well known directory structure for environment specific settings is used. Files within the base directory are applied on all installations, whereas files in the env directory are applied only if the environment is matches.


Only quartz-jobs-cluster.xml provides an environment specific configuration, any other configuration files are applied globally only.
directory structure of custom properties
├── base/
│   ├──
│   ├── quartz-jobs-cluster.xml (DEPRECATED)
│   ├── quartz-jobs-custom.xml
│   ├── initSystem.project.cluster.cli
│   └──
└── env/
    ├── <env-name 1>/
    │   ├── quartz-jobs-cluster.xml (DEPRECATED)
    │   └── quartz-jobs-custom.xml
    ├── <env-name 2>/
    │   ├── quartz-jobs-cluster.xml (DEPRECATED)
    │   └── quartz-jobs-custom.xml
    └── ...

12.3 Development Scope

IOM Development Environment (devenv-4-iom) provides a process for how to execute cli scripts.

12.4 Runtime Scope

During runtime, the configuration is selected by the Helm parameter caas.envName, see section Parameters in Guide - Operate Intershop Order Management 3.0.

13 Project Files

project provisioning

Project files have to be part of the customization artifact of the CaaS project.

13.1 Overview

Project-files provides a generic directory structure to add files and directories required by projects. The content of project-files will be copied recursively to $OMS_VAR/project-files.

An example for usage of project-files are public keys, required to automate file-transfer to external partners. Public key files have to be referenced within the file-system by the SQL-configuration. Since the structure of IOM is not fixed, SQL-configuration have to be able to determine their position within the file system in a flexible way. E.g, if the keys are all placed within the sub-directory public-keys located in project-files, the files will be copied to $OMS_VAR/project-files/public-keys. The SQL configuration has to use the according system property to create a valid reference to a key-file: "${is.oms.dir.var}/project-files/public-keys/<file 1>".

Directory Structure

Project-files does not support environment specific differences. The complete directory structure is copied recursively on all environments to $OMS_VAR/project-files.

directory structure of sql-configuration
├── <custom dir>/
│   ├── <custom dir>/
│   │   ├── <custom file>
│   │   └── <custom file>
│   └── <custom dir>
│       ├── <custom dir>/
│       │   ├── <custom file>
│       │   ├── <custom file>
│       │   └── ...
│       └── ...
└── ...

13.2 Development Scope

Project files are available in IOM Development Environment (devenv-4-iom) if they are part of the custom IOM image.

14 Test Data

project provisioning

Test data have to be part of the customization artifact of the CaaS project.

14.1 Overview

CaaS projects may require test data to be automatically loaded into the Intershop CaaS environment, e.g. test systems require this behavior. Therefore it is possible to manage test data in IOM standard projects too. Test data might be loaded for specific environments (e.g. test systems) only or on systems of any environment. Again, the familiar directory structure is used to distinguish between these options.

14.1.1 Defining Timeout for Import Process is deprecated since 3.2, use Helm parameter caas.importTestDataTimeout instead.

Loading test data is realized by the script located at $OMS_HOME/bin. Depending on the amount of test data, the behavior of the script needs to be adapted. Values to be passed at command line option --timeout can be placed in file Within this file the variable TIMEOUT can be set (shell syntax: no spaces around =), which is passed to the according command line parameters during the import process. is optional. If not overwritten by --timeout=300 is used, when running


14.1.2 Directory Structure

The root directory holding the test data is named test-data. Within test-data the well known directory structure for environment specific settings is used. Files within the base directory are copied on all installations, whereas files in the env directory are copied only if the environment matches.

directory structure of test data
├── base/
│   ├──
│   ├── <import file 1>
│   └── ...
└── env/
    ├── <env-name 1>/
    │   ├──
    │   ├── <import file 1>
    │   └── ...
    ├── <env-name 2>/
    │    └── ...
    └── ...

14.2 Development Scope

Test data are loaded into IOM Development Environment (devenv-4-iom) if they are part of the custom IOM image and the according config variables are set (CAAS_ENV_NAME has to be set to an environment containing any test-data and CAAS_IMPORT_TEST_DATA has to be set to true). 

14.3 Runtime Scope

During runtime, the environment is selected by the Helm parameter caas.envName, see section Parameters in Guide - Operate Intershop Order Management 3.0.


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