Data Model Definitions | Hybris Academy

Atomic Type

An atomic type is a simple, indivisible data type that cannot be further subdivided within the scope of the data model. These types are considered fundamental and are the building blocks for constructing more complex data structures.

Let's explore some common atomic data types with examples:

Integer
Float or Double.
Boolean
Date
Time
String

Defining an Atomic Type in items.xml: You define data models for items in XML files, such as items.xml. In these XML files, you can define item types and their attributes. Here are examples of defining atomic types in item.xml:

<itemtype code="Product" autocreate="true" generate="true">
<attributes>
<attribute qualifier="name" type="java.lang.String">
<modifiers/>
<persistence type="property"/>
</attribute>
</attributes>
</itemtype>

In this example, we define an item type "Product" with an attribute "name" of type java.lang.String. "java.lang.String" is an atomic type for representing text or string data.

Collection Type

In data modeling, a collection type refers to a data type that is used to represent and manage collections of data elements. Collections are used when you need to store multiple values of the same or different data types as a single entity.

Collection types are essential for modeling relationships between entities or for handling scenarios where multiple values need to be associated with a single entity.

The most common collection types in SAP Commerce are:

List: A list is an ordered collection that allows duplicate values. You can use a list to represent attributes like a list of product categories associated with a product.
Set: A set is an unordered collection that does not allow duplicate values. You can use a set to represent attributes like a set of tags associated with a blog post.

Defining an Collection Type in items.xml: You want to create a collection attribute to store a list of Region. Here's how you can define this in items.xml:

ENUM Type

An Enum type, short for enumeration type, is a data type that consists of a set of distinct, named values. These named values represent all the possible states or options for a particular attribute, and they are typically used to represent categorical or discrete data.

Enum types provide a way to define a restricted set of valid values for an attribute, making the data more structured and self-descriptive. Enumerations are especially useful when you want to ensure that a variable can only take on specific, predefined values.

Example of how an enum type might be defined in a data modeling context: In this example, an enum type called Gender is defined with three distinct values: MALE, FEMALE, and OTHER.

public enum Gender
{
MALE,
FEMALE,
OTHER
}

Defining an Enum Type in items.xml: To define an enum type in items.xml, you need to create a new item type with an "enum" type attribute. Here's an example of defining an enum type for representing product statuses:

<enumtype generate="true" code="ProductStatus" autocreate="true">
<description>This type is intended to set the product status of the Product.</description>
<value code="IN_STOCK" />
<value code="OUT_OF_STOCK" />
<value code="DISCONTINUED" />
</enumtype>

Map Type

A map type is a data structure that stores key-value pairs, where each key is unique within the map, and each key is associated with a corresponding value.

Maps are also known as associative arrays, dictionaries, or hash tables in different programming languages and contexts. Map types are used to model relationships between data elements and are particularly useful when you need to look up values based on their keys efficiently.

Here are some key characteristics and use cases for map types in data modeling:

Key-Value Pairs: A map consists of a collection of key-value pairs, where each key is used to access its associated value. The key is typically unique within the map.
Efficient Retrieval: Maps are optimized for efficient retrieval of values based on their keys. This allows for quick searches and lookups, making them suitable for scenarios where you need to access data by a unique identifier.
No Duplicate Keys: Keys within a map must be unique. If you attempt to insert a duplicate key, it will typically replace the existing value associated with that key.

Defining a Map Type in items.xml:

To define a map type in items.xml, you typically create a new item by declaring the code, argument type and return type. Here argument type represent the key and return type represents the value of Map. The item UrlToItem will store key-value pairs.

We have defined below UrlToItem code where key is the string value of URL and return type is the Item stored in this Map.

<maptype code="UrlToItem"
argumenttype="java.lang.String"
returntype="Item"
autocreate="true"
generate="false"/>

Relation Type

A relation type, also known as a relationship type or simply a relationship, defines the association or connection between two or more entities or data elements within a data model. Relationships play a crucial role in modeling the structure and interactions between different parts of a data model, helping to represent the complex relationships that exist in the real world.

Here are some key aspects and types of relationships in data modeling:

Cardinality: Cardinality describes the number of instances of one entity that can be related to the number of instances of another entity through a relationship. Common cardinality options include "one-to-one," "one-to-many," and "many-to-many."
Directionality: Relationships can be unidirectional or bidirectional. A unidirectional relationship means that one entity knows about the other, but the other doesn't necessarily have knowledge of the first entity. In a bidirectional relationship, both entities are aware of each other.

Here's an explanation of how relationship types are defined in items.xml:

1) One-to-One Relationship: We can define one to one relation in hybris by simply creating an attribute of item type.

<itemtype code="Employee" autocreate="true" generate="true">
<attributes>
<attribute qualifier="identityCard" type="IdentityCard">
<modifiers/> <persistence type="property"/>
</attribute>
</attributes>
</itemtype>
<itemtype code="IdentityCard" autocreate="true" generate="true">
<attributes>
</attributes>
</itemtype>

In this example, the "Employee" item type has a one-to-one relationship with the "IdentityCard" item type. An "Employee" item can have one associated "IdentityCard" item through the "identityCard" attribute.

Practical Use Case: Suppose you have an employee Steve with code "stev8848" who has one identity card with code "id299292". We can define this one to one relation as below:

</Employee>

2) One-to-Many Relationship: A one-to-many relationship between item types in the items.xml file defines a relationship where one instance of the source item type can be associated with multiple instances of the target item type. This type of relationship is also known as a "one-to-N" relationship. Let's explore this relationship type with an example.

Suppose you are modeling a simple e-commerce system where you have two item types: "Country" and "State." Each country can have one or more states, creating a one-to-many relationship.

<relation code="Country2State" generate="true" autocreate="true" localized="false" >
<sourceElement type="Country" cardinality="one" qualifier="user">
<modifiers read="true" write="true" search="true" optional="false"/>
</sourceElement>
<targetElement type="State" cardinality="many" qualifier="carts">
<modifiers read="true" write="true" search="true" optional="true" partof="true"/>
</targetElement>
</relation>

We have defined the item type with code Country2State. We have defined the source element as Country and target Element as State. We have cardinality="one" for source Element and cardinality="many " for target Element.

Practical Use Case: Suppose you have a Country as USA and you want to associate multiple states (e.g., Florida, California, Arizona) with this Country. You can use this one-to-many relationship to link the "Country" item to all the relevant State items.

<country code="USA">
<states>
<state code="Florida"/>
<state code="California"/>
<state code="Arizona"/>
</states>
</country>

3) Many-to-Many Relationship: A many-to-many relationship between item types in the items.xml file defines a relationship where multiple instances of one item type can be associated with multiple instances of another item type. This type of relationship is also known as a "N-to-N" relationship.

Suppose you are modeling a simple e-commerce system where you have two item types: "Product" and "Category." Each product can belong to multiple categories, and each category can contain multiple products, creating a many-to-many relationship.

<relation code="Product2Category" autocreate="true" generate="false" localized="false" >
<sourceElement qualifier="products" type="Product" cardinality="many" ordered="false">
<modifiers read="true" write="true" search="true" optional="true"/>
</sourceElement>
<targetElement qualifier="categories" type="Category" cardinality="many" ordered="true" collectiontype="list">
<modifiers read="true" write="true" search="true" optional="true"/>
</targetElement>
</relation>

We have defined the item type with code Product2Category. We have defined the source element as Product and target element as Category. We have cardinality="many" for source Element as well as target Element.

Practical Use Case: Suppose you have a "Clothing" category that contains multiple products, and you also have a "Sale" category that contains some of the same products. You can use this many-to-many relationship to associate these categories with the relevant products.

<category code="Clothing">
<products>
<product code="Shirt"/>
<product code="Pants"/>
<product code="Shoes"/>
</products>
</category>
<category code="Sale">
<products>
<product code="Shirt"/>
<product code="Shoes"/>
</products>
</category>

Item Type

An "item type" is a fundamental concept used to define the structure and characteristics of different data entities or objects within the Hybris. Item types serve as the blueprint for creating, managing, and querying data in a Hybris system.

Examples of Item Types:

In an e-commerce system, common item types might include "Product," "Category," "Customer," "Order," and "Payment."
For content management, item types like "CMSComponent" and "CMSPages" can be used to model web page components and pages.
Custom item types can also be created to represent domain-specific data within the Hybris system.

Define Item type in Item.xml: There are mainly 4 ways of defining item type in item.xml like creating item by extending the existing item , creating a new item without extending existing item, defining new attribute in existing table and redefining the existing attribute in the old table.

1) New Item type definition without extending existing item type: In this scenario we are going to create item type from scratch without extending any existing item type.

Practical Use Case: We have to define a table where we can store the customer id, their feedback text and the ratings given by customer.

We will define the attributes as below. Since we are creating new table we have define the autocreate="true" generate="true and also define the unique table name with unique typecode.

<itemtype code="CustomerfeedbackDetails" autocreate="true" generate="true" jaloclass="org.training.core.CustomerfeedbackDetails">
<deployment table="CustomerfeedbackDetails" typecode="17870" />
<attributes>
<attribute qualifier="customerid" type="java.lang.String">
<modifiers optional="false" unique="true"/>
<persistence type="property" />
</attribute>
<attribute qualifier="feedbacktext" type="java.lang.String">
<modifiers unique="false"/>
<persistence type="property" />
</attribute>
<attribute qualifier="rating" type="java.lang.String" >
<modifiers unique="false" />
<persistence type="property" />
</attribute>
</attributes>
</itemtype>

We will discuss the each attribute in the detail in following section:

autocreate :

The autocreate=true will create a new table in the DB.
The autocreate=false will not create a table in the DB.
In the above scenario build will fail if we set the autocreate as false since we are creating a new table entry.
We should make it to true for the first definition of item type.

generate:

The generate = true will generate the jalo class for the type.
The generate = false will not generate the jalo class for the type.
The model classes will be generated always irrespective of generate is true or false.
We should make it to true for the first definition of item type.

deployment table:

This will be the deployment table name where all the table entry will be stored.
This name should be unique to avoid any DB conflicts.

typecode:

The value of type code should be unique.
This typecode number is used to reference the table uniquely by Hybris.
The typecode value should be between 0 & 32767.
The typecode value between 0 & 10000 is already reserved by Hybris, unique value greater than 10000 should be use.

Attribute data Type:

1. Attribute data type are defined by type at attribute level.

2. The data type can be primitive like Boolean, String, Float and Integer.

3. The data type can have non-primitive type reference also.

Attribute Modifiers:
- Read:
  1. This attribute value true indicated this is readable and getter method will be automatically generated during build.
  2. The default value is true for this modifier.
- Write:
  1. This attribute value true indicated this is readable and setter method will be automatically generated during build.
  2. The default value is true for this modifier.
- Search:
1. Attribute will be searchable while searching with flexible query.
2. The default value is true for this attribute.
- Optional:
1. Optional=true means the value is optional for this attribute.
2. Optional= false means that while saving the model the attribute value is mandatory.
3. The default value is true.
- Unique:
  1. The attribute should have unique value.
  2. The default value is false.
- Initial:
1. The attribute should be set with an initial value when creating a new item of this type.
2. The default value is false.
3. It’s also good practice to use initial="true" with a default value.
4. This is especially relevant for boolean values. To avoid the setting null to the boolean field, we can define a default value "true" or "false".

Persistence type:
- Property Type: <persistence type="property"/>

This is the default persistence type in Hybris.
When you define an attribute with persistence type "property," it means that the attribute's value is stored as a column in the database table associated with the item type.
Each attribute value is stored directly in its own column, making it easy to query and update specific attributes efficiently.

Dynamic Type: <persistence type="dynamic"/>

The "dynamic" persistence type is used for attributes where the structure or type of the attribute can change dynamically without changing the database schema.
This approach is flexible and can accommodate attributes with varying data types or dynamic schema requirements.
Dynamic attributes are often used in scenarios where you need to add or modify attributes for items without altering the database schema.

2) New Item type definition by extending existing item type: In this part we are going to define new item type by extedning the existing item type.

Practical Use Case: We have to define a new functionality where product can have list of the country codes where those products should be visible.

Suppose we have product1 and product2. Porduct1 should be available in USA and product2 should be available in USA and CANADA both.

We will define the attributes as below.

<itemtype code="CustomProduct" extends="Product"
autocreate="true" generate="true" jaloclass="org.training.core.jalo.CustomProduct">
<description>Custom product extension that contains additional attributes.</description>
<attributes>
<attribute qualifier="countries" type="CountryCodeList">
<description>List of countries that the Custom Product is designed for</description>
<modifiers />
<persistence type="property" />
</attribute>
</attributes>
</itemtype>

We have defined the list of country codes which is referenced in the customproduct table. The country code list will help in writing business logic and filtering the Product based on the country code.

We have to give autocreate="true" generate="true" since we are creating new itemtype.

3) Define the new attribute in the existing item type: In some scenarios we have to define the new attribute in the existing item type to achieve the functionality.

Practical Use Case: We have to define a new functionality where product can have a flag which indicates that product is configurable product or not. Configurable product will be configured from third party system and non configurable product can be changed by customer while doing add to cart.

<itemtype code="Product" autocreate="false" generate="false">
<attributes>
<attribute qualifier="configurable" type="java.lang.Boolean">
<description>Config product flag</description>
<defaultvalue>Boolean.FALSE</defaultvalue>
<modifiers read="true" write="true" search="true" optional="false"/>
<persistence type="property"/>
</attribute>
</attributes>
</itemtype>

In the above definition we can see the autocreate="false" generate="false" since the attribute will be created in the existing item type and no new item type will be created. We have defined the attribute configurable in the product which will be used to filter the product which are configurable and non configurable in the business logic.

4) Redeclaring the existing attribute in the child item : We have some scenarios where we want to redeclare the existing attribute in the child item. For example, It might be to make an attribute read-only or modify the data type of an attribute. We can switch the read=true modifier to read=false. The type of the property can also be changed, but only to subtypes.

Practical Use Case: We can see that isocode attribute is re defined in Country item type even though its defined in its Parent item type called C2Litem. We are redefining the unique = true constraint for the isocode attribute in country table.

<itemtype code="Country" extends="C2LItem" jaloclass="de.hybris.platform.jalo.c2l.Country"
autocreate="true" generate="true">
<deployment table="Countries" typecode="34"/>
<attributes>
<attribute qualifier="isocode" type="java.lang.String"
redeclare="true" generate="false">
<modifiers read="true" write="true" search="true" optional="false" unique="true"/>
</attribute>
</attributes>
</itemtype>

We can also redefine the data type from parent to child item but the new type given in the child item should be subtype of parent attribute.