Hybris starting point

https://wiki.hybris.com/display/release5/Release+5+Documentation+Home

About the hybris Commerce Suite

The hybris Commerce Suite organizes data like product information to be propagated via multiple
communication channels in a consistent and efficient way. This enables businesses to sell products
across multiple distribution channels.

Areas of the hybris Commerce Suite

The hybris product components, such as modules and extensions are classified according to the
following areas:
 Platform area consists of a standard set of extensions that provide the main functionality of a hybris
installation.
 Content area is a centralized repository of structured information, text, web content, print layouts and
more.
 Commerce area enables management of channel neutral and channel specific business logic and
processes.
 Channel area provides management of channel specific visualization and interaction.
 hybris Commerce Suite is a complete set of hybris functionality from all areas.

Figure: Schema of hybris areas.

From Single-Channel to Cross-Channel

Distribution
For selling products you commonly cover different distribution channels. Based on consistent
single-source product information, multiple channels enable you to scale your sales activities.
Even more, you can integrate and orchestrate your marketing activities across multiple
channels.

Single Channel
A single channel can be a unique communication channel, which is for information only, or a unique
commerce channel through which goods, services, and information flow from vendor (or
manufacturer, distributor) to consumer (or business customer, dealer, distributor). Such a
transactional commerce channel, can be online (web site, electronic catalog) or offline (store, printed
material). hybris provides tools like for feeding information into channels and other tools for
implementing the channels themselves, for example a web shop, a mobile shop, a print catalog, or an
electronic catalog.

Multi Channel
Multi channel is the concept of offering not just one communication or commerce channel to your
consumers (or business customers, dealers) but multiple. In order to ensure consistent information
like product information, pricing, or promotions in all channels, a single source of truth of product data
is mandatory. This is achieved by a Product Information Management System (PIM) that tightly
integrates with channel specific applications. The hybris Commerce Suite with its strong
PIM component enables you to centrally manage product data. In addition, you easily can add
channels like e-catalogs, Point of Sales (POS) kiosk systems, mobile web shops, or call center
applications extending the options of hybris Commerce and hybris Print.

Figure: Schema of the hybris Commerce Suite. The input channels are on the left, the output
channels on the right.

Cross Channel
Based on a consistent multi channel infrastructure, companies can start guiding customers pro-
actively from one channel to the other by means of loyalty programs, store events, vouchers, gift
cards, special channel specific promotions, and more. If a consistent multi channel infrastructure is
not in place this would only confuse customers, due to disparate and often conflicting product
information, availability, and pricing information.
Figure: Cross-channel campaigns require consistent information not only about products but also
about promotions.

Customers tend to use all channels simultaneously. For example, having the printed catalog on their
desk, a customer orders a product via web shop, that is picked up and paid for in a local retail shop.
Such a cross-channel approach supports and reinforces the natural behavior of customers and
consumers.

Figure: Cross-channel hopping customers tend to use use different channels (symbolized by
horizontal layers) for stimulation, information, and purchase.

Based on the hybris Commerce Suite you can orchestrate your complementary or channel specific
marketing activities, and thus leverage your business across all distribution channels.
 Figure: A sample gift voucher loaded online but valid in both online and offline channels.

Directory Structure of the hybris Commerce Suite

All extensions developed by hybris are grouped in specific directories in the /bindirectory
to distinguish between different kind of extensions that hybris offers. Additionally,
distinguishing the /bin directory from the other directories is beneficial for both partner
developers and system administrators when updating the hybris Commerce Suite.

Directory Structure
The directory structure of the hybris Commerce Suite has a clear distinction between binary files
stored in bin directory and the other files like:

 Configuration files stored in config folder

 Data files stored in data folder
 Log files stored in log folder
 Temporary files stored in temp folder

The advantage of having the binaries directory separated from the rest of the directories is that you
can easily integrate updates of the hybris Commerce Suite. Your customized configuration files will
not be modified by the update process.
 Figure: Main directory structure of the hybris Commerce Suite.

Extension Packaging
An extension can be a part of multiple modules. To ensure that each extension exists only once, but
may be used by multiple modules, we group the extensions developed by hybris in the following
directories in the /bin directory:

 ext-accelerator
 ext-addon
 ext-channel
 ext-commerce
 ext-content
 ext-data
 ext-platform
 ext-platform-optional
 ext-template
 platform

Easier Development
One of the benefits of this horizontal directory structure is the fact that it is easier for developers to
work with the hybris system. Each extension is a separate Eclipse project with correctly configured
dependencies, and can be opened as needed in your IDE.

Figure: Main directory structure of the hybris Commerce Suite.

Technical Aspects
 The bin directory and its subdirectories do not contain any customizable configuration data. Never
change anything within this directory. During the update processes the/bin directory and its
subdirectories may be completely replaced with newer version of hybris software.

Custom Data Configuration

 Do not keep your custom data configuration in the bin directory or any of its subdirectories.

 Custom configuration data, such as the license file

and local.properties and localextensions.xml files, must reside in the /config directory.
 If no config directory is available, you will be asked on the first ant call about a configuration
template that should be used, develop or production . Please refer toConfiguration Templates for
details.
 The config directory for development is an Eclipse project and should be added as a separate
project.

Directory Structure Overview

Directory Description Environment
Variable
For details
see hybris
Environment
Variables.
/bin Contains the hybris Platform directories, the template ${HYBRIS_BIN_DI
directory and the hybris extensions directory. It may R}
also contain the directory for partner extensions or
custom extensions made by customers for their own
use.

 /bin/cus This directory is created during the process of creating

tom the custom extensions. It should contain your own
project extensions. For details about creating
extensions see Creating a New Extension.

 /bin/ext This directory contains acceleratorcms,

- acceleratorfacades, acceleratorservices,
accelera b2bacceleratorfacades, b2bacceleratorservice .
tor

 /bin/ext This directory contains addon extensions.

-addon

 /bin/ext This directory contains cscockpit, instore,

-channel mobileoptionals,mobileservices,print,printcockpit,p
rinthmc .

 /bin/ext This directory contains commerce-related extensions.

-
commerce

 /bin/ext This directory contains bmecat,

-content classificationsystems,cms2,cmscockpit,importcockpi
t,mam, productcockpit .
 Directory Description Environment
Variable
For details
see hybris
Environment
Variables.

 /bin/ext This directory contains sample data extensions.

-data

 /bin/ext It contains admincockpit, backoffice, cockpit, hmc, ${HYBRIS_EXT-

- mcc, platformhmc extensions. PLATFORM_DIR}
platform

 /bin/ext It contains optional platform extensions ${HYBRIS_EXT-

- PLATFORM-
platform OPTIONAL_DIR}
-
optional

 /bin/ext It contains all extgen templates. ${HYBRIS_EXT-

- TEMPLATE_DIR}
template

 /bin/pla The actual hybris Platform functionalities. It includes ${HYBRIS_PLATF

tform core extensions, the build framework, custom ORM_DIR}
extension templates in /extgen, application server
directories, and so on.
/config The directory contains your custom configuration files ${HYBRIS_CONFI
for the hybris Commerce Suite, such G_DIR}
as:local.properties, localextensions.xm
l, hybrislicence.jar. This directory also
contains the files for the customization mechanism of
the hybris Commerce Suite.
/data It contains runtime data, such as: ${HYBRIS_DATA_
DIR}
 Media files, such as product pictures. See also Media
folder.
 LuceneSearch indexes
 HSQLDB files

/log It contains log files from the hybris Server, JDBC ${HYBRIS_LOG_DI
logging, and so on. R}
 Directory Description Environment
Variable
For details
see hybris
Environment
Variables.
/temp It contains temporary files. ${HYBRIS_TEMP_
DIR}

hybris Environment Variables

The hybris Commerce Suite uses a number of environment variables that are defined to
reference the paths of its various components.

Default Values of Environment Variables

The table below summarizes the hybris environment variables.
Variable Name Description Factory Default

HYBRIS_BIN_DIR Points to the /bin directory of hybris/bin

the hybris Commerce Suite, in
which the platform and all
extensions are located.

HYBRIS_CONFIG_DIR Points to hybris/config

the /config directory of the
hybris Commerce Suite, where
custom configuration files are
stored.

HYBRIS_DATA_DIR Points to the /data directory of hybris/data

the hybris Commerce Suite,
where runtime data is stored.

HYBRIS_LOG_DIR Points to the /log directory of hybris/log

the hybris Commerce Suite,
containing log files from the
hybris Server, JDBC logging,
etc.

HYBRIS_TEMP_DIR Points to the /temp directory of hybris/temp/hybris

the hybris Commerce Suite,
where temporary files are stored.

By factory default, all these variables point to a directory two levels above the platform directory
plus the respective subpath. For example, if the hybris Platform is located at
C:\hybris\bin\platform, then HYBRIS_TEMP_DIR points to C:\hybris\temp\hybris by
factory default.

Platform
hybris Commerce Suite is based on a flexible modular concept that allows adding
functionality through extensions. The hybris Platform consists of a standard set of extensions
providing the main functionality of a hybris installation. An extension is a group of functions
representing a subset of the hybris Commerce Suite. An extension can contain business logic,
type definitions, a Web application, and many others. Below you can find a summary of
every hybris Platform functionality.

Architecture Overview
The hybris Commerce Suite is highly flexible and modular software. The flexibility comes
from several layers of abstraction and functionality.

Basic Architecture
From a business point of view, the hybris Commerce Suite is divided into individual packages, such
as Commerce, Content, Channel and Orders. These packages are bundles of functionality assembled
for a certain range of business functionality. All of these packages rely on more basic functionality
provided by the hybris Platform. While the hybris Platform can run without any package, no package
can run without the hybris Platform.

From a more technical point of view, packages consist of individual modules (also referred to
as extensions). For example, the hybris Print technically consists of two extensions:Print (the
technical foundation) and Print Cockpit (the graphical user interface).
Extensions are written by hybris or the implementation partner of your project. Extensions written by
hybris provide standardized functionality and are supported and maintained by hybris. If you write an
extension, you need to maintain them by yourself but you are free to implement any business
functionality you need. A full hybris Commerce Suite installation therefore consists of the hybris
Platform plus any hybris packages plus any additional extensions that you have implemented.
Extensions which are part of hybris Platform proper are also referred to as the core extensions. On
top of these core extensions, hybris Platform contains several pieces of hybris software, such as
the Build Framework, and third-party software, such as the pre-bundled Apache Tomcat.
hybris Commerce Suite is run in a Java Virtual Machine on a Servlet Container or a J2EE-compliant
application server (such as IBM Websphere or Oracle WebLogic) and connects to an external
database (MySQL, Oracle DB, Microsoft SQL Server). Internal caching and persistence mechanisms
allow the hybris Commerce Suite to run on a Servlet Container. A full-fledged J2EE-compliant
application server can be used, but is not necessary.

Figure: A technical view on the basic architecture of a hybris Commerce Suite installation.

The hybris Platform layer abstracts data from the storage structure on the database using the
persistence framework and provides functionality such as Clustering and the hybris Platform Cache.
Relying on the persistence framework, the other functional components of the Platform Layer provide
basic business functionality: Transactions, CronJobs,Personalization, Internationalization, and more.
The packages on the Functional Layer (hybris Commerce, hybris PIM, hybris Print) use the hybris
Platform to implement the functions they deliver. Actually, hybris Platform is part of any hybris
Package.

Layer Architecture
The hybris Commerce Suite contains several layers, each of which has a different function and data
abstraction level.
Figure: Overview of the architectural layers of the hybris Commerce Suite.
Layer Name Description What would a Product look like
on this Layer?

Cockpits, This is where objects are

hmc, represented in a way that an end-
WebServices user can interact with them: add
products to a cart, edit a product
description, or set a password for
a user account, for example. On
this layer it is possible to let a
user do something with an object
in the hybris Platform via a
graphical user interface.

Functionality on this level (such

as the JSF-based hybris
StoreFoundation or the ZK-based
hybris Print Cockpit) uses the
ServiceLayer for functionality
and the Type Layer for storage of
objects.

Depending on the complexity of

your implementation, this layer
can itself consist of several
individual layers and even use an
individual data model

ServiceLayer Provides the Java Application Click here to expand...

Framework Programmer's Interface (API) for
(including the objects in the hybris Commerce
actual Suite, the hybris API. The hybris
ServiceLayer, ServiceLayer relies on so-called
the models, which are POJO objects.
Infrastructure Attributes on models have
Services, and automatically generated getter
the Business and setter methods. Models are
Services) generated based on types.

Type Layer Describes business object items.xml

models. It is on this layer that
definitions of business objects
(types) and their fields
(attributes) are made via
the items.xml items.xml file.
Models are generated based on
types.
<itemtype code="Product"
extends="LocalizableItem">
<attributes>
<attribute
qualifier="code"
type="java.lang.String"/>

</attributes>
 Layer Name Description What would a Product look like
on this Layer?
</itemtype>

Persistence Deals with abstraction from the SQL-compliant representation of

Layer database, caching, and clustering. numbers and strings in a database
You are not likely to get into table, such as VARCHAR, CLOB
contact with the Persistence
Layer at all as it is completely
transparent and does not require
any explicit interaction from your
side.

Database Although not a layer of the hybris Database-specific representation of

Commerce Suite, the database is numbers and strings.
also an important component in
this overview: the database
makes the data held in the hybris
Commerce Suite persistent.

Modes of Operation
You can run the hybris Commerce Suite in three different modes of operation:
Operation Schema Graphics Description
Mode

Single The most basic mode of

Node operation. A single
machine running one
instance of a hybris
Commerce Suite
installation. Does not
have several nodes
(unlike in Cluster Mode)
and only has one set of
data (unlike Multi-Tenant
mode).
 Operation Schema Graphics Description
Mode

Cluster The hybris

Mode Cluster consists of several
individual nodes. These
nodes access a common
database and
communicate among each
other via the TCP or UDP
protocol. Summing up,
this is a multi-node,
cross-linked version of
Single Node.

Multi-
Tenant A hybris Commerce Suite
Mode in Multi-Tenant
Mode allows using
several individual,
distinguished sets of data
separated by database
table prefixes. Multi-
Tenant Mode can be used
for Single Node and for
Cluster Mode operation.

hybris Platform Cache

The hybris Cache is a part of the hybris persistence layer and enables to reduce the amount of
database queries. Therefore it improves the performance per a single server node. It
transparently stores in memory search results, item attributes and item instances.

Caching Mechanism Overview

The hybris Cache enables to reduce the amount of database queries, and therefore improves the
performance of the hybris Commerce Suite. It stores different kind of data:

 Item instances, for example a Product

 All item attributes, that is the result of getAllAttributes() or getAttribute(X) calls.
 Results of FlexibleSearch queries
 Figure: hybris Cache as a part of the persistence layer.

When Data Is Cached

The hybris Cache works transparently. Every time you access the API, the cache intercepts calls and
handles caching implicitly. The following examples present how caching works:

 Caching item attributes:

 When calling product.getCode() , the underlying data is being returned from the cache or, if not yet
cached, retrieved and written to the cache.
 When calling product.setCode(X) , the cached value is being removed (invalidated) from the cache,
because it is no longer valid.

 Caching FlexibleSeach results:

 When executing FlexibleSearch query like:

SELECT code FROM Product

the list of result is being cached in the main cache.

 When a product is removed, then its item data and the cached FlexibleSearch result for the above
query is removed from the cache.

How Data Is Cached

Since hybris 4.6 version, the hybris Region Cache replaces the previous cache solution, and gives
you much more fine-grained control over your cache configuration. With the hybris Region Cache you
can define multiple cache regions by specifying their size and eviction strategy, as well as the type
instances for which they are responsible, to find an optimal configuration for your needs. See
also Region Cache.

When Data Is Removed from Cache

A cache entry is removed from the cache in the following cases:
1. If the replacement strategy removes the entry from the cache because the cache has reached its
maximum size and cannot hold any additional entries. This is done whenever the cache is full and a
newer entry is put into the cache. It is called displacement.
2. If the cache framework knows that the cache entry is no longer valid and does not represent the
correct database content. It is called invalidation.
 Inside a single VM, the cache invalidation is done by a method call.
 When using multiple cluster nodes, the other nodes are being notified via TCP or UDP invalidation
packets. For details, see Cluster - Technical Guide.
 Invalidation is not performed whenever you change something. There are circumstances where the
invalidation is being delayed, for example when working with transactions. By default, entries modified
inside a transaction are invalidated after the transaction.

Managing the hybris Cache

Using the hybris Administration Console, you can completely clear the cache and monitor cache
statistics. Refer to hybris Administration Console - End User Guide Monitoring Tab section

Multi-Tenant Systems
The hybris Commerce Suite allows to be run in so-called Multi-Tenant Mode, in which
individual sets of data are maintained on one single hybris Commerce Suite installation. The
effect is that you can have several logical hybris Commerce Suite installations running, for
example, to host online shops for different customers on one hybris Commerce Suite.

Introduction to Multi-Tenant Systems

The hybris Commerce Suite allows using individual sets of data across one single database.

In quite a few respects, multi-tenant systems are like having several individual hybris Commerce Suite
installations:

 isolation of data between tenants

 option of using separate databases
 option of setting individual time zones and locale settings
 Each tenant has a fully individual and isolated set of data.
In general, multi-tenant systems tend to require less system memory than individual hybris Commerce
Suite installations. Multi-tenant systems are useful when a hybris Commerce Suite installation is
expected to run with several sets of data using the same code base (that is, the same hybris
Commerce Suite version), such as

 hosting a hybris Commerce Suite to several individual customers

 one single, corporate-wide hybris Commerce Suite serving individual countries with individual product
and customer data
 using the hybris Commerce's CMS module to power country-specific versions of a company website

Note
A hybris Cluster is a concept different from multi-tenant hybris Commerce Suites. A hybris Cluster is a
number of individual, separate hybris Commerce Suites sharing one single set of data, whereas a
multi-tenant hybris Commerce Suite is one single hybris Commerce Suite using individual sets of
data. For a discussion of running a hybris Commerce Suite in clustered mode, refer to the Cluster -
Technical Guide document.

General Overview
Tenants allow customizing

 the time zone (and, by consequence, the date)

 the database in use
 database URL
 database driver
 database user and password
 the available active extensions
 currency
 currency format
 date format

By consequence, it is possible for each tenant in one single hybris Commerce Suite installation to use
a different database server, a different user account on the database, and to specify the extensions
that will be available for use.
It is not possible to use different versions of the hybris Commerce Suite - all tenants will necessarily
use the same hybris Commerce Suite version (although you will be able of specifying the extensions
available to each tenant). To run different versions of the hybris Commerce Suite, you will need to use
different hybris Commerce Suite installations.

Kinds of Tenants
There are two kinds of tenant:

 the master tenant

This is the primary tenant of the hybris Commerce Suite. The master tenant:
– uses the database connection specified in the project.properties file and no database table
prefix.
– is created automatically.
– cannot be removed. Even on a non-multi-tenant hybris Commerce Suite, the master tenant will be
available.
 slave tenants

Any number is allowed.

Creating New Tenants

Tenants need to be configured in the project.properties or local.properties.
To install tenants, the property installed.tenants needs to be specified, for example. The main
purpose of the default junit, foo, t1, and t2 tenants is unit testing.
installed.tenants=junit,foo,t1,t2

Also, for each tenant, a properties file needs to be defined

as {tenant_\{tenantID\}.properties_.
The user can configure his own tenant properties files or override the current one, and the files must
be put directly under the config directory, and the naming convention
islocal_tenant_\{tenantID\}.properties.
For example, the tenant_junit.properties file has the following properties:
cronjob.timertask.loadonstartup=false
db.factory=de.hybris.platform.jdbcwrapper.JUnitDataSourceFactory

db.tableprefix=junit_
alt.datasource.ALT1.foo=bar
alt.datasource.ALT2.foo=bar

slave.datasource.A.foo=bar
slave.datasource.B.foo=bar
slave.datasource.C.foo=bar

hmc.webroot=/hmc_junit
hac.webroot=/hac_junit
The database prefix can be configured using the local_tenant_junit.properties:
db.tableprefix=myjunit_

The fact that individual tenant data sets are isolated also means that using another tenant's data is
only possible by using exactly the same database connection. Consequently, you will need to do an
initialization on every individual tenant. Initializing the master tenant does not allow any of the slave
tenant to use the master tenant's data.

Initialize the Master Tenant Before Initializing Slave Tenants

ServiceLayer
The hybris ServiceLayer is an API to develop with and for the hybris Commerce Suite.
The main characteristics of the ServiceLayer are:

 It is based on a service-oriented architecture.

 It provides a clean separation of business logic and persistence logic.
 It provides a number of services, each with its well-defined responsibilities.
 It provides a framework to develop your own services and to extend existing ones.
 It is heavily based on the Spring Framework.
 It is based on common patterns, such as interface-oriented design and dependency injection.
 It is the layer in which partners should implement their business logic.
 It provides hooks into model life-cycle events for performing custom logic.
 It provides hooks into system event life-cycle events such as init and update process.
 It provides a framework for publishing and receiving events.

Figure: Overview of the integration of the hybris ServiceLayer. For a discussion of the
components, please refer to ServiceLayer Architecture.
The ServiceLayer aims to be:

 Consistent
 Easily approachable
 Comprehensive
 Adaptable
 Extensible
 Flexible

ServiceLayer Architecture
The ServiceLayer uses a variety of different architecture concepts. Some of these are
optional, others are mandatory.
 Structure Overview
The ServiceLayer can be described as a layer of services on top of the persistence layer. The
services themselves can be divided into subcomponents.

Figure: The ServiceLayer (blue) interconnects the persistence layer with the client. Arrows indicate
exchange of data objects.

Architectural Components

Client
A client in this context is any software component that uses the ServiceLayer, such as:

 Page Controllers of an MVC framework

 Web Service clients
 Scripts
 Other services

Services
A service holds the logic to perform business processes and provides this logic through a number of
related public methods. These public methods usually are defined in a Java interface. Most often
these methods operate on the same kind of model object, for example product, order and so on.
 Services are expected to abstract from the persistence layer, that is, to only contain functional logic
and no persistence-related code. That means if you implement a service, make sure to implement it in
a way that the underlying implementation is as loosely coupled to the persistence layer as possible.

Figure: Sample of relations between services. Note the pattern of having an interface and an
implementation per service.
The hybris Commerce Suite exposes all of its functionality through services. There are the following
kinds of services:

 Business Services implement business use cases, such as cart handling or back order.
 Infrastructure Services provide the underlying technical foundation, such as internationalization,
import, export and so on.
 System services provide functionality required by the ServiceLayer, such as model handling and
session handling.

The service methods should be as fine-grained as possible to enable reuse.

Extensions must provide their functionality as services. Per extension you may provide as many
services as you deem necessary, not only one.
Services may use other services to perform their tasks but should keep their interdependencies to a
minimum in order to avoid overly tight coupling with other components.
In a project, you may write your own services to either provide unique functionality or to aggregate
other services' functionality.
Although technically not necessary, hybris recommends implementing services in terms of interfaces.
See Spring Framework in the hybris Commerce Suite for reasons why.
Services interact with other components through models. For details see section Models below.

Strategies
A service may delegate parts of its tasks to smaller micro-services, called strategies. The service then
serves as a kind of facade to the strategies. Clients still use the service and its stable API. But under
the hood the functionality is split into multiple parts. Because these parts are smaller and very focused
to their task, it is easier to adapt or replace them. Strategies therefore help to further encapsulate
behaviour and make it more adaptable.
 Figure: Sample of a service (consisting of an interface definition and the related implementation)
relying on strategies. Note how the strategies also follow the pattern of interface definition and related
implementation.

DAOs
A DAO (Data Access Object) is an interface to the storage back end system. DAOs store and retrieve
objects. You use DAOs to save, remove, and find models.
DAOs are the place to put SQL or FlexibleSearch statements and nowhere else. This is to ensure
further decoupling from the underlying storage facility.
DAOs interact with services via models and with the database via FlexibleSearch and SQL
statements.
Icon
In the hybris Commerce Suite, DAOs use the hybris Type System for persistence. This means that
hybris Commerce Suite DAOs do not implement any individual logic and simply call the underlying
persistence layer.

Models
Models are a new way to represent hybris items. Each model contains all item attributes from all
extensions thus unifying access to an item's data. Models are generated from the type system of the
hybris Commerce Suite; see Type System Documentation. Furthermore they are more or less simple
POJOs (Plain Old Java Objects) that can be used without any storage facility. Thus, it's pretty easy to
mock them up, for example for testing and debugging.
Models are used by DAOs, services, strategies, converters, and facades.

Installation Guide

 Added by Arnold Späing | hybris, last edited by Mateusz Wiktor | hybris on 02.09.2013 CEST (view change)
 show comment

This document is a comprehensive guide on installing the hybris Commerce Suite. Inside you
can find the following information:

 Quick Installation and Full Installation guides:

 Information about hybris Server
 Information about Installing Licenses
 Configuration Guide
 Compatibility with Third-Party Components
 Instructions on setting up a production system
 Description of hybris PackageManager 2.x

hybris Server
The hybris Commerce Suite comes with a preconfigured and highly optimized server based on
Apache Tomcat for development and production.

Overview on the hybris Server

The hybris Commerce Suite comes pre-bundled with a Apache Tomcat web container plus
configuration settings. The Apache Tomcat can be used out-of-the-box for development and
production use. This concept of a pre-bundled Apache Tomcat and configuration settings is called the
hybris Server.

To deploy new versions of the hybris software, you can simply replace the entire hybris Server with a
newer version.

Advantages and Benefits

The concept of the hybris Server brings a lot of advantages and benefits for you:

 You can use proven standards (Tomcat) but get professional support, documentation and know-how
from hybris
 Very fast deployment cycles
 Simplified hosting
 Setup and configuration process is exactly the same on development machines and production
environments.
 The hybris Commerce Suite does not need extended JEE features like EJB or JMS. The complete
hybris stack is very lightweight and only needs a Servlet 2.5 compliant web server. The hybris
Commerce Suite does not need a JEE compliant application server. For executing background tasks
like CronJobs or administration tasks, you can even run the hybris Commerce Suite as a standalone
Java application – completely without any application server or web server.
 With various enhancements like automatic updating functionality, a refurbished directory layout and a
completely preconfigured and optimized Server based on standard Apache Tomcat technology, hybris
dramatically simplifies the deployment of productive systems. hybris fully supports virtualized
environments and helps you by providing preconfigured virtual images for development and
production to further reducing the effort of installing and updating the hybris Software.

Starting the hybris Server

Basically, you can start the hybris Server in these ways:

 From the command line.

 As a system service.
 Starting the hybris Server From the Command Line
Normal operation mode:

1. Navigate to the ${HYBRIS_BIN_DIR}/platform directory.

2. To start the hybris Server:

 On Windows systems—call the hybrisserver.bat file.
 On Unix systems—call the hybrisserver.sh file, such as: ./hybrisserver.sh

Debug operation mode, requiring develop configuration template:

1. Navigate to the ${HYBRIS_BIN_DIR}/platform directory.

2. To start the hybris Server:

 On Windows systems—run the hybrisserver.bat file with the debug parameter, such
ashybrisserver.bat debug.
 On Unix systems—call the hybrisserver.sh file with the debug parameter, such
as./hybrisserver.sh debug.

Starting the hybris Server as a Service

Refer to http://technet.microsoft.com/en-us/library/cc736564(WS.10).aspx: Microsoft Technet on
using services.
To run the hybris Server as a system service, you need to install the hybris Server.

Installing the hybris Server as a Service

Under Microsoft Windows systems:

 Navigate to the ${HYBRIS_BIN_DIR}/platform/tomcat-6/bin directory.

 Call the InstallTomcatService.bat file.

Removing the hybris Server Service

To remove the hybris Server service:

 Navigate to the ${HYBRIS_BIN_DIR}/platform/tomcat-6/bin directory.

 Call the UninstallTomcatService.bat file.

Using the hybris Server

Included
Icon
The hybris Server binaries are bundled with the hybris Platform. You do not need to download the
hybris Server seperately.
You can use the hybris Server in two scenarios without major re-configuration in between:

 Development:
You run the hybris Server on the same machine on which you develop. An explicit deployment is not
necessary.
 Production use:
The hybris Server is run on a machine different from the one on which you develop. Usually, some
sort of deployment process is used.

Development Operation
Basically, the setup procedure is the same for both development and production scenario. Refer to
the Local Installations document for details on installing the hybris Commerce Suite.
During the first hybris Commerce Suite build, select the develop configuration template.
After that, you can develop your extension(s). To "deploy" modified extensions or configuration,
simply restart the hybris Server. During restart, the modified extensions and configuration will be
loaded automatically.

Production Operation
Production operation differs from development mainly in the fact that you will want to deploy the
hybris Commerce Suite on a remote server.
During the first hybris Commerce Suite build, select the production configuration template.

Installation
Basically, the setup procedure is the same for both development and production scenario. Refer to
the Local Installations document for details on installing the hybris Commerce Suite.

Deployment
Deployment takes place in these phases:

 Building the deployment files

 Deploying the deployment files
 Building and restarting the hybris Commerce Suite

Building the deployment files

1. Call ant production on the development machine.

This may take a while and will create two files:
 hybrisServer-Platform.zip
This file contains the hybris Server. You will only need to deploy this file if you want to update the
hybris Server (for example, to install a new version of the hybris Commerce Suite).
 hybrisServer-AllExtensions.zip
This file contains the extensions of the hybris Commerce Suite. Does not contain the hybris Platform,
which is contained in the hybrisServer-Platform.zip file as part of the hybris Server.

Deploying the deployment files

1. Stop the hybris Server on the remote server if running.

2. Copy the hybrisServer-AllExtensions.zip file to the remote server.
3. Delete the directories in the ${HYBRIS_BIN_DIR} directory, except for /platform.
4. Unzip the hybrisServer-AllExtensions.zip file into the ${HYBRIS_BIN_DIR} directory.
This way, you will replace the existing non-platform extensions with the new versions.
5. If you want to deploy the hybris Server as well:
a. Copy the hybrisServer-Platform.zip file to the remote server.
b. Delete the /platform directory in the ${HYBRIS_BIN_DIR} directory.
c. Unzip the hybrisServer-Platform.zip file into the ${HYBRIS_BIN_DIR} directory.
This way, you will replace the existing hybris Server including the hybris Platform with the new
versions.

Building and restarting the hybris Commerce Suite

1. Build the hybris Commerce Suite on the remote server:

 Open a command shell.
 Navigate to the ${HYBRIS_BIN_DIR}/platform directory.
 Make sure that a compliant Apache Ant version is used:
 On Windows systems, call the ${HYBRIS_BIN_DIR}/platform/setantenv.bat file. Do not close
the command shell after this call as the settings are transient and would get lost if the command shell
is closed.
 On Unix systems, call the ${HYBRIS_BIN_DIR}/platform/setantenv.sh file, such as: .
./setantenv.sh
 Call ant clean all to build the entire hybris Commerce Suite.

2. Restart the hybris Server:

Normal operation mode:

a. Navigate to the ${HYBRIS_BIN_DIR}/platform directory.

b. To start the hybris Server:

 On Windows systems—call the hybrisserver.bat file.
 On Unix systems—call the hybrisserver.sh file, such as: ./hybrisserver.sh

Debug operation mode, requiring develop configuration template:

c. Navigate to the ${HYBRIS_BIN_DIR}/platform directory.

d. To start the hybris Server:

 On Windows systems—run the hybrisserver.bat file with the debug parameter, such
as hybrisserver.bat debug.
 On Unix systems—call the hybrisserver.sh file with the debug parameter, such
as./hybrisserver.sh debug.

Running the hybris Server as a Service

The hybris Server can optionally be installed as a service. Run as a service, the hybris Server can be
started, restarted and stopped more conveniently than when run in a shell (as is done by
the hybrisserver.bat / hybrisserver.sh files).

Security Patching
You might want to update your system to a more secure Apache Tomcat installation.The reason for
that could be that a certain AJP protocol connector implementations in Apache Tomcat (6.0.0 through
6.0.33, 5.5.0 through 5.5.33, and possibly other versions) allow remote attackers to spoof AJP
requests, bypass authentication, and obtain sensitive information by causing the connector to
interpret a request body as a new request. More information on security issues you may find on pages
linked in See Also panel.
 To patch the hybris Server you need to:

1. Download the tomcat-coyote.jar file from Apache Tomcat 6.0.35. It can be obtained from the
official Apache package within the tomcat-6/lib folder.

2. Replace the old file:

a. Shutdown the hybris Platform.

b. Go to bin/platform/tomcat-6/lib folder and replace the old tomcat-coyote.jarfile with the
newly downloaded file.
c. Restart the hybris Platform.

3. Create a text file in the tomcat-6/lib folder called tomcat-coyote_updated_to_6-0-35.txt.

That way anybody that checks the folder will know it has been updated.

Configuring the hybris Server

Generally, there are these sorts of configuration settings when you use the hybris Server. All of these
settings come in the form of properties and can be defined or overridden via
the local.properties Configuring the Behavior of the hybris Commerce Suite file, but they affect
different aspects of the hybris Server.

 Tomcat-specific properties
 hybris Commerce Suite specific properties
 Log4J-specific properties

The process of how these properties are loaded and take effect have similiarites and differences:

 All kinds of properties are defined (or overridden) in the local.properties Configuring the
Behavior of the hybris Commerce Suite file.
 All kinds of properties are loaded on the hybris Server start-up from the file system.
 Tomcat-specific properties are written to a Tomcat configuration file during the hybris Commerce
Suite build, while the hybris Commerce Suite specific properties and Log4J-specific properties are not
written to any other file.
Although the Tomcat-specific properties will be available by hybris Commerce Suite runtime and can
be read and set, modifying these values will have no effect: by the time you could set the values "from
inside", the Java Virtual Machine is already running.

The aspect that properties are read in during the hybris Server start-up means that you will not have
to re-build the hybris Commerce Suite after you have made the hybris Commerce Suite specific
changes to the local.properties file. Instead, restarting the hybris Server will do; the hybris
Server will pick up the modifications on restart. If you have modified Tomcat-specific properties in
the local.properties file, you will have to call ant deploy for the changes to take effect.

Refer to the Build Framework for details.

Tomcat-Specific Properties
The following table contains a list of all configuration properties specific to the hybris Server's Apache
Tomcat in the project.properties file of the hybris Commerce Suite. You can override the
factory default values via the local.properties Configuring the Behavior of the hybris Commerce
Suite file.
 Property name Property description

tomcat.http.port Specifies the port that allows access to the hybris Suite via an
unsecured connection.

tomcat.ssl.port Specifies the port that allows access to the hybris Suite via an
SSL-secured connection.

tomcat.jmx.port Specifies the port that allows access to the hybris Suite via
JMX.

tomcat.javaoptions Java runtime options for the hybris Server in normal operation
mode (hybrisserver.bat / hybrisserver.sh)

tomcat.debugjavaoptions Java runtime options for the hybris Server in debug mode
(hybrisserver.bat debug / hybrisserver.sh
debug)

tomcat.generaloptions Java runtime options for the hybris Server used in both the
normal operation mode and debug mode.

production.output.path The directory into which the files created by ant

production will be created. For details, please refer
to hybris Server.
Tip

Apache Tomcat-specific configuration files also available

There may be situations in which you might have to modify advanced, Apache Tomcat-specific
settings. In this case, you can directly modify the configuration of the hybris Server's Apache Tomcat.
The ${HYBRIS_CONFIG_DIR}/tomcat/conf directory contains configuration files for the Apache
Tomcat and the Tanuki Java Wrapper, such as server.xml. Modifying these files is for advanced
users and in most situations, you will not have to do that.

hybris Commerce Suite Specific Properties

These define runtime parameters for the hybris Commerce Suite, such as cache size, CronJob, or
LDAP settings. These make up the large majority of all available properties.
Basically, these are the settings for the hybris Commerce Suite and do not affect the application
server directly. These settings are not discussed here in depth, refer to theConfiguration Properties
Reference instead.
You can override the factory default values via the local.properties Configuring the Behavior of
the hybris Commerce Suite file.

Log4J-Specific Properties
Although a subset of the hybris Commerce Suite specific properties, Log4J-related properties are
handled in a special way. Log4J-related settings are loaded prior to the hybris Commerce Suite
specific properties, but are not written to any persistent file (as is the case with Tomcat-specific
properties).
You can override the factory default values via the local.properties Configuring the Behavior of
the hybris Commerce Suite file.
 Projects

 Attachments:1
 Added by Thomas Hertz | hybris, last edited by Karolina Bargiela | hybris on 28.06.2013 CEST (view change)
 show comment


Consult project-related information and benefit from our documented experiences in various
projects. Consult the projects pages in order to prepare and support your project.
See Also

 Home of Release 5

Project Quick Start

 hybris Commerce Accelerator Documentation

Basics
 How To Set up the hybris Commerce Suite as an Eclipse Project - Tutorial
 Project Tips and Pitfalls - Best Practices
 Configuring User Roles in the hMC - Best Practices

Import
 ImpEx Import - Best Practices
 How To Import from Multiple Data Sources - Tutorial
 Extract, Transform, and Load (ETL) Tools

Products and Catalogs

 Catalog Module - End User Guide
 Define Product Attributes
 Product Modeling
 Modeling Product Variants
 How to Implement Size Conversion Systems for hybris Catalogs

Migration
 hybris Migration Guide

Testing
 Testing in the hybris Commerce Suite
 Selenium
 JMeter Quick Start

Administration in the hybris Commerce Suite


 Added by Lukasz Gornicki | hybris, last edited by Jamie Sawyer on 15.10.2013 CEST (view change)
 show comment

You can administer the hybris Commerce Suite using different tools, depending on what you
really want to administer, if it is hybris Commerce Suite installation or its data model. Find
more information in the documentation in the table below:

Application Performance and Monitoring


 Added by Lukasz Gornicki | hybris, last edited by Jamie Sawyer on 15.10.2013 CEST (view change)
 show comment

After deploying your hybris Commerce Suite, you need to measure its performance. You
should monitor all parts of your installation, like network traffic, database and many other
areas. You also should find out how to fine-tune performance of your system. Find more
information in the documentation in the table below: