Populators, Converters and WsDTO concept in SAP Commerce(Hybris)

Nuray Fahri
4 min readDec 28, 2020

In this article, we will talk about data transfer objects(DTOs), Converters, Populators and finally WsDTOs.

When developing custom extensions in SAP Commerce(Hybris) you will be implementing the Converters and Populators pattern a lot in your project. Converters and populators are used in facade layer to convert the model to data. We call converter methods to convert the model to data.

Why we need them?

Let’s say we have product table(ProductModel) in the database with 50 fields but we need 10 of them to return to Front end(UI). We call our model source which has all the data from the database and we call target(DTO) the data structure which is subset of the model source and will be passed to UI. We use converters and populators to create a target DTO by converting a source Model object using Populators to populate the DTO.

We can convert models to DTO directly in facade layer , then why we should have a converter?

Because in most cases we will need to convert our model(Product in our case) from multiple places. We convert it on product listing page, product detail page, order confirmation page.As we follow OOPs concept it is good to have a separate class to do this conversion for us, from all of these places.

Converter: creates new instances of Data objects and call Populators to populate data. It contains list of populators and uses populators to convert data from source to target.

Populator: fills the data object by getting the data from the model. It’s not recommended to call populator directly in code. Conversion logic exists in populators.

Steps for defining Converters and Populators(Example with ProductData):

1. Defining data transfer object(DTO).

In <custom>facades-beans.xml add for creating new property for ProductData(DTO) and build the hybris system.

After successful build we can check our ProductData DTO(data transfer object) class at the specified package and we can see that the class contains our new property.

2. Define a Converter in <custom>facades-spring.xml.

We specify what our target object is(the DTO that we want our Converter to build)

3. Define the Populator.

Populators implement the Populator<SOURCE,TARGET> interface and implement (override) the populate method.

The populate method can be as simple as getting and setting values from the Model object (Source) to the target (DTO) or calling Services to get additional data.

4. Call the convertors convert method inside other method.

We call the converter’s covert method or the convertAll which invokes all the populators defined for that convertor in sequence.

WsDTO concept

WsDTO is data layer used by version 2 of the REST API in OCC.

WsDTO model was introduced by SAP to add stability to the REST API by removing the dependency to the commerce services data model. Changes in the commerce data model do not directly affect the REST API. It also improves flexibility by introducing a mechanism that allows control of returning fields. In v2 of the REST API, we can explicitly request specific fields to be filled in an object or use a predefined set of fields.

In older version of the REST API, services return data objects which could lead to some unexpected behaviors when fields are added or changed in the commerce services data model. Every data model change in the commerce services could influence the REST API and as a result, could affect compatibility with the service consumers.

Dynamic Field Configuration

The new WsDTO layer was introduced with a new mechanism that allows us to define fields to return by API. By default there are three configurations:

  • BASIC — only a basic set of fields that identify an object are filled.
  • DEFAULT — medium set of fields defined on the most common use cases.
  • FULL — all fields are returned.

Example ProductWsDTO

<bean parent="fieldSetLevelMapping" id="productWsDTOFieldSetLevelMapping">
<property name="dtoClass"
<property name="levelMapping">
<entry key="BASIC"
<entry key="DEFAULT"
<entry key="FULL"


Every Data object has its counterpart in WsDTO and appropriate mapping. All OCC REST API methods in v2 have changed their signatures to return WsDTO objects.

Learn more:



Make sure you give this post a clap and follow my blog if you find it helpful.