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.
12INSERT_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:
12INSERT_UPDATE Promotion; code[unique=true]; name[lang=en]; name[lang=fr]; country(isocode)
;Maranello3; Antarctica Ferrari launch; Lancement Ferrari en Antartique; AQEven 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).
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:OnlinePoints 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.