Impex is an abbreviation for import- export in SAP Commerce Cloud. It is one of many important features offered by Commerce cloud.It helps in importing data into the commerce system and exporting it out of the system.
The execution of the impex can be seen at various avenues in a commerce system (most popular approaches as per my view in descending order mentioned below) :
- At runtime through HAC (Hybris Administrative Console).
- During System update / System initialization by importing the configured impexes
( which mainly resides in the initialData Extension of the project and help in building the
project/essential data). - Using the Backoffice Impex Import/Export Wizard.
- Creating an Import or Export Cronjob in Backoffice.
- Using the Import/Export API.
So lets start our journey of mastering Impexes by learning its basic syntax. We'll use the below sample impex throughout this article to understand the basic syntax:
$10k = 10000
# ImpEx for Importing Bands
INSERT_UPDATE Band;code[unique=true];name;albumSales;history
;A001;yRock;$10k;Occasional tribute rock band
;A006;yBand;$10k;Dutch tribute rock band formed in 2013 playing classic rock
;A007;yBand;300000;Dutch tribute rock band formed in 2013 playing classic rock
1. Impex Header
INSERT_UPDATE Band;code[unique=true];name;albumSales;history <--- HEADER LINE
;A001;yRock;$10k;Occasional tribute rock band
So first line of any impex is known as its headers which contains the following subcomponent :
- Instruction or Mode (How to import) i.e. INSERT , INSERT_UPDATE etc.
- Item Type (where or in which data model instruction will be executed) i.e. Band,User,Product etc.
- Attribute (what all attributes of the item type will be affected ) i.e. code , name , albumSales
All the header subcomponents are separated by ; semicolon The whole header syntax is case insensitive including the attribute qualifiers.
In addition there are certain modifiers that can be used on type and attribute to add some more meaning to the import.
Lets talk about all the subcomponent briefly :
Header Mode:
There are 4 Impex modes :
INSERT :
Creates a new Item in SAP Commerce from the processed value line. No check if item with same attributes already exists, therefore, trying to insert an item with a primary Key that already exists will throw an exception .
UPDATE :
Self explanatory it updates an existing item by selecting it from the unique attribute data given in the value line.
INSERT_UPDATE :
Merge INSERT and UPDATE header modes: if an item with the key attributes is existing it will be updated otherewise a new item will be created.
REMOVE :
Find an existing item using the key attributes. If it exists, it is deleted, otherwise a message of level warning is logged in the system.
Header Type :
The Header type defines an item type from Type System where the value line's data will be created, updated or removed .
There is also an option in each line to 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.
Example :
As we can see the User type in the header, but in each value line we are again defining a new type i.e. Customer & Employees which are subtype of User. This gives the flexibility to declare abstract type in header and add concrete item type in each value line.
INSERT User;uid[unique=true]
Customer;SampleCustomer
Employee;SampleEmployee
Header Attributes & Modifiers:
Column/Text followed by the header type in the Impex header describes an attribute of the header type where the data value of the subsequent value lines are mapped .
While Importing , commerce system checks the specified type and its attributes and uses a Translator to match the value line's entry to the individual attribute.
It is easy to set an attribute value for attributes that are specified as AtomicTypes (such as java.lang.String or java.lang.Integer).
Modifiers are defined on an attribute or header type to give additional metadata about the attribute or header type while importing i.e. unique = true (For making the attribute a key attribute), batchmode=true (For importing/updating the same value in bulk)
Example :
INSERT Customer; uid [unique = true]
;myUser
Here the uid is an attribute of itemtype Customer or in otherwords uid is a column in the table customer.
Its type java.lang.String, so additonal definitions are not required. Just define the attribute at the header line and write a value line with the plain text of the desired user ID.
2. Value Line
INSERT_UPDATE Band;code[unique=true];name;albumSales;history
;A001;yRock;$10k;Occasional tribute rock band <--- VALUE LINE
Each Value line represent the data of one object/instance of the type mentioned in the header.
And as per the instruction provided in the header the value line or data is created/updated/deleted on an object in commerce system.
This data will go into the specific column as mentioned in the header e.g. code -> A001 , name -> yRock.
Data is separated by ; semicolon.
3. Macros
ImpEx allows to define macros so that we do not have to type repeating strings in our impex.
Macro definitions start with the dollar symbol ($), and they are referenced by $anyText
During import, these macros are parsed and any occurrence of the macro name is replaced by the macro value.
They can be called either in headers or in value lines.
We can even call macros within other macro definitions. If we define two macros with the same key, the latest definition is used.
Example :
Here we have $10k defined as macro and used in multiple value lines in the impex.
$10k = 10000 <--- MACROS
# ImpEx for Importing Bands
INSERT_UPDATE Band;code[unique=true];name;albumSales;history
;A001;yRock;$10k;Occasional tribute rock band
;A006;yBand;$10k;Dutch tribute rock band formed in 2013 playing classic rock
This is all about basic syntax of an impex. I hope you learned something useful.
Please do post your feedbacks and queries in comment section.