Impex and its Execution Flow

Impex is a Hybris functionality that provides a way to import and export data to and from the Hybris Platform.

Impex provides Create, Update, and Delete of CRUD operations on the database columns. SAP Commerce has a separate a flexible Search query to read data of a type.

Impex is Hybris specific Language that later gets converted into SQL scripts.

Syntax

The Syntax of Impex consists of a two-part header and data.

# Header -> Represents The Hybris Type System with comma separated attributes
# Data -> Data Related to Hybris type

ExecutionMode itemType[modifier=value];attribute(columnName)[modifier=value]

# columnName is required only in case of composed Type        

if you want to know more about the hybris Type System click -> hybris Type System

example

INSERT Product;code[unique=true];unit(code)[default=pieces];manufacturerName
;2047052;;MB496T/A

# unit is a enumeration so name as code        

Execution Flow of Impex

1. Micros get replaced in the Impex header
2. Cell Decorator reads the cell value and applies the business logic on top
3. The translator translates the values from/to the hybris.
4. Scripting gets executed and returns the results.
5. Impex Statements get converted into SQL script (Insert, update delete) and DB gets reflected if commit mode is on.

let's understand this flow one after the other.

Micros get replaced in the Impex header

Micros are reusable statements that can be used multiple times in the Impex file.

# here catalogversion is the micro which can be used mutiple places in the 
#   impex file
$catalogversion=staged
UPDATE BundleTemplate;id[unique=true];$catalogversion        

The cell decorator reads the cell value and applies the business logic on top

Cell Decorator can be provided as the attribute modifier to run a business logic before we import the data in DB.

Example: In the above scenario...

The cell decorator will decide if Any Product is a Bulk product or not based on height and weight. Here isBulk is the attribute that will be calculated and filled with true or False.

$isBulk = isBulk[cellDecorator=com.batch.decorator.IsBulkProductDecorator]

UPDATE Product;code[unique=true];$isBulk
;2047052;height->20
        

Here we are importing the map value in the bulk header. how-to-import-maptype

The Implementation of decorator decides if the product is a bulk product or not.

public class IsBulkProductDecorator extends AbstractImpExCSVCellDecorator
{
	private final BulkCalculator bulkCalculator ;

	public IsBulkProductDecorator()
	{
      this.bulkProductDecorator = Registry.getApplicationContext().
                   getBean("bulkCalculator", BulkCalculator.class);
	}

	@Override
	public String decorate(final int i, final Map<String,Integer> map)
	{
		return Boolean.toString(bulkCalculator.isProductBulk(map));
	}

}        

The decorate method accepts the map of String[height] and Integer[20] which we can calculate with the BulkCalculator.

The translator translates the values from/to the hybris.

The translator is a converter between CSV files and the Hybris item attribute.

The translator can be provided as the attribute modifier to convert the items before saving them.

Example 1. FileLoaderValueTrnaslator

$jarCms=$jarResourceCms/structure-view

# Here the FileLoaderValueTranslator loads a File into a String property.

$velTemplate=velocityTemplate[translator=de.hybris.platform.commerceservices.impex.impl.FileLoaderValueTranslator]


UPDATE PageTemplate;uid[unique=true];$velTemplate
;ProductDetailsPageTemplate;$jarCms/structure_productDetails2PageTemplate.vm        

Example 2. MediaDataTranslator

$media = @media[translator= de.hybris.platform.impex.jalo.media.MediaDataTranslator][forceWrite=true]

INSERT_UPDATE Media;code[unique=true];mime;realfilename;$media
;;ContentPageModel__function_preview;text/gif;ContentPageModel__function_preview.gif;$jarResourceCms/preview-images/ContentPageModel__function_preview.gif]        

Scripting gets executed and returns the results.

Scripting(BeanShell, Groovy, Javascript) can be used with a header in the Impex statement to achieve dynamic behavior.

We don’t need to provide the scripting name when using BeanShell it's the default one.

The script can be inserted with the #% on the impex object. impex object has mupliple methods to support the execution.

Example. Setting german locale before executing german catalog-related Impex.

#% impex.setLocale( Locale.GERMAN );

$storeUid=apparel-de
$productCatalog=apparelProductCatalog
$productCatalogName=Apparel Product Catalog
$catalogVersion=catalogversion(catalog(id[default=$productCatalog]),version[default='Staged'])[unique=true,default=$productCatalog:Staged]
$storeImage=storeImage(qualifier, $catalogVersion)        

setting the execution mode. Also, Initialize parameters and fires an SQL against the database with includeSQLData.

#% impex.enableCodeExecution( true )
#% impex.setRelaxedMode( true );
INSERT_UPDATE Product; code[unique=true]; name
#% impex.includeSQLData("jdbc:mysql://localhost/projectDB?user=rajat&password=password", "com.mysql.jdbc.Driver", "Select code,name from Table");;        

For Exporting the B2BPermissionResult in file B2BPermissionResult.csv

"#% impex.setTargetFile( ""B2BPermissionResult.csv"" );"
insert B2BPermissionResult;&Item;B2BOrder(code);creationtime[forceWrite=false,dateformat=dd.MM.yyyy hh:mm:ss];owner(&Item);permission(code);status(code,itemtype(code))
"#% impex.exportItems( ""B2BPermissionResult"" , false );"        

we can write the groovy script for conditional,beforeEach and afterEach statements

INSERT_UPDATE Title;code[unique=true]
#%groovy% if: 5==5
;foo
#%groovy% if: 5==4
;bar        

Initialize the promotion module after the import.

UPDATE DroolsKIEModule;name[unique=true];defaultKIEBase(name)
"#% afterEach: de.hybris.platform.core.Registry.getApplicationContext().getBean(""ruleEngineSystemSetup"").initializeModule(impex.getLastImportedItem());"
;promotions-module;promotions-base        

Setting the Delivery Address from the User's default Address after the order creation.

INSERT_UPDATE Order;code[unique=true];user(uid);date[dateformat=dd.MM.yyyy HH:mm];currency(isocode);net;deliveryMode(code[default='premium-gross']);paymentMode(code);Discounts(code);calculated;site(uid);store(uid);status(code
;testOrder1;orderhistoryuser@test.com;17.04.2011 15:10;USD;false;;advance;;false;wsTest;wsTest;CREATED
"#%   impex.getLastImportedItem().setDeliveryAddress(impex.getLastImportedItem().getUser().getDefaultDeliveryAddress());impex.getLastImportedItem().setPaymentAddress(impex.getLastImportedItem().getUser().getDefaultPaymentAddress());";
"#%   impex.getLastImportedItem().calculate();";        

Impex Statements get converted into SQL script (Insert, update delete) and DB gets reflected if commit mode is on.

once these conversions are done, impex gets converted into a simple SQL Query to insert, update or Delete statements based on the Impex execution mode.

Impex Hacks

1. Insert/Update/Remove the Elements of a type in BatchMode and disable the associated Interceptor

Syntax:

Mode Item[batchmode=true,disable.interceptor.beans='beanName'];itemtype(code)[unique=true]

;ItemTypeName

Example:

REMOVE DroolsRule[batchmode=true,disable.interceptor.beans='ruleengineruleremoveinterceptor'];itemtype(code)[unique=true]
;DroolsRule        

Other Useful References:

• https://help.sap.com/viewer/d0224eca81e249cb821f2cdf45a82ace/1811/en-US/4ce7b82cbc574456ac197393f88e5cc6.html
• http://javainsimpleway.com/impex-cell-decorator/
• https://hybrismart.com/2016/10/30/mastering-hybris-impex-recipes-and-secrets/