This section describes how the module maps categories to Shopware and what configuration options are available.


The following subsections are involved in mapping categories:

│   └───category-tree-shop
│   └───category-tree-transfer
│   └───category-tree-compare
    │   └───category-operations-move
    │   └───category-operations-add
    │   └───category-operations-delete
    │   └───category-operations-refresh-shop-tree
    │   └───category-operations-rebuild-shop-tree
    │   └───category-operations-sort-categories

Mapping categories is a complex process in the output module. There are two main subsections involved:

  • category-tree builds and compares the category trees from synQup and Shopware
  • category synchronizes the category trees and then upserts each category

You can find more information on what each subsection does below (see "How Categories are Mapped").


The following configuration is used for categories:

  "subsections": {
    "category": {
      "enabled": true,
      "deleteMode": "...",
      "defaultShopwareLayout": {
        "defaultLayoutShopwareId": "...",
        "overwriteShopwareLayoutId": true|false
      "rootCategoryShopwareId": "..."

Setting a Default Layout

You can set a default layout for your categories via configuration:

  • defaultLayoutShopwareId contains an uuid of a cms_page from Shopware. This is the layout to which each category will be assigned to during the initial import.
  • overwriteShopwareLayoutId determines whether a layout set manually in the administration will be replaced by the uuid from defaultLayoutShopwareId

Using a Custom Root Category

  • By default, the root-transfer-category will be imported as a "level 1 category" (= as one of the root categories of shopware)
  • The field rootCategoryShopwareId defines the id of a category, under which all transfer categories will be imported

Mapping Table

Target: category
Source: Elio\CommerceBundle\Document\Category\Category

Target Field Source Path
*T name label
active active
cmsPageId configuration
T description description
T metaTitle metaInformation.metaTitle
T metaDescription metaInformation.metaDescription
T keywords metaInformation.metaKeywords
parent_id parent

Background - How Categories are Mapped

The process of mapping categories to Shopware can be confusing at first sight. Therefore, it is broken down in detail here.

First thing to understand is that there are three steps necessary in order to map categories from synQup to Shopware:

  1. Category Tree: Build and compare the category trees from Shopware and synQup
  2. Synchronize Trees: Execute operations to synchronize the Shopware category tree with your transfer categories
  3. Category Upserts: Upsert each category document individually

The steps are explained in detail in the following sections.

Step 1: Build and Compare Category Trees

Before the module is able to upsert categories to Shopware is has to generate and compare the category trees from Shopware and synQup. This is handled by the following subsections:

  • category-tree-shop builds a tree from the categories in Shopware
  • category-tree-transfer builds a tree from the categories in synQup
  • category-tree-compare compares both category trees

In the subsection category-tree-compare the module derives operations to synchronize the existence of categories between synQup and Shopware. The generated operations are executed in the subsection category-operations eventually (see step 2).

Step 2: Synchronize Category Trees

The next step is to execute the operations to synchronize the category trees. The following subsections are involved:

  • category-operations-move moves a category to another parent within its tree
  • category-operations-refresh-shop-tree rebuilds the category tree as soon as all move-operations are done
  • category-operations-delete removes a category from Shopware
  • category-operations-add adds categories to Shopware
  • category-operations-rebuild-shop-tree rebuilds the category tree as soon as all add- and delete-operations are done
  • category-operations-sort-categories synchronizes the order of categories

The operations executed in step 2 are only responsible to synchronize the existence of categories between synQup and Shopware. An ADD-operation only creates a very simple category that does fully not represent its source document (Category) yet. This will be done in the next subsection: category.

At first glance, it seems unnecessarily complicated that categories might be sent to Shopware twice:

  • As a sync-operation in the subsection category-operations
  • As an upsert-request in the subsection category

The reason for this is that a category, that has been updated in synQup (e.g. by updating its name), is not necessarily sent as tree-operation (the structure of the trees is not affected by changing names). So an update of a name must be handled in the category subsection.

If the structure of the trees did not change this subsection does not do anything at all.

Step 3: Upsert Categories

In this step all category-data will be mapped from synQup to Shopware. This is done by the following subsections: