Introduction
If you are working with SAP Commerce, one file you will encounter frequently is:
items.xmlWhether you are creating a new business entity, adding an attribute to an existing type, creating a relation, or extending a platform item type, items.xml is usually involved.
However, simply knowing the XML syntax is not enough.
A good SAP Commerce developer should understand what happens after an items.xml definition is processed and how it relates to:
- Type System
- Model classes
- Database persistence
- FlexibleSearch
- Relations
- Backoffice
- Impex
- Service Layer
In this article, we'll examine the most important items.xml configurations using practical examples.
What is items.xml?
items.xml is an SAP Commerce configuration file used to define the platform's data model.
It can define:
- Item types
- Attributes
- Relations
- Enum types
- Collection types
- Map types
- Inheritance
- Persistence configuration
- Deployment configuration
- Attribute modifiers
A simplified flow is:
items.xml
↓
Type System
↓
Generated Model
↓
Service Layer
↓
Persistence
↓
DatabaseWhere is items.xml Located?
In a custom extension, it is commonly located under:
<extension>/resources/<extension>-items.xmlThe exact filename can vary according to the extension's configuration.
For example:
customcore
└── resources
└── customcore-items.xmlBasic Item Type Definition
Let's create a simple custom item type.
<itemtype code="CustomerPreference"
extends="GenericItem">
<attributes>
<attribute qualifier="preferenceName"
type="java.lang.String">
<modifiers read="true"
write="true"
optional="false"/>
<persistence type="property"/>
</attribute>
</attributes>
</itemtype>This defines:
CustomerPreferencewith the attribute:
preferenceNameUnderstanding the itemtype Element
The itemtype element defines an SAP Commerce item type.
Example:
<itemtype code="CustomerPreference"
extends="GenericItem">The important properties are:
code
Defines the unique type code.
code="CustomerPreference"extends
Defines the parent type.
extends="GenericItem"This allows the custom type to inherit properties from the parent.
GenericItem
GenericItem is a fundamental SAP Commerce item type.
A custom persistent item often ultimately inherits from it.
For example:
CustomerPreference
↓
GenericItem
↓
ItemThis provides the underlying platform infrastructure required for the item.
Adding an Attribute
An attribute can be defined using:
<attribute qualifier="externalId"
type="java.lang.String">
<modifiers read="true"
write="true"
optional="true"/>
<persistence type="property"/>
</attribute>The important properties are:
qualifier
type
modifiers
persistenceAttribute Qualifier
The qualifier is the logical name of the attribute.
Example:
qualifier="externalId"The generated model will typically expose methods such as:
getExternalId()
setExternalId()You can then write:
CustomerPreferenceModel preference;
preference.setExternalId("EXT-10001");
String id = preference.getExternalId();Attribute Type
The type defines what kind of data the attribute holds.
Examples:
type="java.lang.String"type="java.lang.Integer"type="java.lang.Boolean"type="java.util.Date"You can also reference another SAP Commerce type.
For example:
type="Product"Mandatory Attribute
Consider:
<modifiers optional="false"/>This indicates that the attribute is mandatory.
Example:
<attribute qualifier="externalId"
type="java.lang.String">
<modifiers optional="false"/>
</attribute>The application should provide a value before saving the item when the platform's validation/persistence rules require it.
Optional Attribute
An optional attribute can be empty.
<modifiers optional="true"/>For example:
<attribute qualifier="description"
type="java.lang.String">
<modifiers optional="true"/>
</attribute>Read and Write Modifiers
You can control access using:
<modifiers read="true"
write="true"/>For example:
read="true"
write="false"means application code can read the attribute but should not normally write it through the generated model API.
Unique Attribute
You can define an attribute as unique.
<attribute qualifier="externalId"
type="java.lang.String">
<modifiers unique="true"/>
</attribute>This is useful when an external identifier must uniquely identify an item.
For example:
EXT-10001
EXT-10002
EXT-10003should not contain duplicates.
Important: unique="true" is a Type System constraint. It should not automatically be interpreted as equivalent to a database index in every situation.
Initial Attribute
The initial modifier is useful when an attribute should be set during item creation and should not normally be changed afterward through the generated setter.
Example:
<modifiers initial="true"/>This is useful for values that represent immutable creation-time information.
Persistence Type
A common configuration is:
<persistence type="property"/>This tells SAP Commerce how the attribute is persisted.
For most ordinary attributes, property persistence is commonly used.
Deployment
A custom item type may define a deployment configuration.
Example:
<deployment table="CustomerPreference"
typecode="12001"/>This specifies:
Table → CustomerPreference
Typecode → 12001The type code must be selected according to your project's SAP Commerce type-code strategy and must not conflict with another type.
Why Type Codes Matter
The type code is an important identifier within the SAP Commerce Type System.
Incorrect or duplicate type codes can cause problems during system update or initialization.
For custom development, organizations commonly reserve ranges of type codes for custom extensions.
Always follow the type-code conventions established by your project.
Extending Existing Types
Instead of creating a completely new item type, you can extend an existing type.
For example:
<itemtype code="CustomProduct"
extends="Product">
</itemtype>Conceptually:
Product
|
+---- code
+---- name
+---- catalogVersion
|
↓
CustomProduct
|
+---- customAttributeThis is useful when the existing platform type already represents the correct business concept.
Adding an Attribute to an Existing Type
You can also define additional attributes on an existing item type through an extension.
Example:
<itemtype code="Product"
autocreate="false"
generate="false">
<attributes>
<attribute qualifier="externalProductCode"
type="java.lang.String">
<modifiers optional="true"/>
<persistence type="property"/>
</attribute>
</attributes>
</itemtype>The important part is that the existing type is being extended rather than recreated.
What Does autocreate=false Mean?
When modifying an existing platform type, you may see:
autocreate="false"This indicates that the type itself is not being created as a new type by this declaration.
It is commonly used when extending an existing platform item definition.
What Does generate=false Mean?
You may also see:
generate="false"This prevents generation of a new model class for the type declaration.
This is useful when the item type already exists and you're only adding metadata such as an attribute.
Relations
Relations are another major part of items.xml.
Suppose we want:
Customer
|
| 1 : N
|
CustomerPreferenceWe can define a relation.
Example:
<relation code="CustomerToPreferenceRelation">
<sourceElement type="Customer"
qualifier="customer"
cardinality="one"/>
<targetElement type="CustomerPreference"
qualifier="preferences"
cardinality="many"/>
</relation>This establishes a relationship between the two item types.
Understanding sourceElement
The source side is:
<sourceElement type="Customer"
qualifier="customer"
cardinality="one"/>This says the relation starts from a Customer.
The qualifier determines how the relation can be accessed from that side.
Understanding targetElement
The target side is:
<targetElement type="CustomerPreference"
qualifier="preferences"
cardinality="many"/>This means a customer can have multiple preferences.
Conceptually:
Customer
|
+---- Preference 1
|
+---- Preference 2
|
+---- Preference 3Relation Cardinality
Common cardinalities are:
one
manyThese can be combined to model:
1 : 1
1 : N
N : 1
N : NMany-to-Many Example
Consider:
Product ↔ CategoryA product can belong to multiple categories and a category can contain multiple products.
Conceptually:
Product A ─── Category 1
└── Category 2
Product B ─── Category 1
└── Category 3SAP Commerce relations can represent this relationship.
Enum Types
items.xml can also define enumeration types.
Example:
<enumtype code="CustomerPreferenceType"
autocreate="true"
generate="true">
<value code="EMAIL"/>
<value code="SMS"/>
<value code="PUSH"/>
</enumtype>This creates an enumeration with values such as:
EMAIL
SMS
PUSHYou can then use it as an attribute type.
<attribute qualifier="preferenceType"
type="CustomerPreferenceType">
</attribute>Collection Types
SAP Commerce also supports collection types.
For example, a collection of strings can be defined using the appropriate collection type configuration.
Collections can be useful when a business concept naturally contains multiple values without requiring a separate persistent item relationship.
However, developers should carefully consider whether a relation or a collection is more appropriate for the use case.
Map Types
SAP Commerce also supports map types for key-value data.
For example:
language → valuecould conceptually be represented as:
en → "Hello"
de → "Hallo"
fr → "Bonjour"For structured business data, however, a dedicated item type or relation may sometimes be a better long-term design.
Generated Model
Once the Type System has been processed, SAP Commerce provides the corresponding model representation.
For example:
CustomerPreferencecan have:
CustomerPreferenceModelThen application code can use:
CustomerPreferenceModel preference =
modelService.create(CustomerPreferenceModel.class);
preference.setExternalId("EXT-10001");
modelService.save(preference);items.xml and FlexibleSearch
Once the item exists in the Type System, it can be queried through FlexibleSearch.
For example:
SELECT {pk}
FROM {CustomerPreference}
WHERE {externalId} = 'EXT-10001'This is one of the reasons understanding the relationship between items.xml, models, and persistence is important.
items.xml and Impex
Impex operates on the Type System defined by the platform.
For example, if we have:
<attribute qualifier="externalId"
type="java.lang.String">we can use the attribute in Impex:
INSERT_UPDATE CustomerPreference;
externalId[unique=true];
EXT-10001The Type System therefore forms the foundation for how data can be imported and manipulated through Impex.
items.xml Change Lifecycle
A typical development flow looks like:
Modify items.xml
↓
Build
↓
Generate/update platform metadata
↓
System Update
↓
Verify Type System
↓
Test ModelService / FlexibleSearch / ImpexThe exact commands and procedure depend on the SAP Commerce version and project setup.
Common items.xml Mistakes
Duplicate Type Code
Two custom types should not accidentally use the same type code.
Duplicate Attribute Qualifier
Avoid defining conflicting attributes on the same type hierarchy.
Wrong Parent Type
Always verify that the selected parent type actually represents the intended business concept.
Incorrect Relation Cardinality
A wrong cardinality can cause unexpected data-model behaviour.
Forgetting System Update
Changing items.xml does not mean the running platform automatically knows about the change.
The appropriate build and system update process is required.
Changing Existing Attributes Carelessly
Changing the type or persistence characteristics of an existing attribute can have significant implications for existing data.
Always assess migration and compatibility before making such changes.
Best Practices
Keep Item Definitions Simple
Use the Type System to model persistent business entities, not every object in your application.
Prefer Existing Types When Appropriate
Before creating a new item type, check whether an existing platform type can be extended.
Use Relations for Real Business Relationships
If two persistent business entities have a meaningful relationship, a relation is often preferable to storing IDs manually.
Follow Naming Conventions
Use meaningful type codes and qualifiers that clearly communicate their purpose.
Treat Type Changes Carefully
Changes to existing types can affect:
- Database persistence
- Existing data
- Impex
- FlexibleSearch
- OCC
- Backoffice
- Integrations
Always assess the impact before deploying.
Real-World Example
Suppose a business requirement says:
"Every B2B customer should have an external division number and division name."
A developer might model this using attributes:
<attribute qualifier="divisionNumber"
type="java.lang.String">
</attribute>
<attribute qualifier="divisionName"
type="java.lang.String">
</attribute>But before doing this, the developer should ask:
- Does the division already exist as an item type?
- Is the division shared by multiple B2B units?
- Should this be a relation instead?
- Is the division number unique?
- Does an external SAP system own this data?
If the division is a separate business entity, a relation may be a better design:
B2BUnit
|
| many-to-one
↓
DivisionThis illustrates why Type System design is more than simply adding fields.
Frequently Asked Interview Questions
What is items.xml in SAP Commerce?
items.xml is used to define Type System metadata such as item types, attributes, relations, enum types, and other data-model definitions.
What is the difference between itemtype and attribute?
An itemtype defines a business entity, while an attribute defines a property belonging to that entity.
What is the purpose of deployment?
Deployment configuration defines persistence-related information such as the table and type code for applicable item types.
What is the difference between extending an item type and creating a new item type?
Extending an item type reuses the existing type hierarchy and adds custom functionality, while creating a new item type introduces a new business entity.
What is the purpose of autocreate="false"?
It is commonly used when working with an already-existing platform type rather than creating a new type.
What is the purpose of generate="false"?
It prevents generation of a new model class for that declaration, which is commonly relevant when extending an existing type.
What is a relation in SAP Commerce?
A relation defines a persistent relationship between two item types and exposes the relationship through generated model APIs.
Does changing items.xml immediately change the database?
No. The change must go through the appropriate SAP Commerce build and Type System update process.
Conclusion
items.xml is one of the most important configuration files in SAP Commerce development.
A strong understanding of items.xml helps developers work confidently with:
- Item Types
- Attributes
- Model classes
- Relations
- FlexibleSearch
- Impex
- Backoffice
- Persistence
- Type System updates
The key takeaway is that items.xml is not simply an XML file containing fields. It is part of the foundation of the SAP Commerce Type System and therefore directly influences how business entities are represented throughout the platform.
Once you understand items.xml, many other SAP Commerce concepts become much easier to understand.
