SAP Hybris Commerce is shipped with a text-based import and export functionality called ImpEx. The ImpEx engine allows creating, updating, removing and exporting platform items such as customer, product or order data to and from comma-separated value (CSV) data files, both during run time and during the initialization or update process.

ImpEx Syntax

An ImpEx file contains several different kinds of data.

Headers, refer to the Header section.

Lines of values


Macro definitions

BeanShell calls

Lines declaring user rights import


A header is a single line defining a mapping of the following value lines to the type system. A header applies to all processed value lines until the next header or until the end of file, whichever comes first. You can put any number of headers in one ImpEx file.

An ImpEx header line has the following structure:

mode type[modifier=value];attribute[modifier=value];attribute[modifier=value];attribute[modifier=value][;…];attribute[modifier=value]

Mode: Mode specifies what is to be done with the following value lines (insert, update, and so on)

Type: Type defines the type of item to be processed (category, product, media, type, and so on)

Attribute: Attribute describes which item attributes the columns are mapped to. The value lines supply the actual values for the items that are translated using the header settings

Modifier: Modifier gives additional information for translating a value record to the mapped type attribute

Example for a header row:

INSERT_UPDATE category;code[unique=true];name[lang=en];name[lang=en];$supercategories;$thumbnail;description[lang=en];order


  • This header states that each following value line creates or updates a category instance, until another header occurs.
  • The whole header syntax is case insensitive including the attribute qualifiers.

    Types of Modes:




Creates a new Item in SAP Hybris Commerce from the processed value line. By default, ImpEx does not check if an item with the same attributes already exists. Therefore, trying to insert an item with a code that already exists may throw an exception caused by the SAP Hybris Commerce core. For that reason, it is recommended to use the unique modifier, where ImpEx pre-checks a violation of attribute uniqueness.


Selects an existing item in SAP Hybris Commerce from the combination of the values of all columns marked with the unique modifier, which are referred to as key attributes, and sets the item attributes to the values specified in the value line.

If there is no item that matches the values of all key attributes, the value line cannot be resolved. The value line is dumped into a temporary file and the ImpEx extension tries to resolve the value line later on. Refer to ImpEx API document, section Import Using an Importer Instance for details.

Also note that the default value for attributes is null. This means that any attributes that are referenced by the header but for which no values are specified in the value line are not ignored, but are explicitly set to null. For example, the following ImpEx lines cause the ahertz customer to have the name attribute set to null as the second line after the header specifies no value for the name attribute.

UPDATE User;uid[unique=true];name;customerID;

;ahertz;Anja Hertz;;


To set values for both the name and the customerID attributes, you would need to use one of the three following approaches:

Specify all values in one single line:

UPDATE User;uid[unique=true];name;customerID;

;ahertz;Anja Hertz;K2006-C0005;

Re-specify all values that have been set in a prior line:

UPDATE User;uid[unique=true];name;customerID;

;ahertz;Anja Hertz;;

;ahertz;Anja Hertz;K2006-C0005;

Use individual headers:

UPDATE User;uid[unique=true];name;

;ahertz;Anja Hertz;

UPDATE User;uid[unique=true];custmerID;


UPDATE User;uid[unique=true];name;customerID;

;ahertz;Anja Hertz;;

;ahertz;Anja Hertz;K2006-C0005;

Use individual headers:


Combines the effects of the INSERT and UPDATE header modes: if an item with the values of all key attributes exists, this item is updated. If no item exists that matches the combination of all key attributes, the value line is used to create the item. The hybris ImpEx extension always uses this order: UPDATE, then INSERT.


As in UPDATE mode, the hybris ImpEx extension tries to find an existing item using the key attributes. If such an item exists, it is deleted, otherwise a log message of level warning is printed to the log.

Header Type

The type code selects the type from the SAP Hybris Commerce Type System where the following data rows create, update or remove instances.

Optionally, each line can specify a subtype of the type specified in the header at the first column. That subtype is selected for that single line only – in the next line, the type specified in the header is active again. The following code snippet references the User type in the header, but creates an instance of the Customer and Employee types each.

INSERT Job; code[unique=true]

Header Attributes

Each column followed by the header type at the header line describes an attribute of the header type where the column value of the following value lines are mapped to. The ImpEx extension checks the specified type and its attributes and uses a Translator to match the value line's entry to the individual attribute. 

INSERT Product;code;unit(code)

Value Line

Items are translated into a text representation called a value line completely driven by their business type definition. Generally, one item is represented by one value line - its attribute values by the columns of this row. 

For each value line, an item is created, updated, or removed depending on the mode set by the header. The basic structure of a value line is:



Comments start with the dash # and are ignored during import. Blank lines and lines without values, such as ones occasionally generated by Microsoft Excel like ;;;;;;;;, are also ignored.

INSERT_UPDATE Product;code[unique=true]; varianttype(code);name[lang=en]; 
# BASEPRODUCTS JEANS;;;;;;;;;;;;;;;

Definition Line – Macro

The ImpEx extension allows you to define macros so that you do not have to type repeating strings into your CSV files, and you can keep your CSV files more manageable. During import, these macros are parsed and any occurrence of the macro name is replaced by the macro value. You can call macros in headers and in value lines. You can even call macros within macro definitions. If you define two macros with the same key, the latest definition is used.

Macro definitions start with the dollar symbol $, and they are referenced by $macroname. For example:

INSERT Product; code; $catalogVersion

Wherever the term $catalogVersion appears, it is replaced by: catalogVersion(catalog(id),version)

INSERT Product; code; catalogVersion(catalog(id),version)

This is all about ImpEx.

Now we see how to Import via ImpEx Web

  • Open the Hybris Administration Console.

  • Go to the Console tab and select ImpEx Import option.

  • The ImpEx Import page displays.

You can perform import in two ways:

  • In the Import content section paste a script and click the Import content button.

  • In the Import script section choose a script from a different location and click the Import file button.

Hope this blog help you...

Thanks for Reading...

To report this post you need to login first.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.

Leave a Reply