Wednesday, August 12, 2026

SAP Commerce items.xml Explained with Practical Examples

Introduction

If you are working with SAP Commerce, one file you will encounter frequently is:

items.xml

Whether 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
    ↓
Database

Where is items.xml Located?

In a custom extension, it is commonly located under:

<extension>/resources/<extension>-items.xml

The exact filename can vary according to the extension's configuration.

For example:

customcore
 └── resources
      └── customcore-items.xml

Basic 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:

CustomerPreference

with the attribute:

preferenceName

Understanding 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
       ↓
      Item

This 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
persistence

Attribute 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-10003

should 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 → 12001

The 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
   |
   +---- customAttribute

This 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
    |
CustomerPreference

We 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 3

Relation Cardinality

Common cardinalities are:

one
many

These can be combined to model:

1 : 1
1 : N
N : 1
N : N

Many-to-Many Example

Consider:

Product ↔ Category

A 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 3

SAP 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
PUSH

You 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 → value

could 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:

CustomerPreference

can have:

CustomerPreferenceModel

Then 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-10001

The 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 / Impex

The 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
   ↓
Division

This 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.

Posted by at
Labels: , , , , , , , , , , , , ,

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)