Understanding Itemtypes

SAP Hybris uses a flexible, declarative type system where developers define every platform entity – products, orders, customers, categories, media, and carts as an ItemType. In other words, it is like declaring a Java class and a database table at the same time, because that is exactly what happens behind the scenes.

Itemtype to Java to Database

How SAP Commerce Converts Itemtypes Into Data

Itemtype

Defined in items.xml

Developers define the structure of a business object using an itemtype in the items.xml file. It contains attributes, relations and modifiers.

Example:
<itemtype code="Student">

➡

Java Model Class

Used in Service Layer

When the platform builds the extension, it generates a Model class from the itemtype definition. Developers interact with this class in services and business logic.

Example:
StudentModel.java

➡

Database Table

Persistent storage

During a system update, the platform creates or updates the database schema. Each attribute defined in the itemtype becomes a column in the database table.

Example:
students

Click on any block to see more details about that layer.

Types are defined in XML configuration files named *-items.xml, located inside each extension’s resources/ directory. First, when you run ant build, SAP Hybris reads these files and generates Java model classes under bootstrap/gensrc/. Then, after a system update, it automatically creates or updates the corresponding database schema.

Itemtype XML attributes

The <itemtype> element accepts several XML attributes that govern its identity, inheritance chain, Java code generation behaviour, and database mapping strategy. Understanding each one is essential before creating any custom type.

Attribute	Default value	Description
code	–	Unique identifier for the type. Becomes the Java class name and DB table prefix. Must be globally unique across all extensions.
extends	GenericItem	The parent type this ItemType inherits from. All types ultimately extend GenericItem.
autocreate	true	If true, the type is created automatically in database during ant initialize or system update. Always set true for new custom types.
generate	true	If true, generates a Java model class (e.g. ProductModel.java). Set false only when providing a fully manual Java implementation.
abstract	false	If true, the type cannot be instantiated directly. No database table is created for abstract types — only for their concrete subtypes.

The <deployment> element

In SAP Hybris, the element is mandatory when creating a root type. In other words, this applies to any type that directly extends GenericItem and does not inherit deployment information from a parent custom type. It maps the type to a specific database table and assigns a unique internal numeric type code used by the Hybris type registry.

Attribute	Description
table	Database table name to create.
typecode	Unique integer used to refer itemtype in the database. The value of the typecode attribute must be a positive integer between 0 and 32767 (2^15-1) and must be unique. SAP Hybris reserves 0–10000 for core types. Use 10001–32767 for all custom types.

Defining Attributes

Attributes are the properties (fields) of your ItemType. Each <attribute> element maps to a database column (for property persistence) and a getter/setter pair in the generated Java model class.

Sub-Elements/ Attribute	Required	Description
qualifier	Yes	The attribute name. Becomes the Java property name (getter/setter). Convention: camelCase. Maps to the database column name
type	Yes	data type of the attribute
redeclare	No	Used to override or modify an attribute that is already defined in the parent item type
<description>	No	Human-readable documentation. Shown in the HAC type system browser and Backoffice tooltip
<modifiers>	No	Controls access, constraints, and lifecycle behaviour
<persistence>	Yes	Defines HOW the value is stored
<defaultvalue>	No	Configure default value and used it when no value given
<custom-properties>	No	Used to define additional metadata or configuration for attributes or item types. These properties are mainly used by Backoffice, Cockpit, or custom logic, not directly by the core platform

The <modifiers> Element

The<modifiers> element defines behavior rules for an attribute. It controls database constraints, service layer access, lifecycle behaviour, and deletion cascading.

Attribute	Default Value	Description
write	true	Define if the attribute is writable. If false, no setter is generated in the model class.
read	true	Define if the attribute is readable. If false, no getter is generated.
unique	false	If true, adds a UNIQUE database constraint. Ideal for business keys like email addresses, order codes, or SKUs.
optional	true	Define if the attribute is mandatory or optional. If false, adds a NOT NULL constraint to the database column.
initial	false	If true, the attribute can only be set once at item creation. Setting this to ‘true’ is only useful in combination with write=’false’.
search	true	If false, the attribute is excluded from FlexibleSearch indexing hints. Can improve performance for attributes never used in WHERE clauses.
partof	false	if true, It means that the child item belongs to the parent item, and its lifecycle is controlled by the parent. If the parent is deleted, the child is automatically deleted as well.
private	false	If true, hides the attribute from Backoffice UI and ImpEx export by default. Use for internal, system-managed, or sensitive fields
removable	true	If false, the item cannot be deleted as long as it holds a reference through this attribute.

The <persistence> element

The <persistence> element is mandatory on every attribute. This element determines whether to store the attribute value in a database column or compute it dynamically at runtime.

Attribute	Description
property	Standard persistence type. Value stored in a dedicated column in the type’s table.
dynamic	No database column. Value is computed at runtime by a Spring bean implementing DynamicAttributeHandler. The modern approach for derived or calculated values. Know more about dynamic attribute.

Itemtype Creation Scenarios

Scenario 1: Create new root Itemtype

Use this when you need a completely new entity that does not belong to any existing type hierarchy. You must provide a <deployment> element with a unique table name and typecode.

Requirement: An e-commerce company works with multiple external suppliers who provide products for the platform. The business needs to store supplier-related information such as supplier name and email id.


<itemtype code="Supplier">
	<deployment table="suppliers" typecode="10001"/>
	<attributes>
		<attribute qualifier="name" type="java.lang.String">
			<persistence type="property"/>
			<modifiers optional="false" initial="true" write="true" read="true" unique="true"/>
		</attribute>
	    <attribute qualifier="email" type="java.lang.String">
			<persistence type="property"/>
	        <modifiers optional="false" initial="true" write="true" read="true" unique="true"/>
		</attribute>
		</attributes>
</itemtype>

Scenario 2: Create new Itemtype by Extending an existing Itemtype

Developers use this approach to add domain-specific attributes while still leveraging the existing functionality of the parent type.

Requirement: An e-commerce company sells multiple product categories such as electronics, clothing, and furniture. For electronics products need to store information such as batteryLife, warrantyYears.


<itemtype code="ElectronicsProduct"
         extends="Product"
         autocreate="true"
         generate="true">
  <description>Electronics-specific product with tech specs.</description>
  <attributes>
    <attribute qualifier="batteryLife" type="java.lang.Integer">
      <description>Battery life in hours.</description>
      <modifiers optional="true" />
      <persistence type="property" />
    </attribute>
    <attribute qualifier="warrantyYears" type="java.lang.Integer">
      <modifiers optional="false" />
      <persistence type="property" />
      <defaultvalue>Integer.valueOf(1)</defaultvalue>
    </attribute>
  </attributes>
</itemtype>

Scenario 3: Modify existing Itemtype

In this case we just need to define the item type with existing item type code and add new attributes. Use autocreate=”false” and generate=”false” to inject new attributes into any existing type without subclassing.

Requirement: Add purchaseOrderNumber and approvedBy attribute in the existing Order itemtype.


<itemtype code="Order"
         autocreate="false"
         generate="false">
  <attributes>
    <attribute qualifier="purchaseOrderNumber" type="java.lang.String">
      <description>B2B PO number from the buyer.</description>
      <modifiers optional="true" />
      <persistence type="property" />
    </attribute>
    <attribute qualifier="approvedBy" type="Employee">
      <modifiers optional="true" />
      <persistence type="property" />
    </attribute>
  </attributes>
</itemtype>