Introduction

This page explains the subsections that are generated dynamically by the mapping-extension. The mapping-extension generates a dynamic subsection tree based on your configuration. Basically it follows this pattern:

  • The mapping extension extends the ProgressDefinition based on the configured mappings.
  • It adds one parent subsection for each mapping.
  • The 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.
  • In addition, two subsections used to prepare the mapping of your documents are added by the mapping-extension

The following diagram shows which subsections the mapping-extension goes through:

Mapping Extension Subsections

Starting Point

There are two options available for the starting point of the mapping-extension:

  • Default: The mapping-extension starts as soon as the main module finished the progress-initialization
  • Custom: Configure a set of required subsections to be finished in requiredFinishedSubsections

Default

By default, the extension starts as soon as the main module finished initializing its progresses.

This can cause a problem if you reference documents that are mapped by the main module. If you do not set a custom starting point it can happen that your referenced documents have not been added to the shop yet, as soon as the mapping-extension starts to map your documents. So if you reference entities mapped by the main module you should use the custom mode.

Custom

You can configure a collection of subsection names (not paths) that needs to be finished before the mapping-extension starts to map your documents. This is done by setting the key requiredFinishedSubsections in the configuration. Example:

{
    "requiredFinishedSubsections": [
        "product",
        "customer"
    ]
}

You can find all valid entries in Synqup\Modules\Shopware6Bundle\Output\Standard\Progress\Subsections. Most likely you only need to be aware of the following keys / subsection names:

  • category
  • customer
  • product
  • propertyGroup
  • propertyGroupOption
  • order

By using these keys the mapping-extension does not map any document before the subsection {subsectionName} is done.

Initialize Progress Subsection

Basically the same principles as in the main module apply to the mapping-extension as well. So please refer to the documentation of the main module for more details.

This is a summary of the most important things to know:

  • Before the module starts to map documents to Shopware, the progress for each individual subsection is calculated.
  • The progress-initialization is used to check the progress of subsections that delete entities from Shopware for anomalies.
  • If the progress is abnormally high, the anomaly detection process is initiated (this is the same process as in the main module as well).
  • The calculated progress is not final for the -upsert subsections. If invalid documents are detected the progress count is reduced.

Sanity Checks Subsection

In the mapping-extension the sanity check does only check if the previous flow execution detected a delete-anomaly that must be confirmed via configuration. If an unconfirmed delete anomaly is detected the extension refuses to run. You can find more information about this process in the documentation of the main module.

Document Mapping Subsections

As already mentioned you have to configure each mapped document individually . The extension adds one parent subsection for each mapped document to the subsection tree that consists of the following subtree of subsections:

output  
└───document  
    └───document-[relations-extract]
    └───document-[relations-cache]
    └───document-entity-validate
    └───document-[-delta-count]
    └───document-[-anomaly-check]
    └───document-entity-upsert
    └───document-entity-delete

The sections shown in brackets are not necessarily executed. This depends on your configuration and factors explained below.

Relations Extract

This subsection is only generated if you configure the reference loading mode bulk . Basically it extracts and caches all referenced Shopware values. This is done to be able to perform a bulk search for all referenced Shopware entities.

Relations Cache

This subsection is only generated if you configure the reference loading mode bulk . This subsection uses the extracted values from the previous subsection (-relations-extract) to perform a bulk search for several referenced Shopware entities at once.

Delta Count

This subsection is part of the anomaly detection . In simple terms, it checks how many of the documents marked with a deletion flag will actually be removed from Shopware (in a full import, for example, it is possible that many documents have already been deleted in a previous flow execution. This means the actual delete-count is lower).

Anomaly Check

This is also part of the anomaly detection . The amount of documents to be deleted, calculated in the delta-count subsection, is analyzed for anomalies. If an unconfirmed anomaly is detected, the documents are prevented from being deleted.

Validate

Each document is validated to check if it can be transformed into a valid Shopware entity. If this is not the case the upsert progress is reduced, and you will be notified.

Upsert

Each document is transformed into a Shopware entity and then sent to the shop via Sync API.

Delete

Each document, if the corresponding Shopware entity (still) exists, is transformed into a delete request and deleted via Sync-API.