Evaluating the ImpEx Syntax

Objective

After completing this lesson, you will be able to evaluate various options of ImpEx syntax to import data into the SAP Commerce Cloud database.

ImpEx - Basic Syntax

Now that you know what ImpEx is and when to use it, the next step is to look inside the script itself. An ImpEx file offers a rich set of syntax options - from simple business keys to macros, Document IDs, translators, and collection modes - and each one solves a specific data-import challenge. In this lesson, you will examine these syntax elements side by side so you can evaluate which construct best fits a given import requirement in SAP Commerce Cloud.

Anatomy of a Header and Data Row

Every ImpEx script is built from two lines: a header row and one or more data rows.

A header row starts with an operation, followed by an item type, and a semicolon-separated list of attributes. Attributes may include reference sub-attributes (in parentheses) and modifiers (in square brackets).

The four operations available are:

  • INSERT — creates a new entity.
  • UPDATE — modifies an existing entity.
  • INSERT_UPDATE — modifies an existing entity, or creates one if none exists.
  • REMOVE — deletes an entity.

Data rows always begin with a semicolon to skip the operation and item type columns and align with the header.

Code Snippet
12
INSERT_UPDATE Customer; customerID[unique=true]; groups(uid); ;FrankColumbo;customergroup;

In this example, the header row declares the operation (INSERT_UPDATE), the item type (Customer), and the attributes to populate. The data row below provides the corresponding values for one customer. We will look more closely at the [unique=true] modifier and the reference attribute groups(uid) next.

Key Attributes, Localization, and References

Take a look at the following ImpEx example, which imports a promotion into SAP Commerce Cloud:

Code Snippet
12
INSERT_UPDATE Promotion; code[unique=true]; name[lang=en]; name[lang=fr]; country(isocode) ;Maranello3; Antarctica Ferrari launch; Lancement Ferrari en Antartique; AQ

Even in this short snippet, three important syntax elements are at work: a business key, localized attributes, and a reference attribute. Understanding each one is essential to reading and writing ImpEx.

Business Key

The [unique=true] modifier on code defines a business key (also called a key attribute). ImpEx uses this key to locate the target item before applying the operation:

  • For UPDATE, a matching item must already exist.
  • For INSERT, no matching item may exist.
  • For INSERT_UPDATE (used above), ImpEx updates the item if it exists, or creates a new one if it does not.

If more than one attribute is marked as unique, ImpEx treats the combination as a composite key — you will see this pattern in the next section on catalog-aware items.

Localized Attribute

Attributes such as name can hold different values per language. The [lang=xx] qualifier specifies the target language, and multiple languages can appear side by side in the same data row. In the example above, the English name and the French name of the promotion are imported together in a single line.

Reference Attribute

The header field country(isocode) is a reference attribute. Instead of storing the country directly, ImpEx looks up the Country item whose isocode equals AQ and stores that item's primary key on the Promotion. This is how ImpEx links records across tables using human-readable business keys rather than internal database IDs.

Reference attributes can also be nested and combined into composite keys - a more advanced pattern you will explore in the next section, Working with Catalog-Aware Items.

Working with Catalog-Aware Items

Catalog-aware types (such as Product or its subtype Car) need a composite business key, because the same product code can exist across different catalog versions (Staged and Online in the below example).

Code Snippet
1234
$catalogVersion=catalogVersion(catalog(id),version)[unique=true] INSERT_UPDATE Car; code[unique=true]; name[lang=en]; unit(code); $catalogVersion ;DB5;Aston Martin DB5; pieces; Default:Staged ;ES1;Lotus Esprit S1; pieces; Default:Online

Points to evaluate here:

  • Macros (lines starting with $) are substituted verbatim and reduce repetition.
  • Composite key values use commas in the header, such as catalogVersion(catalog(id),version) with 2 keys, and colons in data rows, such as Default:Staged or Default:Online.
  • Nested references such as catalogVersion(catalog(id),version) let ImpEx traverse multiple tables to resolve the correct foreign key.

ImpEx – Beyond the Basics

Beyond the basics, ImpEx provides several syntax elements you should be able to recognize and choose between:

  • Macros — reusable aliases for frequently used statements.
  • Document IDs — short aliases that simplify cross-references between items with complex business keys.
  • Collections and Maps — use these types as attribute values.
  • Translators — custom import logic, for example to import media files or classification attributes.
  • Batch mode and date formats — apply an update to all matching items and control how date values are parsed.
  • Scripting (BeanShell, Groovy, JavaScript) — embed scripts with hooks such as beforeEach, afterEach, and getLastImportedItem().

Note

To learn more about the Scripting Support in ImpEx, check out the recording of the expert deep dive live session: Identifying Scripting Support in SAP Commerce Cloud in the SAP Commerce Cloud Additional Live Sessions Series: Where You Go Next After Learning the Technical Basics of SAP Commerce Cloud.

The sections that follow drill down into the ones you will use most often.

Using Macros and Default Values

Macros work in both header and data rows. Combined with default modifiers, they can dramatically shorten data rows.

Code Snippet
123456
$catVersion=catalogVersion(catalog(id[default=$prodCat]),version[default=$version])[unique=true] INSERT Category;code[unique=true];$catVersion ;cars; ;cars;myCatalog ;cars;myCatalog:$version ;cars;:Staged

When a data row omits a value, the default takes over. All four rows above produce the same result: a powerful way to keep large imports concise and consistent.

Document ID for Cross-References

Cross-referencing an item normally requires the full business key. With composite keys, however, this quickly becomes needlessly wordy:

Code Snippet
12
INSERT_UPDATE Employee; uid[unique=true]; car(code, $catalogVersion) ;FrankColumbo; DB5:Default:Staged

As shown, to reference a car item, all three keys (DB5:Default:Staged) must be specified. If items have more than three keys, the verbosity escalates even further.

Document IDs simplify this. Use "&" (as &CarRef shown below) to store a reference under a short alias as "db5", then reuse it later:

Code Snippet
12345
INSERT_UPDATE Car; code[unique=true]; name[lang=en]; $catalogVersion;&CarRef ;DB5;Aston Martin DB5; Default:Staged; db5 INSERT_UPDATE Employee; uid[unique=true]; car(&CarRef) ;FrankColumbo; db5

In large ImpEx files, Document IDs also improve performance: the processor caches each new PK in memory, eliminating a database lookup for every reference.

Importing Maps

Maps require delimiters for structure: entries are separated by semicolons (;) and key-value pairs by arrows (->) by default. However, note that semicolons also serve as ImpEx column separators. To avoid ambiguity, wrap map values in double quotes - such as the "preferences" map example below:

Code Snippet
12
UPDATE Employee;uid[unique=true];preferences ;FrankColumbo;"drink->whiskey;game->poker;colour->beige"

You can override the delimiters with modifiers: map-delimiter and key2value-delimiter:

Code Snippet
12
UPDATE Employee;uid[unique=true];relatives[map-delimiter=|][key2value-delimiter=>>] ;FrankColumbo;wife>>Mrs. Columbo|sister>>Rose|brother>>Fred

Importing Collections

Collections support three modes to evaluate based on intent:

  • replace (default) - overrides existing references.
  • append - adds to existing references.
  • remove - eliminates matching references.
Code Snippet
12
INSERT_UPDATE Employee;uid[unique=true];groups(uid)[mode=append] ;FrankColumbo;approvers,dummygroup,reviewers

Advanced Qualifiers: Translators, Batch Mode, and Date Formats

Translators apply custom interpretation to imported values. Prefix the attribute with @ and provide the fully qualified class name:

Code Snippet
12
INSERT_UPDATE Employee;uid[unique=true];@password[translator=de.hybris.….PasswordTranslator] ;FrankColumbo;aVeryStrongPassword

Common built-in translators include the PasswordTranslator (hashes passwords before persistence) , the MediaDataTranslator (imports binary media files) or the classification attribute translator (covered later).

Batch mode applies one operation to many items at once. The example below updates the approval status of all products to approved:

Code Snippet
12
UPDATE Product [batchmode=true];itemType(code)[unique=true];approvalStatus(code) ;Product;approved

Date formats are declared per attribute with [dateformat=...]:

Code Snippet
12
UPDATE Rental;rentalId[unique=true];startDate[dateformat="39;yyyy.MM.dd"];endDate[dateformat="MM/dd/yyyy"] ;101;2026.08.31;03/15/2027

Importing Classification Attributes

Classification attributes are not stored directly on the product table, so a translator is required.

SAP Commerce Cloud provides ClassificationAttributeTranslator, which needs the classification system and version. Macros keep the header readable:

Code Snippet
1234567
$sysName=ClassificationSystem $sysVer=1.0 $translator=de.hybris...ClassificationAttributeTranslator $clAttrModifiers=system=$sysName,version=$sysVer,translator=$translator UPDATE Car;code[unique=true];@ads[$clAttrModifiers];@terms[$clAttrModifiers] ;car01;Coca-Cola,Pennzoil;5y loan

ImpEx for Export

ImpEx is not only for import. A typical ImpEx export script specifies a target file, defines an ImpEx header that lists the attributes to export, and calls an exporter function using BeanShell:

Code Snippet
123
"#%beanshell% impex.setTargetFile( ""Product.csv"" );" INSERT_UPDATE Product;code[unique=true];description[lang=en];name[lang=fr] "#%beanshell% impex.exportItems(""Product"", false);"

While INSERT_UPDATE isn't strictly necessary for specifying which attributes to export, including it in the header maintains consistency and aids reusability, ensuring the exported file can be seamlessly re-imported into another SAP Commerce Cloud server.

In addition, in the example above, all products are exported while excluding subtype items (controlled by the second parameter set to false). For targeted exports, use a flexible search query instead:

Code Snippet
12
"#%beanshell% impex.exportItemsFlexibleSearch( ""select {pk} from {Product} where {code} like '%happy%'"");"

Summary

  • Header and data rows define every ImpEx script, with the operations INSERT, UPDATE, INSERT_UPDATE, and REMOVE controlling behavior.
  • Business keys, composite keys, and localized attributes determine how ImpEx locates and updates target items in the SAP Commerce Cloud database.
  • Macros, default values, and Document IDs streamline complex scripts and improve import performance.
  • Maps, collections, and advanced qualifiers (translators, batch mode, date formats) handle special data types and custom import logic.
  • Export scripts reuse ImpEx headers so exported data remains re-importable across environments.