Attributes

A marketplace product attribute is anything that describes the product itself: colour, material, weight, dimensions, country of origin, energy class, and so on. Each marketplace category defines its own set of attributes — some are mandatory (the marketplace rejects products that don’t have them), most are optional.

The Attribute Mappings page is where you tell the plugin, for each operator attribute, which piece of data in Shopware should be sent. You can map an attribute to a native product field (like Name or Weight), to a custom field on the product, to a property group, to a fixed text, or to one of several built-in helpers. Each mapping can also have value rules that transform the data on the way out — for example trimming long text, converting commas to dots in numbers, or stripping HTML from a rich-text description.

Where to find it

Open the Mirakl admin module, then on the dashboard click the Attribute Mappings tile in the Quick Start section.

The list shows every operator attribute you have mapped, with these columns:

Product Attribute — the operator’s attribute (the thing you map into).
Mapping Type — kind of mapping at a glance.
Required (Mirakl / Export) — two flags, separated by a slash. First: whether the marketplace requires this attribute. Second: whether the plugin treats the attribute as mandatory at export time (see Required attributes below).
Source Type — what kind of Shopware data you are reading from (Product Field, Custom Field, Property Group, etc.).
Source Value — the specific field or value behind the source type.
Default Value — fallback used when the product has no value (see Default value below).
Connections — the connections this mapping applies to.

You can filter the list by Connection, Source Type and Product Attribute. The toolbar offers Refresh, Add Mapping, Auto Map, Export Mappings and Import Mappings.

The list of available operator attributes you can pick from comes from a refresh — open Product Attributes in Quick Start and use Refresh Attributes, or let the setup wizard pull it for you in step 3.

Auto Map — the recommended starting point

Click Auto Map in the toolbar. The plugin runs through the operator’s attribute list and creates mappings for everything it recognises by name or code. The matcher is conservative:

It only adds new mappings — anything you have already configured is left alone.
It only maps attributes whose name matches a known pattern. Attributes the matcher does not recognise are left for you to handle manually.

What the matcher recognises (a non-exhaustive list of common attribute names):

gtin, ean, product.ean → mapped to the product’s EAN field
short.item.description, product.name, product.title → Name
long.item.description, product.description → Description
net.mass.weight, product.weight → Weight
product.width, product.height, product.length → the matching dimension field
supplier.part.number, manufacturer.number, mpn → Manufacturer Number
sku, product.number → Product Number
category, product.category → the Product Category helper
product.image, image.url → Product Image URL
tax.rate, vat.rate → Tax Rate

After it finishes you will see a notification with the count of new mappings. Run Auto Map again any time you refresh the operator’s attribute list or want to fill in newly added attributes.

Adding a mapping manually

Click Add Mapping in the toolbar (or open an existing row and choose Edit from the context menu). The dialog asks for:

Product Attribute — pick the operator attribute you want to map.
Connections — which connection(s) this mapping applies to. One mapping can target several connections at once, but you cannot have two mappings for the same attribute on the same connection.
Source Type — what kind of Shopware data you want to read from. The dialog adjusts its fields based on your choice. Available source types include Product Field, Custom Field, Property Group, Product Category, Mirakl Category, Shopware Category, Product Image URL, Tax Rate, EAN with SKU fallback, Auto Product ID Type (EAN/SHOP_SKU), Shop SKU (Product Number), Product ID Type: SHOP_SKU, EAN / GTIN, Product ID Type: EAN, Effective Stock, Delivery Time, Mirakl Offer State and Static Value. The same list of source types is shared with Offer fields — that page describes what each one resolves to.
Source Value — depends on the source type: a product-field name, a custom-field key, a property-group reference, a static text, and so on.
Default Value — a fallback used when the product has no value (see below).
Required for export — a per-mapping safety check (see below).

Default value

Each mapping has a Default Value field with a small lock icon next to it:

Locked (no default) — when the product has no value, the plugin’s exporter falls back to its own logic. Use this when you would rather let the standard behaviour decide.
Unlocked (explicit default) — the value you type into the field is sent to the marketplace as-is when the product has no value of its own. An empty unlocked field sends an explicit blank — that is sometimes useful, for example to clear a previously set attribute.

Required attributes

The list shows two flags side by side under Required (Mirakl / Export):

Required by Mirakl — comes from the operator’s attribute definition. If Mirakl marks an attribute as required, missing values cause the operator to reject the product.
Required for export — a per-mapping safety check on your side. When this is on, products that have no value for this attribute are skipped during catalog export — they will not even be sent. Use this as a soft gate for fields you would rather skip on than fail on.

When you turn off Required for export on an attribute the marketplace itself requires, the dialog warns you that this may cause export errors or rejected products.

Value rules (transformations)

The data you store in Shopware rarely matches the marketplace’s expected format one-to-one. Each saved mapping can carry a chain of value rules (the editor is labelled Value transformations in the dialog) that adjust the value before it is sent.

To open the editor, save the mapping first, then re-open it via the row context menu → Edit and click Value transformations in the dialog footer. The button shows a count of existing rules.

If you click Value transformations while the mapping is still new (before the first save), nothing happens and an info notice appears: “Save the mapping first — transformations can only be added to a saved mapping.” Save first, then re-open to add rules.

Available rule types:

Type	What it does
Replacement	Plain find-and-replace. Match mode is either Substring (every occurrence) or Exact match (whole value).
Regular expression	A PCRE pattern in the form `/pattern/flags` plus a replacement template that can reference capture groups with `$0`, `$1`, `$2`. Allowed flags: `i`, `s`, `u`. Invalid patterns are rejected with a clear error.
Remove HTML	Strips every HTML tag.
HTML → plain text (formatted)	Converts HTML to formatted plain text.
Lowercase	Lowercases the value.
Uppercase	Uppercases the value.
Capitalize first letter	Capitalises only the first character.
Title Case (each word)	Capitalises every word.
Max length	Truncates to a maximum number of characters.

Rules run in Priority order — lower numbers run first. Example: a rule with priority 10 Remove HTML, followed by priority 20 Lowercase, followed by priority 30 Max length 200 turns a rich-text description into clean, lowercase text capped at 200 characters.

Import / Export

The Export Mappings and Import Mappings buttons let you carry an entire mapping configuration (including value rules) between connections or between shops:

Export Mappings opens a dialog where you pick a Source connection. The downloaded JSON file contains every attribute mapping linked to that connection. Attributes are referenced by their operator code, not by internal identifiers, so the file is portable between connections.
Import Mappings opens a dialog where you pick a Target connection, an Import mode (Merge — keep existing mappings, only add new ones, or Replace — remove existing mappings of the target connection first) and the JSON file to upload. The summary at the end reports how many mappings were Imported, Replaced, Skipped, and how many Missing attributes (referenced in the JSON but absent from the target connection’s attribute list).

The setup wizard’s Auto-Map step accepts the same JSON format, so an exported file can also be applied at first-time setup.

Tips & gotchas

Categories — each marketplace category has its own required-attribute set
Catalog export — uses attribute mappings at export time
Offer fields — the per-offer counterpart, sharing the same source types and value rules