What is the Mapping-Extension?

The Mapping-Extension makes it possible to map custom documents to Shopware without having to develop a custom module. This is done by adding a simple json-configuration to the configuration of the main module.

In contrast to a "module extension", which extends already existing entities, the mapping extension is used to map additional entities.

This page explains general concepts of the mapping extension. There is a step-by-step guide to configure the mapping extension available as well.

Supported Features

The following features are mappable by the mapping extension:

  • Fields like strings, numbers and dates
  • Translations
  • One-to-many / many-to-one foreign key references to other Shopware entities

In addition, most concepts of the main module (e.g. delete-security, document validation, ...) are used in the extension as well.

Overview - How Does the Extension Work?

This section gives you a brief overview of how the mapping extension works in general. The steps to map a custom document to a custom Shopware table are basically the following:

  • Install the mapping extension (synqup/shopware-6-mapping-extension).
  • Add the mapping-extension configuration to the extensions section of the configuration of the main module
  • Add one to many "object mappings" to that configuration. Those object-mappings define how a custom document is mapped to a custom Shopware table by a simple json config.
  • Execute the flow of the main module. The module adds subsections to the subsection tree dynamically based on your configured object-mappings. These subsections will be used to map your documents to Shopware.
  • Several steps are performed automatically, e.g. validation, upserts, deletes, anomaly checks, ...

Configuration

In order for the mapping extension to be recognized and executed, it must be added to the configuration of the main module. Use Synqup\\Modules\\Shopware6MappingExtensionBundle\Subscriber\\Shopware6MappingExtensionBundleSubscriber as extension key. After that your documents are automatically transferred to Shopware. In general the configuration of the mapping-extension has the following structure:

{
    "shopwareApi": {},
    "locales": {},
    "identifier": {},
    "subsections": {},
    "extensions": {
        "Synqup\\Modules\\Shopware6MappingExtensionBundle\\Subscriber\\Shopware6MappingExtensionBundleSubscriber": {
            "primaryKeyMode": "...",
            "referenceLoadingMode": "...",
            "deleteAnomalyThresholdPercentage": ...,
            "requiredFinishedSubsections": [
                "..."
            ],
            "batchSizes": {
                "...": 0
            },
            "mappings": [
                {
                    "...": "..."
                }
            ]
        }
    }
}

The configuration has the following parts on its highest layer:

  • primaryKeyMode determines how documents are identified (see foreign key mapping)
  • referenceLoadingMode determines how referenced Shopware entities are fetched (foreign key mapping)
  • deleteAnomalyThresholdPercentage sets the delete-percentage upon which the delete-protection takes place (see document deletion)
  • requiredFinishedSubsections allows you to configure a set of subsections of the main module that needs to be done before the mapping-extension starts (see mapping-extension subsections)
  • batchSizes sets the batch sizes to use in each subsection (see batch sizes)
  • mappings describes how your documents are mapped to Shopware tables (see mapping-configuration)

The mapping extension extends the ProgressDefinition based on the configured mappings. It adds one parent subsection for each mapping. Those object-mappings / subsections are handled sequentially as they appear in the configuration. The mapping of an entity starts only after all objects of the previous entity have been transferred.

On this page