OCC Layer in Hybris

OCC Stands for Omni Commerce Connect. By enabling OCC layer/module, hybris exposes a set of API which can be consumed or utilized by third party. It enable the seamless integration anywhere in the landscape.

OCC layer can be enable using Extension creation way or Addon creation way [deprecated as of the 2205 release of SAP Commerce]

OCC comes with 2 kind of version i.e. V1 & V2. V1 is stateful while V2 is stateless (default one). In V2 customer data is not longer preserved between the 2 calls. Each time Customer need to provide the customer or cart details in url. And in V1, the customer cart and other customer data are stored in the session, and are preserved between subsequent requests (basing on the assumption the JSESSIONID is stored).

Important Aspect of OCC Layer

  1. OAuth Security – refer another blog
  2. Filter List
  3. Caching in OCC – refer another blog
  4. Exception Handling in OCC
  5. DTO Mapping in OCC
  6. XML/JSON Conversion

Filter list are the set of java class called before & after the request lands to controller. There are a list of filter which get called to process the request. The list of filters are managed in filter-config-v2-spring.xml.

For security we have springSecurityFilterchain & userMatchingFilter. These 2 filters takes care of Authentication and session management. userMatchingFilter read the URL and as per the URL pattern is persists the customer into the session on every request

execeptionTranslationFilter – This filter catches & resolves exception thrown from other filter

There are also some generic platform filter which performs different activities are present in filter chain. These filters are log4jFilter, corsFilter, restSessionFilterV2.

cartMatchingFilter – It is used to pull the current cart into the session.

commerceWebservicesSessionLanguageFilterV2 – When we request a data from an API in a particular language, and if there is not data in that language, empty content get returned instead of fallback language data. This filter can be customized to manage the fallback language functionality. Similarly we have commerceWebservicesSessionCurrencyFilterV2 for dealing with currency parameter.

Exception handling mechanism for OCC layer is the well planned to display the only required information in case of error. Its default implementation exist in webservicescommons extension. It provides a common error response format & mapping of response status for exceptions.

The RestExceptionResolver allows you to define generic error messages so that internal information is not leaked. Below is the bean implementation for exception handling

The WebserviceErrorFactory is used in error handling mechanism to convert exceptions to ErrorWsDTO objects. We can configure the way the exceptions will be converted to ErrorWsDTO object by adding our converter to a list in 


The configuration for DTO mapping allow the mapping of data between source and destination. It allows us provide a list of fields we want to map. The Configuration file for DTO mapping is

/ycommercewebservices/web/webroot/WEB-INF/config/v2/dto-mappings-v2-spring.xml file.

It contains the the DefaultDataMapper which  uses FieldSetBuilder and GeneralFieldFilter to map only specified fields of destination object.

In order to do a custom data mapping we need to do modify the below kind of code in above mentioned xml file.

We can define the field level attribute for any customization in this bean field. In request body we get parameter upon that basis the BASIC, DEFAULT or FULL mapping happens.

OCC Layer allow us to convert the DTO object to their text representation (either JSON or XML) used in REST calls. The DTO are the POJO classes defined in commercewebservicescommons-beans.xml file. Below bean is used for converting the response :

<alias name=”jaxbMessageConverters” alias=”messageConvertersV2″ />

OCC Layer provides interactive OCC REST API documentation called swagger UI. We can open the swagger UI in the browser by calling below URL


By Providing the authentication and authorization we can access the API from the swagger and test the API’s functionalities.

In order to enable or display our custom API in swagger we need to add some annotation in method declaration in controller.

@Operation – This annotation is require to make API available in Swagger UI.

@ApiBaseSiteIdUserIdAndCartIdParam – This annotation indicates that the request parameter should contain basesite id, userid & cart id.

Leave a Reply

Your email address will not be published. Required fields are marked *