Introduction

This page explains how you can configure documents to be mapped to Shopware in general. There is also a step-by-step guide available that contains a lot of in-depth examples.

The configuration of how to map a custom document to a custom Shopware table is called ObjectMapping / object-mapping. It consists of two parts:

An object configuration defines how the document is mapped to a Shopware table (see "Object Mappings")
A field configuration that defines how the fields of that document are mapped to the columns of its target table (see "Field Mappings")

Object Mappings

In order to map a document to Shopware you have to add an "object-mapping" to the mappings field of the configuration. It basically looks like this:

{
    "mappings": [
        {
            "sourceDocumentFqcn": "Namespace\\Of\\The\\Source\\Document\\DocumentName",
            "targetTableName": "name_of_the_target_table",
            "primaryKeyMode": "id || identifier",
            "referenceLoadingMode": "bulk || on demand",
            "fields": [
                "{see below}"
            ]
        }
    ]
}

sourceDocumentFqcn: FQCN of the BaseDocument that contains the source data.
targetTableName: Name of the target table in Shopware (in snake_case).
primaryKeyMode: Determines whether documents are identified by their ObjectIds or identifiers. Optional field with default value identifier. Please refer to the identifier documentation for details.
referenceLodaingMode: Determines whether referenced entities are loaded on demand or cached before the mapping process. Optional field with default value bulk. Please refer to the foreign key documentation for more details.
fields: Configures the individual fields of an entity

Field Mappings

The field mappings.fields configures how each field of a document will be mapped to its corresponding Shopware field. Basically, an individual field configuration has the following structure:

{
    "sourcePath": "path.to.source.value",
    "targetFieldName": "name_of_target_field",
    "{fieldTypeConfig}": {
        "allowsNullValues": false
    }
}

sourcePath is a required field that contains the path to the source value of the BaseDocument that should be mapped to the target field. You can simply concatenate the fields to the target value with dot notation. Example: The path to the string representation of a customers' salutation would look like this: customerInformation.personalInformation.salutation.salutation.

targetField is a required field that contains the name of the column in the target table to which the source value will be written to.

In the example above {fieldTypeConfig} is a placeholder for the actual field configuration. This placeholder must be replaced by one of the following values, depending on the type of the target field:

stringFieldConfig to map text fields (= map a value from your document to a text field in Shopware)
numericFieldConfig to map number fields
foreignKeyFieldConfig to map references to other Shopware entities
booleanFieldConfig to map boolean values
dateTimeFieldConfig to map date and/or time values

{fieldTypeConfig}}.allowsNullValues is the only configuration that applies to all field types. It determines whether the target
field accepts the value null. This is an optional field with a default value of false.

You can find examples for every field type in the following section.

Text Fields

A field is marked as a text field by using the field configuration stringFieldConfig. Example:

{
    "sourcePath": "...",
    "targetFieldName": "...",
    "stringFieldConfig": {
        "isTranslated": false,
        "allowsNullValues": true,
        "maxLength": 255,
        "allowsHtml": false
    }
}

isTranslated marks a field as translated (optional, default false). See "Translated Fields" for details.
maxLength is the maximum length that the target field accepts. No length check will be performed if this value is not specified.
allowsHtml specifies whether Shopware accepts HTML in the target field (optional, default false). Attention: Values like "<19" are already interpreted as HTML and will cause API requests to fail.

Numeric Fields

A field is marked as a numeric field by using the field configuration numericFieldConfig. There is no distinction made between different number types (integer, float, ...). Example:

 {
    "sourcePath": "...",
    "targetFieldName": "...",
    "numericFieldConfig": {
        "allowsNullValues": true,
        "isTranslated": false,
        "allowNegativeValues": false,
        "roundingMode": "...",
        "roundingPrecision": 2
    }
}

isTranslated marks a field as translated (optional, default false).
allowNegativeValues specifies whether negative numbers are accepted (optional, default true).
roundingMode defines if and how numbers are rounded. Allowed values are: ceil, floor, round.
roundingPrecision applies only to the roundingMode round. Specifies the number of decimal places to which a number is rounded.

Boolean Fields

A field is marked as a boolean field by using the field configuration booleanFieldConfig. Example:

{
    "sourcePath": "...",
    "targetFieldName": "...",
    "booleanFieldConfig": {
        "allowsNullValues": true,
        "isTranslated": false
    }
}

Date Fields

To map a date use the key dateTimeFieldConfig. Example:

{
    "sourcePath": "...",
    "targetFieldName": "...",
    "dateTimeFieldConfig": {
        "allowsNullValues": true,
        "isTranslated": false
    }
}

Translated Fields

It is very easy to map translated fields with the mapping-extension. Actually there are only two things to do:

Add a field of type TranslationCollection to your document
Set the field configuration isTranslated to true

The translated values from your field will be mapped to the corresponding _translation table of your entity automatically.

Note that the mapping-extension uses the locale-configuration from the main module configuration to map your locales.

Configuration

{
    "sourcePath": "translatedField",
    "targetFieldName": "...",
    "{{fieldTypeConfig}}": {
        "isTranslated": true
    }
}

Requirements

Although it is very easy to map translations, there have been some problems in the past. They were mainly caused by incompatibilities between the mapping-extension and the plugin tables to be filled. That's why this section gives you an overview of the requirements that your tables must fulfill in order to be able to map translations with the mapping-extension.

Translations are supported, provided that the target tables correspond to the schema used by Shopware for "translation tables". If you follow the guidelines for translated entity definitions in Shopware you should be fine. But since this is crucial for translations to work the essential requirements are summarized here for you. For that we take a look at the following example:

CREATE TABLE `my_example_table`
(
    `id` BINARY(16) NOT NULL,
    PRIMARY KEY (`id`)
);

CREATE TABLE `my_example_table_translation`
(
    `my_example_table_id` BINARY(16) NOT NULL,
    `language_id`         BINARY(16) NOT NULL,
    PRIMARY KEY (`my_example_table_id`, `language_id`),
    CONSTRAINT `...` FOREIGN KEY (`language_id`) REFERENCES `language` (`id`) ON ...,
    CONSTRAINT `...` FOREIGN KEY (`my_example_table_id`) REFERENCES `my_example_table` (`id`) ON ...
);

You have to follow the patterns visible in this table structure:

The translation table must be named like the main entity with an appended _translation. So my_example_table must be named my_example_table_translation.
The reference to the main entity (the non-translated table) must follow the pattern entity_name_id. In this case my_example_table_id
The primary key of the translation table is a combination of the language id and the foreign key to the main entity.
Make sure that your property names are camel case representations of the storage names.

Foreign Key Fields

This is just a quick reference on how to map foreign key fields with the mapping-extension. Due to its complexity there is a dedicated documentation that explains how to map foreign keys in detail.

To configure a foreign key, use the field configuration foreignKeyField:

{
    "foreignKeyFieldConfig": {
        "sourcePath": "...",
        "targetFieldName": "...",
        "allowsNullValues": ...,
        "references": {
            "table": "referenced_table_name",
            "field": "referenced_column_name"
        }
    }
}

On this page

#Introduction

#Object Mappings

#Field Mappings

#Text Fields

#Numeric Fields

#Boolean Fields

#Date Fields

#Translated Fields

#Configuration

#Requirements

#Foreign Key Fields