Guide - Intershop Order Management - Technical Overview

1 Introduction

The Intershop Order Management System (IOM) as a middle-ware for e-commerce combines the order processes used in all various channels. It takes incoming orders from all available channels and connects them with selected order fulfillment processes. Depending on configurations, these processes are individually managed for each combination of channels. In addition, it provides the customers with greater transparency on product availability, order status, and returns. Thus, it supports call center employees, warehouse employees, and business managers in their respective work-field.

This guide gives a technical overview about the Intershop Order Management System as well as the applied technical concepts and latest technology updates.

The main target group of this document are system administrators.

1.1 Glossary

TermDescription
GDPRGeneral Data Protection Regulation
HAHigh availability
HTTPHypertext Transfer Protocol
HTTPSHypertext Transfer Protocol Secure
IOMThe abbreviation for Intershop Order Management
JMS

Java Message Service

JSONJavaScript Object Notation
OMSThe abbreviation for Order Management System, the technical name of the IOM
OMTThe abbreviation for Order Management Tool, the graphical management tool of the IOM
RESTRepresentational State Transfer
RMAReturn Merchandize Authorization
SMTPSimple Mail Transfer Protocol
SOAPSimple Object Access Protocol
Spring MVCA Web Framework implementing the Model-View-Controller Pattern

1.2 References

2 Overall Architecture

2.1 Overview

The following figure provides a very high-level overview of components of IOM, other components, required by IOM, and their relations. When going from top to bottom, the following components can be found:

All incoming communication has to go through an HTTP-Proxy, which has the following purposes and requirements:

  • Load-balance the incoming HTTP/HTTPS traffic to the IOM application servers.
  • Provide session-affinity (sticky sessions) for requests to OMT.
  • Terminate HTTPS since IOM application-servers are only able to handle HTTP traffic directly.
  • Observe health-status of IOM application servers in order to send HTTP requests to healthy servers only.

It can be seen that there are IOM application servers of two different types. Every IOM installation needs to have exactly one application server that is running IOM scalable applications and IOM singleton applications. For High availability and scaleability much more IOM application servers may be part of the IOM cluster, but these must run IOM scalable applications only. More information can be found in section IOM application server.

The IOM application servers are using two different kinds of persistent storage: a shared file-system and a database. In fact, an IOM installation is defined by its data, persisted at these two places. Therefore the persistent data have to be managed very carefully. They have to be backed up both, in order to be able to restore an IOM installation.

Finally, the IOM applications need to be able to access an SMTP server in order to send e-mails as part of implemented business processes.

iom components overview

2.2 HTTP-Proxy

Any HTTP-Proxy can be used that is fulfilling the requirements, listed in Architecture Overview. The section Ingress and Ingress Controller will give more information about actual implementation.

2.3 IOM Application Server

IOM applications are running inside Wildfly Application Server. This application server is providing many base technologies used by IOM, e.g. JMS, JPA, EJB, etc.

For further information please see https://docs.wildfly.org/.

2.4 Shared File-System

The following table gives an overview of the directory structure of IOM's shared file-system.

Sub-DirectoryDescription
archive/

Folder used to archive old data, principally sensitive one before deleting them in the database.

importarticle/Import/export of all kind of data (products, stocks, dispatches, returns)
communication-messages/Exchange of data, e.g., for orders.xml
media/Media data, e.g., product images
pdf/PDF documents created by IOM application server, e.g., invoices, credit notes, delivery notes
jobs/Reserved for projects, working files, and archived files for scheduled jobs for projects

2.5 PostgreSQL Database Server

IOM requires a PostgreSQL Database Server. For further information see https://www.postgresql.org. The section PostgreSQL Database Server will give more information on how to use the PostgreSQL Database Server along with IOM.

2.6 SMTP Server

An SMTP server is required to send different kinds of e-mails. The section SMTP Server will give more information on how to use the SMTP server along with IOM.

3 Helm Charts for IOM

3.1 Overview

IOM is delivered in the form of Docker images which are dedicated to run in Kubernetes. Intershop also provides Helm Charts for IOM, which makes it very easy to operate IOM.

A general view on the concept on how to operate IOM with the help of Helm charts is shown in the following figure. The project owner (e.g. implementation partner) has to define a set of values, which is controlling the behavior of the IOM installation. Using the Helm command-line tool along with these values and the IOM Helm charts, he or she is able to execute all tasks that are required to run IOM in a Kubernetes environment.

For more information on how to use Helm Charts for IOM  see Guide - Operate Intershop Order Management 3.0.

helm concept

3.2 Inside Helm Charts for IOM

The main goal of IOM Helm Charts is to provide a running IOM system. For this reason, the Helm Charts for IOM have to cover all components which are required to operate IOM, as described in the section above. These are:

  • HTTP-Proxy for load-balancing, HTTPS-termination, and sticky sessions,
  • IOM application servers in two different flavors: with singleton applications and without,
  • SMTP-Server,
  • PostgreSQL Database-Server with persistent storage of database data,
  • and a Shared file-system.

These components have to be translated into the world of Kubernetes.

3.3 Ingress and Ingress Controller

Within a Kubernetes environment, an Ingress-object is defining how HTTP access to the underlying service (IOM in this case) has to be made. In fact, the Ingress-object holds the configuration for load-balancing, HTTPS-termination, and sticky sessions. But the Ingress-object is a configuration snippet only. This configuration has to be applied to an Ingress controller, which is a really running software. Some different implementations of Ingress controllers exist, the most common one is the NGINX Ingress controller. Within professional Kubernetes clusters, usually, only one global Ingress controller exists, which is used by all Ingress-objects.

There are two problems the Helm Charts for IOM have to deal with:

  • An Ingress controller is not an integral part of a Kubernetes cluster. It always has to be installed as an extra component.
  • The configuration of sticky sessions within the Ingress-object is implementation-specific for NGINX Ingress controllers. If a Kubernetes cluster used a different implementation of the Ingress controller, IOM would not work as expected in this case.

To solve these problems, Helm Charts for IOM is providing an integrated NGINX Ingress controller, which can be used if necessary. This will be the case if no Ingress controller exists at all, or if the existing global Ingress controller is not an NGINX implementation. In this case, the internal NGINX Ingress controller has to be looped in as a proxy between the global Ingress controller and IOM.

The following table shows use cases and according to settings of values to control Helm Charts for IOM properly. See Guide - Operate Intershop Order Management 3.0 for examples.

#Use Casenginx.enablednginx.proxy.enabledingress.class
1global NGINX Ingress controller availablefalse--
2global Ingress controller available, but it is not an NGINXtruetrue-
3global Ingress controller not available at alltruefalsenginx-iom

nginx.enabled and nginx.proxy.enabled in the headers of the table above are two parameters that are used to control integrated NGINX Ingress Controller of IOM Helm charts. These parameters are explained in detail in Guide - Operate Intershop Order Management 3.0 | Parameters. ingress.class in the header of the table is an abbreviation for an annotation that has to be made to the Ingress objects. The corresponding Helm parameters are ingress.annotations and mailhog.ingress.annotations. Both are explained in detail in Guide - Operate Intershop Order Management 3.0 | Parameters. The same document also provides examples on how to set these parameters for different use cases.

3.4 IOM Application Servers

According to the information in Overall Architecture described above, two different types of IOM application servers exist: one with IOM singleton and scalable applications, which has to exist in each installation of IOM exactly once, and 0 or more application servers, which are running IOM scalable applications only.

The IOM Helm Charts are using a StatefulSet to realize the required behavior. Within a stateful set, the pods have fixed names, all ending with a number. The first pod (ending with 0) is the one and only, which is running IOM singleton applications.

Configuration examples and a full list of configuration parameters can be found in Guide - Operate Intershop Order Management 3.0.

3.5 SMTP Server

Different types of IOM installations require different types of SMTP-Servers. A production environment of IOM requires access to a professional EMail-Service to deliver e-mails sent by IOM. Of course, this professional EMail-Service is not part of Helm Charts for IOM.

The SMTP server, which is part of IOM Helm Charts is dedicated for test, demo and preproduction installations only. MailHog is such a kind of SMTP server, which was created especially for testing purposes. For this reason, MailHog is part of IOM Helm Charts.

MailHog is not an SMTP server only. It also provides a REST API and a web-GUI to get access to the received e-mails. Helm Charts for IOM is providing the required Ingress-object, which has to be configured in the same way as described in section Ingress and Ingress controller.

Configuration examples and a full list of configuration parameters can be found in Guide - Operate Intershop Order Management 3.0.

3.6 PostgreSQL Database Server

As with the SMTP server, different types of IOM installations have different requirements for installations of PostgreSQL Database Server. A production system of IOM requires a professionally managed PostgreSQL Database Server, providing HA features, full backup and restore capabilities, etc. 

The Helm Charts for IOM does not cover a PostgreSQL Database Server, which is suitable for a production environment. For production environments, according to PostgreSQL Database Server should be used from a service, providing all the required features or must be set up and operated manually.

The PostgreSQL Database Server, which is part of IOM Helm Charts does not provide any HA or backup/restore features. It should be used for test and uncritical demo installations only. The integrated PostgreSQL Database Server allows deciding whether to store the database data in memory or to persist them in the file-system.

Configuration examples and a full list of configuration parameters can be found in Guide - Operate Intershop Order Management 3.0.

3.7 Shared File-System

The Shared File-system is as important for IOM as the database data. Therefore production systems of IOM must use an external storage provider (e.g. Azure-Files) instead of the one, built into Helm Charts for IOM. For the same reason, the external storage provider needs to have a very good backup and restore capabilities.

Uncritical IOM installations, like test and demo installations, may use the storage provider, which is defined by Helm Charts for IOM.

Configuration examples and a full list of configuration parameters can be found in Guide - Operate Intershop Order Management 3.0.

4 Customization

An IOM installation without customization cannot do anything. It is an empty shell only that needs to be filled.

Customization of IOM consists basically of the following things:

  • An SQL configuration, defining the behavior of IOM,
  • Mail and xsl templates for creation of mails and pdf documents,
  • Deployment artifacts for various purposes, e.g. to modify business processes or to adapt customer systems,
  • Any sort of files needed otherwise, e.g. certificates.

All these data have to be provided by implementation partners in a very special way, which is described in Guide - IOM Standard Project Structure. Implementation partners can then use the caas2docker tool to create project-specific IOM docker images. These docker images can be rolled out by IOM Helm Charts.

Usually, much communication with the customer system is done via an sFTP server. This sFTP server can be considered as a part of the customized IOM system, but it is not part of IOM Helm Charts.

customization workflow

5 Monitoring

IOM provides standard metrics in Prometheus format at http://<pod-name>:9990/metrics.

6 Logging

IOM is writing all logging information to stdout. Each log-entry is written as a single line in JSON format. There are different sources of log-messages, which are all using different formats. To enable automated processing of such log-lines, all different log formats are providing unique meta-data, which give more information about the content and structure of the "real" content.

6.1 Meta-Data

KeyDescription
tenantThe name of the tenant, e.g. Intershop
environmentThe name of the environment, e.g. prod, pre-prod, etc.
logHostThe hostname of the pod that has written the log-line
logVersionThe log-type-specific version of log-format
logType

access|message|script

access: access-log of Wildfly's undertow sub-system

message: log-messages written by Wildfly Application Server, its sub-systems, and IOM

script: messages written by shell scripts, e.g. to start Wildfly, initialize the database, etc.

appNameThe name of container and customization if available, e.g. iom-app, iom-config, iom-app+ci
appVersionThe version of IOM and of customization if available, e.g. 3.0.0.0+1.2.0.0
configNameName of project configuration that was selected, e.g. ci.

6.2 access-log

Version 1.0 of access-log provides the following information:

KeyDescription
eventSourceDefault entry, made by undertow subsystem. The source of the event in the request. There is redundancy with meta-data, but the undertow sub-system should not define the content of IOM's meta-data.
hostNameDefault entry, made by undertow subsystem. The Wildfly host that processed the request. There is redundancy with meta-data, but the undertow sub-system should not define the content of IOM's meta-data.
bytesSentThe number of bytes sent in the body of the response.
dateTimeDate and time of request, using format-string: "yyyy-MM-dd'T'HH:mm:ss.SSSXXX" (see JavaDoc of SimpleDateFormat).
remoteHostIP/hostname of the host that sent the request.
requestLineThe complete request-line of the HTTP-request.
responseHeaderContent-TypeContent of response-header Content-Type.
responseHeaderSet-CookieContent of response-header Set-Cookie.
responseCodeHTTP response code.
remoteUserName of the user sending the request.
localIpIP of Wildfly Application-Server that received the request.
localPortPort of Wildfly Application-Server that received the request.
requestProtocolThe protocol of the request.
responseTimeResponse time in milliseconds.
requestSchemeThe URI scheme of the request.
requestHeaderRefererContent of request-header Referer.
requestHeaderUser-AgentContent of request-header User-Agent.
requestHeaderHostContent of request-header Host.
requestHeaderCookieContent of request-header Cookie.
requestHeaderX-Forwarded-ForContent of request-header X-Forwarded-For.
requestHeaderX-Real-IPContent of request-header X-Real-IP.
requestHeaderX-Forwarded-HostContent of request-header X-Forwarded-Host.
requestHeaderX-Forwarded-ProtoContent of request-header X-Forwarded-Proto.

For better readability the logline in the following example was formatted. The IOM application-server will always write such a log-entry to a single line.

Example
{
  "eventSource": "web-access",
  "hostName": "default-host",
  "tenant": "Intershop",
  "environment": "aks-ci",
  "logHost": "ci-iom-0",
  "logVersion": "1.0",
  "appVersion": "3.0.0.0-SNAPSHOT@19137+1.2.0.0-SNAPSHOT",
  "appName": "iom-app+ci",
  "logType": "access",
  "configName": "ci",
  "bytesSent": 0,
  "dateTime": "2020-09-15T16:56:20.697Z",
  "localIp": "10.244.1.7",
  "localPort": 8080,
  "remoteHost": "10.244.0.148",
  "remoteUser": null,
  "requestHeaderReferer": "http://global-ingress-nginx-controller.iom-3-0-0-0-nginx.svc.cluster.local/omt/app/roleAssignment/userManagement",
  "requestHeaderUser-Agent": "Mozilla/5.0 (X11; Linux x86_64; rv:72.0) Gecko/20100101 Firefox/72.0",
  "requestHeaderHost": "global-ingress-nginx-controller.iom-3-0-0-0-nginx.svc.cluster.local",
  "requestHeaderCookie": "route=1600188975.597.41.791971; JSESSIONID=stHSCG0HI0eWUgLOThNGBm-pYEtfSohEh6js3jdZ.ci-iom-0; org.springframework.web.servlet.i18n.CookieLocaleResolver.LOCALE=en",
  "requestHeaderX-Forwarded-For": "10.244.0.148",
  "requestHeaderX-Real-IP": "10.244.0.148",
  "requestHeaderX-Forwarded-Host": "global-ingress-nginx-controller.iom-3-0-0-0-nginx.svc.cluster.local",
  "requestHeaderX-Forwarded-Proto": "http",
  "requestLine": "GET /omt/static/amCharts/js/amCharts.js?version=3.0.0.0-SNAPSHOT HTTP/1.1",
  "requestProtocol": "HTTP/1.1",
  "requestScheme": "http",
  "responseCode": 304,
  "responseHeaderContent-Type": null,
  "responseHeaderSet-Cookie": null,
  "responseTime": 0
}

6.3 message-log

Version 1.0 of message-log provides the following information:

KeyDescription
timestampThe timestamp of the log message.
sequenceThe sequence number of messages.
loggerClassNameThe class name of the logger.
loggerNameThe name of the logger.
levelThe level of the logged message.
messageThe simple unformatted message w/o stack trace.
threadNameThe name of the callers' thread.
threadIdThe ID of the callers' thread.
mdcThe mapped diagnostic context entry.
ndcThe nested diagnostic context entries.
hostNameThe hostname of the IOM application server that has written the message.
processNameThe name of the process.
processIdThe ID of the process.
stackTraceThe exception stack trace (formatting characters are present, but quoted).
sourceClassNameThe class of the code calling the log method.
sourceFileNameThe source file of the code calling the log method.
sourceMethodNameThe callers' method name.
sourceLineNumberThe line number of the caller.
sourceModuleNameThe name of the module the log message came from.
sourceModuleVersionThe version of the module the log message came from.

For better readability the logline in the following example was formatted. The IOM application-server will always write such a log-entry to a single line. Additionally, the stack trace was shortened and line breaks were added, which makes the example to show invalid JSON.

Example
{
  "timestamp": "2020-09-14T09:38:14.852Z",
  "sequence": 1933085,
  "loggerClassName": "org.jboss.as.ejb3.logging.EjbLogger_$logger",
  "loggerName": "org.jboss.as.ejb3.invocation",
  "level": "ERROR",
  "message": "WFLYEJB0034: EJB Invocation failed on component CreateOrderTransmissionPTBean for method public abstract bakery.logic.valueobject.ProcessContainer bakery.logic.service.controller.Executable.execute(bakery.logic.valueobject.ProcessContainer) throws java.lang.Exception",
  "threadName": "Thread-20 (ActiveMQ-client-global-threads)",
  "threadId": 1406,
  "mdc": {},
  "ndc": "",
  "hostName": "ci-iom-0",
  "processName": "jboss-modules.jar",
  "processId": 222,
  "stackTrace": ": javax.ejb.EJBTransactionRolledbackException:  (orderPU) exception found for object 'class bakery.persistence.dataobject.configuration.connections.CommunicationPartnerDO'\n\tat
org.jboss.as.ejb3@17.0.0.Final//org.jboss.as.ejb3.tx.CMTTxInterceptor.invokeInCallerTx(CMTTxInterceptor.java:203)\n\tat
org.jboss.as.ejb3@17.0.0.Final//org.jboss.as.ejb3.tx.CMTTxInterceptor.required(CMTTxInterceptor.java:364)\n\tat
...
org.hibernate@5.3.10.Final//org.hibernate.query.internal.AbstractProducedQuery.doList(AbstractProducedQuery.java:1537)\n\tat org.hibernate@5.3.10.Final//org.hibernate.query.internal.AbstractProducedQuery.list(AbstractProducedQuery.java:1505)\n\tat
org.hibernate@5.3.10.Final//org.hibernate.query.Query.getResultList(Query.java:132)\n\tat
deployment.bakery.base-app-3.0.0.0-SNAPSHOT.ear.bakery.persistence-core-3.0.0.0-SNAPSHOT.jar//bakery.persistence.bean.configuration.connections.CommunicationPartnerPersistenceBean.getCommunicationPartnerList(CommunicationPartnerPersistenceBean.java:1087)\n\t
... 321 more\n",
  "sourceClassName": "org.jboss.as.ejb3.component.interceptors.LoggingInterceptor",
  "sourceFileName": "LoggingInterceptor.java",
  "sourceMethodName": "processInvocation",
  "sourceLineNumber": 77,
  "sourceModuleName": "org.jboss.as.ejb3",
  "sourceModuleVersion": "17.0.0.Final",
  "tenant": "Intershop",
  "environment": "aks-ci",
  "logHost": "ci-iom-0",
  "logVersion": "1.0",
  "appVersion": "3.0.0.0-SNAPSHOT@19129+1.2.0.0-SNAPSHOT",
  "appName": "iom-app+ci",
  "logType": "message",
  "configName": "ci"
}

6.4 script-log

Version 1.0 of script-log provides the following information:

KeyDescription
timestampThe timestamp of log-message, formatted by "date --iso-8601=seconds".
levelThe level of the logged message.
processNameThe name of the process that has written the message.
messageThe simple unformatted message.
additionalInfoAdditional info, belonging to the message.

For better readability the logline in the following example was formatted. The IOM scripts will always write such a log-entry to a single line.

Example
{
  "tenant": "Intershop",
  "environment": "aks-ci",
  "logHost": "ci-iom-0",
  "logVersion": "1.0",
  "appName": "iom-config+ci",
  "appVersion": "3.0.0.0-SNAPSHOT@19129+1.2.0.0-SNAPSHOT",
  "logType": "script",
  "timestamp": "2020-09-14T09:26:31+00:00",
  "level": "INFO",
  "processName": "apply_json_config.sh",
  "message": "success",
  "configName": "ci",
  "additionalInfo": "462 files were processed."
}

6.5 Configuration

Logging can be configured by a set of parameters, all having the prefix log. A detailed description of these parameters can be found in Guide - Operate Intershop Order Management 3.0 | Parameters.

7 IOM Application Server

7.1 Overview

IOM is a system that is mainly event-driven. Events are triggering business processes, which are running asynchronously within IOM application servers. These business processes may send other events, triggering other business processes, and so on. Initial sources of events may be HTTP requests, coming from outside or jobs and schedules, triggered by timers.

Technically, events are realized by JMS, and business processes are realized by message-driven beans.

iom application server

7.2 Deployment Artifacts

The following list shows the deployment artifacts of IOM and the order, they are loaded.

7.2.1 bakery.base-app-${version}.ear

The application Base contains the essential (and crucial) functionality of the IOM and it provides several functionalities used by the other applications.

7.2.2 customization

Right after base-application, applications provided by project customizations will be loaded.

7.2.3 process-app-${version}.ear

The application Process contains message-driven beans and it is the starting point of the business processes of the IOM. Typical business processes are the announcement of an order, routing of ordered articles to one or more suppliers, creation of invoice documents, or creation of payment notifications. Processes are triggered by the Control-application, by other locally running business processes, and by incoming HTTP requests. Messages are sent and received locally only, not from other application-servers.

7.2.4 bakery.control-app-${version}.war

The application Control is responsible for all processes that should be triggered periodically (scheduled). Scheduled processes are for example:

  • Continue processing of business objects in abnormal state
  • Import and export

The application Control is a singleton application and must be deployed on one IOM application server only.

7.2.5 bakery.impex-app-${version}.war

The application Impex is responsible for the import and export of selected business objects. Impex can be used to exchange data with the connected actors as required. Possible business objects can be orders, customers, or products, for example.
The application Impex is one of the singleton applications and must be deployed on one IOM application server only.

7.2.6 bakery.communication-app-${version}.ear

The application Communication is responsible for communication with external applications. Intended external applications are mostly shops and suppliers. Offered services include a general order handling, return management, stock reservation, and more. Services are offered as SOAP and REST.

For further information see:

7.2.7 bakery.omt-app-${version}.war

The application OMT is the standard graphical user interface of the Intershop Order Management System.

It can be used to manage the IOM in a more comfortable way using a common Internet browser. This tool provides functionality to manage customers, items, and orders. Due to the sensitive data a login is needed. For this purpose, the OMT comes with a user and role management.

For frontend functionality, the application uses several frameworks e.g., Bootstrap, jQuery, and others. The backend of the OMT is based on frameworks such as Spring, Spring MVC, and Hibernate.

7.2.8 oms.rest.communication-app-${version}.war

The application Communication is responsible for communication with external applications. Intended external applications are mostly shops and suppliers. Offered services include a general order handling, return management, stock reservation, and more. Services are offered as SOAP and REST.

For further information see:

7.2.9 gdpr-app-${version}.war

The application GDPR offers functionality including REST interfaces to support the General Data Protection Regulation of the IOM as well as other external systems that can be connected.

Also, see Reference - IOM REST API.

7.2.10 rma-app-${version}.war

The application RMA offers functionality including REST interfaces to support the process of Return Merchandise Authorization of the IOM as well as other external systems that can be connected.

For further information see Overview - IOM Return Merchandise Authorization and Overview - IOM REST API.

7.2.11 transmission-app-${version}.war

The application Transmission offers functionality including REST interfaces to support the message transmission handling of the IOM.

For further information see Overview - IOM REST API.

7.2.12 schedule-app-${version}.war

The application Schedule provides the functionality of customizable, timebase triggered jobs.

For further information see Cookbook - IOM Job Framework.

7.2.13 order-state-app-${version}.war

The application Order State is a replacement of the SOAP OrderState service and offers a REST interface to get the status of one or more orders for given search criteria.

For further information see Overview - IOM REST API.

7.2.14 oms.monitoring-app-${version}.war

The application Monitoring supports the monitoring of application servers.

Please see section Health Check Requests for more information.

7.3 Quartz Jobs

The message-driven beans defined by the application Control are triggered by Quartz jobs, defined in file quartz-jobs-cluster.xml. Since the application Control is rolled out on one IOM application server only, Quartz configuration becomes effectively only on the IOM application server, on which the application Control is deployed. But the Quartz sub-system and the corresponding job configuration is active on all IOM application servers. Please have this in min, when customizing Quartz jobs.

See also Reference - IOM Quartz Jobs 2.2.

7.4 Schedules

There is a second concept that enables to trigger time-based jobs: Schedules. This concept is mainly intended to be used by projects to define custom jobs. The according application Schedules is rolled out on all IOM application servers. Hence, the jobs triggered by Schedules are running on all IOM application servers, too.

Also see Cookbook - IOM Job Framework.

7.5 JMS

In contrast to traditional JMS-driven applications, Java Messages in IOM are sent and received only locally. There is no distribution of JMS events across different IOM application servers.

8 High Availability

High availability can be defined as follows:

The system is designed for the highest requirements in terms of performance and reliability. Several platform capabilities allow easy scaling without downtimes.

The following sections describe a tested and working approach to enabling IOM to be HA.

8.1 IOM Application Servers

High availability can be provided by using multiple IOM application servers running in parallel. As shown in section Overall Architecture, there are two different types of IOM application servers. Each IOM cluster needs to have exactly one IOM application server that is running IOM singleton applications. However, these IOM singleton applications do not process any requests coming from outside. Instead of it, the IOM singleton applications are only processing Jobs asynchronously. From the standpoint of High Availability, all IOM application-servers are identical in their ability to process requests synchronously. Hence, if there is at least one running IOM application server, the application will be available.

For high availability, Helm value replicaCount has to be set to 2 or higher. See Guide - Operate Intershop Order Management 3.0 | Parameters.

During updates of IOM, the system cannot be available since database migration cannot be processed while application servers are still running. For more information see Guide - Operate Intershop Order Management 3.0 | Restrictions on Upgrade.

8.2 Shared File-System

Some directories of IOM servers are containing stateful runtime data that have to be shared by all IOM servers. These directories are placed as sub-directories within the shared file-system of IOM.

It is recommended to use an HA-ready storage service for a shared file-system. Otherwise, IOM cannot be highly available. If the shared file-system is not available, all IOM servers are affected and will not be able to answer any requests.

For high availability, the Helm value persistence.storageClass has to be set to a highly available storage class. See Guide - Operate Intershop Order Management 3.0.

8.3 Load Balancer / Ingress Controller

According to section Ingress and Ingress Controller the Load Balancer / Ingress Controller can be provided globally within Kubernetes cluster or by IOM Helm Charts itself. If the global Ingress Controller is used, it has to be ensured, that it is highly available. If the integrated NGINX Ingress Controller is used, at least two instances of the controller must run. This is controlled by the parameter ingress-nginx.controller.replicaCount, see Guide - Operate Intershop Order Management 3.0 | Parameters.

8.4 Sticky Sessions / Session Failover

Session stickiness and session failover are realized by the Ingress controller. Depending on the capabilities of the Ingress controller, this is realized by the global or by the integrated NGINX Ingress controller, see section Ingress and Ingress Controller.

If one of the IOM application servers is not available, e.g. for an upgrade or technical problems, the load balancer / Ingress controller has to able to send all incoming requests dedicated for this IOM application server to one of the remaining IOM application servers. To do so, IOM provides a REST API for health check requests, which is informing the Kubernetes cluster about the state of each IOM application server. The according configuration is already part of IOM Helm charts. The health check requests support the load-balancer / Ingress controller in deciding which IOM application server to use and which not.

8.5 Health Check Requests

All IOM application servers provide a health check that can be requested using the URL /monitoring/services/health/status. It responds with HTTP status code 200 if the application server is healthy. Otherwise it responds with 5XX.

To ease error analysis, the content delivered by the health check URL contains further information about processed checks. This information is provided in a machine-readable format (JSON), which can also easily be understood by humans.

See Concept - IOM Server Health Check for more information.

8.6 Cluster Status

For an overview of all application servers within a cluster, each health check request updates the current status of the application server within the database. The cluster status can be seen using the URL /monitoring/services/health/clusterstatus. Basic authentication is required. The user also requires the permission Basic application management assigned at the root organization.

See Concept - IOM Server Health Check for more information.

8.7 High Availability Database

IOM application servers are all connecting to the PostgreSQL database.

For high availability of the whole system, also the database and connection to it have to support HA:

  • A database reconnect has to be possible.
  • PostgreSQL HA cluster must be usable.

8.7.1 DB Reconnect

To provide HA, the application servers are able to reconnect to the database without a restart.

To work properly, invalid connections must be recognized and evicted from the pool. The xa-datasource configuration defines how this happens.

IOM uses the background validation checker rather than the validate-on-match method to reduce checking overhead. Moreover, the timeouts configuration parameters may influence the reconnect behavior (old connections might not get evicted as long as the timeouts are not reached). For more information about data source configuration, see Datasource Parameters in the RedHat customer portal.

The current configuration of IOM xa-datasource looks like this:

Exemplary Configuration of XA-Datasource
# The pool size depends on the number of application servers and the database server ressources.
# It can be set at runtime by according environment variables
/subsystem=datasources/xa-data-source=OmsDB: min-pool-size="${env.JBOSS_XA_POOLSIZE_MIN}"
/subsystem=datasources/xa-data-source=OmsDB: max-pool-size="${env.JBOSS_XA_POOLSIZE_MAX}"
/subsystem=datasources/xa-data-source=OmsDB: pool-prefill="true"

# timeouts
/subsystem=datasources/xa-data-source=OmsDB: set-tx-query-timeout="true"
/subsystem=datasources/xa-data-source=OmsDB: query-timeout="3600"
/subsystem=datasources/xa-data-source=OmsDB: blocking-timeout-wait-millis="3000"
/subsystem=datasources/xa-data-source=OmsDB: idle-timeout-minutes="60"

# connection validation
/subsystem=datasources/xa-data-source=OmsDB: validate-on-match="false"
/subsystem=datasources/xa-data-source=OmsDB: background-validation="true"
/subsystem=datasources/xa-data-source=OmsDB: background-validation-millis="20000"
/subsystem=datasources/xa-data-source=OmsDB: exception-sorter-class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"
/subsystem=datasources/xa-data-source=OmsDB: valid-connection-checker-class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"

# features, that are not used or not supported by IOM
/subsystem=datasources/xa-data-source=OmsDB: interleaving="false"
/subsystem=datasources/xa-data-source=OmsDB: pad-xid="false"
/subsystem=datasources/xa-data-source=OmsDB: wrap-xa-resource="false"
/subsystem=datasources/xa-data-source=OmsDB: same-rm-override="false"
/subsystem=datasources/xa-data-source=OmsDB: share-prepared-statements="false"

# required by metrics
/subsystem=datasources/xa-data-source=OmsDB: statistics-enabled="true"

8.7.2 PostgreSQL HA Cluster

IOM supports access to PostgreSQL HA clusters, but has always connected to the master database.

A PostgreSQL HA cluster usually consists of one master server and one or more hot-standby servers. The master server is the only one that is allowed to change data. An additional witness server is needed by the failover process when the total number of servers (master + standbys) is odd.

During the failover, the IOM application must be redirected to the new master. One solution is to add a proxy layer between the IOM application servers and the Postgres HA-cluster. This proxy-layer can be realized by PgBouncer. PgBouncer has to be reconfigured on the fly (without restart) whenever the current master changes. PgBouncer being a connection pool, can also be used to limit the number of connections to PostgreSQL. More than one instance of PgBouncer should be defined to avoid single points of failure.

The IOM database connection address is defined by the Helm parameter oms.db.hostlist, which supports a number of one or more database host addresses. For more information see Guide - Operate Intershop Order Management 3.0 | Parameters.

For more information about PostgreSQL, HA clusters see http://repmgr.org and https://pgbouncer.github.io.

8.8 Clock and Timezone Synchronization

All IOM application servers and the IOM database require synchronized clocks. Additionally, all IOM application servers and the IOM database have to use the same timezone. Currently, the timezone is fixed and will be set for IOM application servers and the database to Etc/UTC.

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
Tickets