Hybris Runtime Development Tools Update: Improved FlexibleSearch. New Impex, Media, Configuration tools


In one of my previous articles I announced my new project, hybris  Runtime Development tools. This post is about some important updates to the package. Hybris Runtime Development tools is a set of the web/command-line utilities for hybris developers to progress faster with the everyday tasks and troubleshooting. Each utility is available both as a command-line application and as an API interface. So you can combine these components freely with your own toolset, both web-based and standalone. commandlinetools The updates are marked with (NEW!)
  • hybrisFlexibleSearch (100% ready)
    • REST API and a console tool to FlexibleSearchService,
    • FlexibleSearch command-line interface,
    • Various output formats, such as TXT, TSV, CSV, XML,
    • Using pipes and filters (grep, awk, perl etc),
    • Cascade reference resolution (no more PK is in output),
    • Handy for testing and troubleshooting
    • NEW! Search by PK. No need to specify a type, just a PK.
    • NEW! FlexibleSearch built-in beautifier (reformatter) 
    • NEW! Supporting a registry of hybris types without unique fields for proper resolution (see below)
    • NEW! Mixing types in Select is available now
  • hybrisBeans (100% ready)
    • REST API and console tool with the common configuration,
    • Shows the information about the specific bean,
    • Changing bean values (!) on the fly.
  • hybrisMedia (100% ready) NEW!
    • NEW! REST API and console interface to Media resources
    • NEW! requesting information about the media item by code
    • NEW! saving/displaying the media item by code
    • NEW! uploading media files by media code
  • hybrisConfiguration (100% ready)  NEW!
    • NEW! all configuration parameters with values
    • NEW! changing configuration parameters (key/value)
    • NEW! syncronization configuration parameters in memory with configuration files
  • hybrisGroovy (0%)
    • executing groovy scripts
  • hybrisCronjob (0%)
    • REST API and console interface to Cronjobs
    • Starting / stopping cronjobs
    • Changing cronjob attributes
  • hybrisSession (0%)
    • REST API and console interface to sessions
    • Changing session attributes
  • hybrisUsers (0%)
    • REST API and console interface to the user and customer service
    • sets up a current user by login
    • change user-related runtime information
  • hybrisLog (0%)
    • log parsing operations
    • activating/deactivating debug mode for classes
    • hooks for flexible search requests and solr requests
  • hybrisSOLR (0%)
    • REST API and console interface to SOLR search and SOLR indexer
    • start/stop index
    • request for SOLR data
    • REST API and console tool with the common configuration
    • Execute groovy scripts easily
  • hybrisPWS (0%)
    • console interface to Platform Web Services
See details about the updates in forthcoming  publications.


Please refer to the previous post to see the basic capabilities. This utility is designed for perfoming FlexibleSearch requests from the command line. Major updates are the following:

Search by PK

If you have a PK of any object in hybris, you can see a detailed information about this object. It is not required now to know what type this object has.
$ ./hybrisFlexibleSearch.sh -pk 8796176187393
catalogVersion code
electronicsProductCatalog:Online 4135570

$ ./hybrisFlexibleSearch.sh -pk 8796093120544
For the API version of this feature a new URL parameter “pk” is introduced.

Flexible Search reformatter

2016-08-20_16h44_32 For the API version of this feature a new URL parameter “beautify” is introduced (boolean).

Registry of hybris types without unique fields

This feature is about the PK resolution. In hybris, the response from FlexibleSearch service contains java objects. However, for exporting data you need to convert these objects into text. For atomic types like String or Integer, the conversion is automatic. The hybris default Flexible Search viewer can’t resolve the references and you need to rewrite your queries. For example, this is what a typical response looks like in HAC: 2016-08-20_16h49_59.png All reference links, all collections and all maps are “encoded” (each in his or her own way). My flexible search console application accomplishes this task by cascade resolution. For the example above, my application in response to the flexible search request “select {pk}, {normal} from {Product}” will return the following:
$ ./hybrisFlexibleSearch.sh -q "Select {pk} from {Product}" -f "pk,normal" -mr 4
pk normal
8796167176193 (electronicsProductCatalog:Online:/300Wx300H/266899-5310.jpg)
8796167340033 (electronicsProductCatalog:Online:/300Wx300H/284533-9485.jpg)
8796167372801 (electronicsProductCatalog:Online:/300Wx300H/107701-5509.jpg)
normal is a collection of Media, so this is a reason why the value is in parentheses. In my example, there is only one item in the list. This item is of Media type. According to the configuration of the utility, Media has two keys, catalogVersion and code. The other utility, hybrisTypeSystem helps to see it easily:
$ ./hybrisTypeSystem.sh -t Media | grep UNIQ
catalogVersion CatalogVersion [UNIQ], [!]
code java.lang.String [UNIQ], [!]
Code is an atomic type. In the example above  /300Wx300H/266899-5310.jpg is a code of the item with pk=8796167176193. Why do we see three components rather than two? It is because the first component, CatalogVersion, is also a composed type and my utility performs an additional request to resolve it into Catalog and catalogVersion. Both catalog and catalogVersions are also composed types, and the system retrieves their unique codes. flexible What rules are used for the resolution? For the example above, how the system understands that Media should be resolved into CatalogVersion+Code? that CatalogVersion should be resolved into Catalog + Version? and that Catalog should be resolved into Id? The rules are simple:
  • If the type has unique fields, they are used for the resolution
  • If the type has no unique fields, manual rules are used.
However, there too many types that have no unique fields, namely 452 in hybris 6.1. There is a list of these types in the updated version of the application, types-without-uniq-fields.txt. The format of this file is simple:
Each line is a rule. The rule X:Y1,Y2,Y3 says that the type X should be resolved in the fields Y1,Y2,Y3. Most of the rules have only pk on the right side. I changed some of the frequently used types from this list to my convenient rules. The rule for PriceRow type:
If you try to see the price of the Product, the price will be resolved according to this rule:
$ ./hybrisFlexibleSearch.sh -q "select {pk} from {PriceRow}" -mr 1
currency price
JPY 3030.0

Mixing type in SELECTs and joins

In the first release of hybrisFlexibleSearch, there were any capabilities to request more than one object out from the request. The PK of this object is the first component of “select” query. For example, “select {pk} from {Product}” returns a set of objects of Product type. However, if you wanted to show prices along with the product, the previous version of hybrisFlexibleSearch wasn’t able to do so. I added this feature into the new version of hybrisFlexibleSearch. Now you are able to process requests like
     {pk}, {PriceRow}
(Instead of 
./hybrisFlexibleSearch.sh -q "select {pk} from {Product}" -f code,europe1Prices 
that have been available in the previous version) However, there is a issue with the type resolution from the attributes in the response. For example, for the flexible request above, {PriceRow} is hybris’ PriceRow type and hybris flexiblesearch engine is not capable to identify this type without any clues. In the new version of the utility there is an command line option named resultTypes (-r for short) that is designed to show the types of the resulting set. Compare the output with and without this option: Without resultTypes:
$ ./hybrisFlexibleSearch.sh -q "select {pk}, {PriceRow.pk} from {Product}, {PriceRow} where {PriceRow.ProductId}={Product.code}" -mr 5
catalogVersion code
electronicsProductCatalog:Online 266899 8796093088799
electronicsProductCatalog:Online 266899 8796093252639
electronicsProductCatalog:Online 65652 8796096201759
electronicsProductCatalog:Online 65652 8796096300063
electronicsProductCatalog:Online 284533 8796098200607
With resultTypes:
$ ./hybrisFlexibleSearch.sh -q "select {pk}, {PriceRow.pk} from {Product}, {PriceRow} where {PriceRow.ProductId}={Product.code}" -mr 5 -r Item,PriceRow
catalogVersion code
electronicsProductCatalog:Online 266899 USD:86.86
electronicsProductCatalog:Online 266899 JPY:7400.0
electronicsProductCatalog:Online 65652 USD:358.88
electronicsProductCatalog:Online 65652 JPY:30570.0
electronicsProductCatalog:Online 284533 USD:419.43
By default, the type of fields in the SELECT part is “String”. So resultTypes will help you to convert the PKs from this list into the human-readable form. For the API version of this feature a new URL parameter “resultTypes” is introduced.


Please refer to the previous post to see the basic capabilities. This utility is designed for requesting the information about the hybris types.


Supporting collection types

$ ./hybrisTypeSystem.sh -t CommentItemRelationcommentsColl
The Element of collection (type): Comment
Code: CommentItemRelationcommentsColl
Extension name: comments
Description: null
XML definition: <collectiontype code=CommentItemRelationcommentsColl elementtype="Comment autocreate="false generate="false/>

Search a item type by pk

Now also can find a type by PK (in the similar way as described above.
$ ./hybrisTypeSystem.sh -pk 8796176187393



Command-line interface

The command-line app is a console wrapper for API. See API for the details. Usage:
./hybrisImpex.sh -i file1.impex file2.impex
./hybrisImpex.sh -i folder/*
./hybrisImpex.sh -c <mediaCode>
For the last example you need to upload an Impex File to Media storage using the following command
./hybrisMedia -c <mediaCode> -i <impexFile> -mt ImpExMedia


parameter  Description Example
? help, available options. Only for the console version.
beautify (-b) Reformats the impex file. All other commands are ignored -b
legacy (-l) legacy mode on. Default value is false -l
maxThreads (-mt) Maximum number of threads. By default, 16 threads.  -mt 16
validationMode (-mode) Validaton mode (strict/relaxed). Default value is strict.  -mode=strict
codeExec (-ce) Enable code execution. By default it is disabled  -ce
mediaCode (-mc) the code of the media of ImpExMedia type to import. At first you need to upload the impex as a media object with this code  -mt 16


Reformatter (beautifier)

./hybrisImpex.sh  -b data/products-classifications_en.impex

Executing impexes

There are two options on how to execute impexes: to load the impex file directly to the hybris Runtime Development tool server and execute there or to upload it as a media (using tools or not) and execute the impex file by the reference to the media.


It is a new utility for uploading media to the system directly from the command line.


  • NEW! REST API and console interface to Media resources
  • NEW! uploading media files by media code


All medias (it is a long list)
./hybrisMedia.sh -am
All media formats (to use with -mt option)
./hybrisMedia.sh -amf
Uploading a file, creating an item of Media type in hybris:
./hybrisMedia.sh -c <mediaCode> -i <file name> -mt Media
Show information about the image with the specified Media code
./hybrisMedia.sh -c <mediaCode>
Download the media file with the specified Media code to the current directory
./hybrisMedia.sh -c <mediaCode> -d
Uploading an Impex file. It can be processed later with hybrisImpex utility
./hybrisMedia.sh -c <mediaCode> -i  <ImpexFilename> -mt ImpExMedia
Download and show the contents of the file (use for text files only!)
./hybrisMedia.sh -c <mediaCode> -d

Download and save the contents of the file
./hybrisMedia.sh -c <mediaCode> -d -t <localFile>


parameter  Description Example
? help, available options. Only for the console version.
-all-medias (-a) The plain list of all media items (code) -a
-all-media-formats(-amf) Displays all media formats -amf
mediaFormat (-mf) Specifies the media format  -mf 300Wx300H
download (-d) Download file from hybris  -d
tofile (-t) Save the downloaded file  -t file.jpg
mediaType (-mt) Media type of a newly created item. The following media types are available OOTB:  Media, BarcodeMedia. CatalogUnawareMedia, CatalogVersionSyncScheduleMedia, ConfigurationMedia, Document, EmailAttachment,Formatter, ImpExMedia, JasperMedia, LDIFMedia, LogFile, ScriptMedia  -mt ImpExMedia
download (-d) Download the media file with the specified m media code (should be used with -c ) -c mediacode_01 -d
code (-c) Code of the item to retrieve (-d /download/ or no other options for the info) or create (with -i)  -c


This utility is designed for runtime configuration management. Basically, all the capabilities are available also in HAC, the Configuration tab, except the sync feature.


You are able to see hybris logs in the tool’s output:
$ ./hybrisImpex.sh -i data/products.impex
[READING IMPEX] data/products.impex
INFO   | jvm 2    | main    | 2016/08/21 14:06:21.580 | INFO  [hybrisHTTP5] [DefaultImportService] Starting import synchronous using cronjob with code=00000G7D
INFO   | jvm 2    | main    | 2016/08/21 14:06:21.585 | INFO  [hybrisHTTP5] (00000G7D) [ImpExImportJob] Starting multi-threaded ImpEx cronjob "ImpEx-Import" (16 threads)
INFO   | jvm 2    | main    | 2016/08/21 14:06:21.621 | WARN  [ImpExReaderWorker] [ImpExReader] line 2 at main script: skipped code line line 2 at main script:impex.setLocale( Locale.GERMAN ) since bean shell is not enabled
INFO   | jvm 2    | main    | 2016/08/21 14:06:26.943 | INFO  [hybrisHTTP5] (00000G7D) [Importer] Finished 1 pass in 0d 00h:00m:05s:354ms - processed: 1954, no lines dumped (last pass 0)
INFO   | jvm 2    | main    | 2016/08/21 14:06:27.050 | INFO  [hybrisHTTP5] [DefaultImportService] Import was successful (using cronjob with code=00000G7D)


parameter  Description Example
? help, available options. Only for the console version.
extension (-e) Extension name -e trainingstorefront
name (-n) Name of the property to change -n sso.redirect.url
value (-v) New value of the property  -v “value value”
list (-l) All available configuration properties (not only for the specified extension)  -l
check (-c) Compares property files with the memory state  -c
sync (-s) Copy all new/update property values from files to memory  -c

Examples of usage

Setting/creating/changing a configuration property:
./hybrisConfiguration.sh -e hybristoolsclient -n test1 -v value1
Find a value of the specific property:
./hybrisConfiguration.sh -e hybristoolsclient -list | grep test1
Scan the property files and compare them with the information in memory:
./hybrisConfiguration.sh -e hybristoolsclient -check
Sync the property files with the memory (one-way sync, only memory information will be changed)
./hybrisConfiguration.sh -e hybristoolsclient -sync


For the reference, the part I of the demonstration:


The extension is available by request. E-mail: Rauf_Aliev@epam.com. Skype: rauf_aliev © Rauf Aliev, August 2016  

Leave a Reply