A note from 2026: This article was published in 2016 and discusses the legacy Hybris Cockpit Framework. In current SAP Commerce Cloud versions, the “hybris” branding has been phased out, and Cockpit Framework / HMC / Product Cockpit have long been deprecated in favor of Backoffice and SmartEdit.

Hybris Cockpit Framework uses configuration files to customize UI components. According to the Hybris documentation, there are three levels of customization: easy, medium, and expert. This article is about “easy customization” via XML files. In this article, I focus on one aspect of cockpit UI configuration: cockpit UI configuration files from the folder

resource/-config/

Although the documentation for this part of Hybris is not bad, I took some notes that formed the core of this article.

The files in the mentioned directory follow this naming convention:

UserId is a directory, and _.xml is a template used for naming.

UserId

Any instance of the Principal object:

user id

user group Id

It is the easiest part and is well documented.

Contexts

The first part of the name is called “a context”. The documentation mentions four key contexts. Actually, there are more than three. This is the list of permitted contexts:

(source: global-cockpit-spring.xml)

listViewTaskContentBrowser. It is used only in
```
TaskMainAreaBrowserComponent
```
It seems that this context is deprecated and decommissioned.
advancedSearch. It is used in wizards, Reference Selector, and Browse item page.

The Advanced Search dialog box is displayed after clicking the “Browse” button in the cockpit content browser.
base. Base configuration. Each type may have a base configuration in which you specify the behavior for simple search and its labels.
contentEditor (cmscockpit)
contentElement (cmscockpit)
editorArea – editor area detail view configuration
liveEditPreviewArea (liveedit)
liveeditRestrictionEditorArea (liveedit)
listViewContentBrowserContext – referenced object result list view shown in the context area
gridView. Defines what attributes of the type are used for the thumbnail, title, and description to build a navigation grid.
gridViewPersonalize. Grid view in Personalization view.
listViewSelector. Reference selector dialog
listViewContentBrowser – search result list view configuration for the content area.
listViewEditorSection –
listViewBrowserSection. Browser section.
listContentElementSection. Component editor lists
listViewBtgMembership.
wizardConfig. Wizard configuration.

As you can see from the table above, each context is associated with a Factory that creates the actual configuration object from a JAXB object. Each Factory defines the allowed tags (see below).

Hybris uses

UIComponentConfiguration uiConfigService.getComponentConfiguration(
    objectTemplate,
    ,
    <*Configuration.class>
)

to fetch the configuration for the component. This call is injected into component implementations differently for different components. Later, these components refer to derivatives of UIComponentConfiguration to change the way the components are rendered.

Object template code

In most cases, the object template code is the name of the Hybris item type.

Examples:

“Product”
“CMSSite.AcceleratorWebsite”
“CMSSite.B2BAcceleratorWebsite”

The last two templates are predefined:

INSERT_UPDATE CockpitItemTemplate;code[unique=true];name[lang=de];name[lang=en];description[lang=de];description[lang=en];relatedType(code);
;"AcceleratorWebsite";"Accelerator Website";"Accelerator Website";"Accelerator Website";"Accelerator Website";CMSSite;
;"B2BAcceleratorWebsite";"B2B Accelerator Website";"B2B Accelerator Website";"B2B Accelerator Website";"B2B Accelerator Website";CMSSite;

This feature is underdocumented and barely used in the OOTB Hybris extensions. However, it looks very interesting. You can change the look of components based on the product the component operates on. The following screencast demonstrates how it works:

In the video, I open two products of the same type one after another, and you will see that some fields are not displayed.

Configuration file syntax

All configuration files are XML. They refer to XML XSDs that are also available in the same directory where the XML files are located.

All XML files have one of the following root elements (see the right column in the table below):

Hybris cockpit configuration root elements and factories

It would be overkill to list all syntax rules for all these tags here. You can use *.xsd files located in the same directory (resources/-config/). They contain all tags and attributes for all listed types of configuration.

Lookup chain

Once the component is requested — for example, for the type

Product

display an

advanced search component

— the configuration from XML is taken into account by the system to display the component according to the configuration.

However, you can have different versions of the configuration for different roles/users. There is logic behind the scenes that determines how these configurations are selected for a particular role and userId.

First, the system tries to apply the configuration specific to the currently logged-in user.

If that fails, the system tries to apply the role-specific configuration. For example, for all admins (admingroup). If it succeeds, the system skips the further steps. Otherwise, the system tries to identify and apply the configuration from the user group configured as the “fallback role”. Finally, Hybris tries to load configuration that is not connected to any roles or users.

Parameters

Wizard-config

allowCreate. The administrator will be able to create new items of the specified type (not only select existing items). Used with Reference Selector.
predefinedValuesStrategy. Fills predefined values for Item.
restrictToCreateTypes. Allows only specific types (subtypes) to be created.
excludeCreateTypes. Defines excluded types.
defaultValueResolver. Used to get a default value for a wizard property.
label_. Defines a label for an attribute for a wizard (for a row in a group).
allowSelect. Allows selecting rows. Used with Reference Selector. Marks a field as optional (true) or required (false) in the wizard.
allowActivate.
allowAutocompletion. Allows autocomplete in collection and reference editors.
optional. Marks a field as optional (true) or required (false) in the wizard.
autocompletionSearchType. The type used for autocompletion.
sclass. For shortListEditor. ZK style name.
autodrop. For shortListEditor.
constraint. For shortListEditor. For constraint=strict, you will need to enter a valid value in the field.
autocomplete. For shortListEditor.

ReferenceDualListBoxEditor

maxResults
searchTypeCode

WysiwygUIEditor

fckToolbarConfiguration. Defines toolbar icons. Uses the
```
default.fckToolbarConfig
```
parameter from
```
.properties
```
files if defined.
fckEmptyStringRegexp.
inline. The WYSIWYG editor is displayed inside the editor area.
rows. The number of rows of the editor in the editorArea.
languageIso.
editorWidth.
editorHeight.

Activating XML Configuration

The default way to activate the XML configuration is by performing an HAC Update.

If you need to apply only one specific configuration file, you can use the following IMPEX (edit the first lines to align with your task):

# configuration

$extension=testcockpits
$constantsfile=org.training.cockpits.constants.TestCockpitsConstants
$item=Product
$userorusergroup=cockpitgroup
$context=editorArea
$factory=editorConfigurationFactory

$configurationName=myConfigurationName
$jarResource=jar:$constantsfile&/$extension-config/$userorusergroup
$file=$context_$item.xml
$medianame=$userorusergroup_$item_$factory_$context
$translator=de.hybris.platform.impex.jalo.media.MediaDataTranslator

INSERT_UPDATE CockpitUIComponentConfiguration ; code[unique=true] ; factoryBean ; objectTemplateCode[unique=true] ; principal(uid)[unique=true] ; media(code) ;
 ; $configurationName ; $factory ; $item ; $userorusergroup ; $medianame ;

INSERT_UPDATE CockpitUIConfigurationMedia ; code[unique=true] ; mime ; realfilename ; @media[translator=$translator][forceWrite=true]
 ; $medianame ; text/xml ; $medianame ; $jarResource/$file