SAP COMMERCE IMPEX QUICK REFERENCE
===================================

DIRECTIVES
  INSERT           Creates new items only — fails if item already exists
  UPDATE           Updates existing items only — fails if item not found
  INSERT_UPDATE    Creates or updates — use this for most imports
  REMOVE           Removes matching items

MACRO SYNTAX
  $macroName=value           Define a macro
  $macroName                 Reference a macro in a header or data row

HEADER SYNTAX
  Type;column1;column2       Basic header
  Type;column[unique=true]   Mark as unique key (required for dedup)
  Type;name[lang=en]         Localized attribute
  Type;ref(refType.attr)     Reference to another type by attribute

COLUMN MODIFIERS
  [unique=true]              Key column for INSERT_UPDATE dedup
  [lang=en]                  Localized value language
  [dateformat=dd.MM.yyyy]    Parse a date string
  [default=value]            Default if cell is empty
  [virtual=true]             Skip persisting this column
  [mode=append]              Append to collection instead of replace

COLLECTION REFERENCES
  ref(Type.attr)[unique=true,default=...]   Reference with default catalog version
  multi-value separator: typically a pipe or comma — check your config

SPECIAL LINES
  #%                         Scripting mode (Groovy)
  # comment                  Comment line — ignored
  $START_USERRIGHTS;...      Start user rights block
  $END_USERRIGHTS;...        End user rights block

CATALOG VERSION MACRO (standard pattern)
  $productCatalog=myCatalog
  $catalogVersion=catalogVersion(catalog(id[default=$productCatalog]),version[default='Staged'])[unique=true,default=$productCatalog:Staged]

COMMON PITFALLS
  1. Forgetting $catalogVersion macro → catalog-aware types won't resolve
  2. Using INSERT instead of INSERT_UPDATE → duplicates on re-import
  3. Column count mismatch → row is silently skipped in some versions
  4. Enum fields: cannot filter with direct equality in FlexibleSearch
  5. Promotions: must compile + publish via Groovy after import
  6. Date format: use dd.MM.yyyy HH:mm:ss — not ISO 8601
  7. Missing [unique=true] → HAC creates duplicate items instead of updating
  8. Encoding: UTF-8 BOM can cause parse errors — save without BOM

IMPORT MODES
  Default (strict)    Fails on first error
  Relaxed             #% impex.setValidationMode("import_relaxed");
  No rollback by default — use HAC Import > checkbox for rollback

HAC IMPORT PATH
  HAC → Console → ImpEx Import → paste or upload → Execute Import
  Check: "Enable code execution" for scripting lines (#% ...)
  Check: "Legacy mode" if using older syntax