Data Modelling – Foundation on SAP Commerce

Data modelling is the foundation of SAP commerce application. It defines the structure of your application. In particular, the SAP Hybris Type System defines platform entities such as products, users, orders, and carts. Essentially, the Type System defines what data exists in your application and determines how the system stores it. It is the backbone for all business logics.

Typically, developers configure the Type System inside the items.xml file. This file is present in extensions that define or modify the data model.

For example, the core-items.xml file comes out of the box and defines basic data models and relations such as users, products, and orders.

During build and database initialization, the platform first combines the XML declarations from all used extensions. Then, it generates the corresponding Java classes and database schema.

If your new extensions needs new item types, extending existing item types, modifying relationships or adding relationships to the overall data model, you should do it in <custom-extension>-items.xml, located in its own top-level resource directory.

Structure of items.xml file


<items xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="items.xsd">
    <atomictypes>
        <atomictype />
    </atomictypes>
    <collectiontypes>
        <collectiontype />
    </collectiontypes>
    <enumtypes>
        <enumtype></enumtype>
    </enumtypes>
    <maptypes>
        <maptype />
    </maptypes>
    <relations>
        <relation></relation>
    </relations>
    <itemtypes>
        <itemtype></itemtype>
    </itemtypes>
</items>

First, SAP Commerce validates the items.xml file against the items.xsd schema. Then, the system uses the items.xsd file to define the order of type definitions. However, if the type definition order does not match the items.xsd order, the extension build fails.

AtomicTypes

AtomicType is the non-structured, non-composed and the most basic types available in SAP commerce. In addition, SAP Commerce provides mappings for many common Java object types, such as java.lang.Integer and java.lang.String.

It is used as attribute type in itemtypes.


<atomictypes>
       <atomictype class="java.lang.Object" autocreate="true" generate="false"/>
       <atomictype class="java.lang.Number" extends="java.lang.Object" autocreate="true" generate="false"/>
</atomictypes>

CollectionTypes

CollectionType allows developers to store multiple values. It contains multiple instances of types.

Collectiontype is based on java collection classes. We can build one to many or many to one relations using collectiontype.

If a collection contains atomic types, the system stores the values as binary fields in the database. However, if it contains items, the system stores their Primary Keys (PKs) as strings.


<collectiontypes>
	<collectiontype code="StringCollection" elementtype="java.lang.String" autocreate="true" generate="false"/>
    <collectiontype code="CartCollection" elementtype="Cart" autocreate="true" generate="false type="list""/>
</collectiontypes>

code: unique identifier if collection

elementtype: defines the type of element collection contain

type: via this attribute we can make use of Java collection class and some of its subclasses(List, Set)

Collectiontype has it own limitations:

However, the database limits the maximum length of a CollectionType field. As a result, if a collection contains many PKs, the system may reach the limit and truncate some entries.
As the database entry only contains the PKs, we cannot run database searches on the entries directly.

EnumerationTypes

Developers use EnumType to define a predefined set of values that they can use as an attribute type. It is similar to java enum. SAP Commerce stores all EnumType values defined in the application in a single database table named EnumerationValue.


<enumtypes>
    <enumtype code="OrderStatus" autocreate="true" generate="true" dynamic="true">
        <value code="CREATED"/>
        <value code="ON_VALIDATION"/>
        <value code="COMPLETED"/>
        <value code="CANCELLED"/>
    </enumtype>
<enumtypes>

STATIC ENUMTYPE:

A Static enum is defined in items.xml with fixed values at development time. Values are part of the codebase. To add new value in static enum we need to modify items.xml, do build and run system update.

For static enum, dynamic attribute value is false.

DYNAMIC ENUMTYPE:

Developers can add or modify Dynamic Enum values at runtime through Backoffice without code changes. To enable this behavior, they define the enum using dynamic=”true”.

MapTypes

A Maptype is a collection of key-value pairs. For each key there is a corresponding value. Developers mainly use MapType to store localized values.


<maptypes>
	<maptype code="localized:java.lang.String"
	         argumenttype="Language"
	         returntype="java.lang.String"
	         autocreate="true"
	         generate="false"/>
</maptypes>

argumenttype: This defines the key type of the map

returntype: Defines the value type of the map

RelationTypes

Developers use a RelationType to connect one item with another. As a result, it helps represent one-to-many or many-to-many relationships.

For many-to-many relations, SAP Commerce connects elements on both sides of the relation through instances of a helper type named LinkItem. For each entry in relation, there is a linkitem instance that stores the PKs of the related items.


<relations>
	<relation code="User2Orders" generate="true" localized="false" autocreate="true">
	    <sourceElement type="User" cardinality="one" qualifier="user">
	        <modifiers read="true" write="true" search="true" optional="false"/>
	    </sourceElement>
	    <targetElement type="Order" cardinality="many" qualifier="orders">
	        <modifiers read="true" write="true" search="true" optional="true" partof="true"/>
	    </targetElement>
	</relation>
</relations>

ItemTypes

An itemtype is the backbone of the SAP hybris data layer and influences everything from database tables to model classes, services, persistence, and even Backoffice behaviour.

In practice, SAP Commerce uses ItemTypes as a metadata-driven framework that defines how the system structures, stores, and accesses data. Know more about itemtype.


<itemtypes> 
    <itemtype code="Customer"
                  extends="User"
                  jaloclass="de.hybris.platform.jalo.user.Customer"
                  autocreate="true"
                  generate="true">
            <attributes>
                <!--  auto ID which is generated by NumberSeries -->
                <attribute autocreate="true" qualifier="customerID"        type="java.lang.String">
                    <modifiers read="true" write="true" search="true"    optional="true"/>
                    <persistence type="property"/>
                </attribute>
            </attributes>
        
    </itemtype>
</itemtypes>