Atrybuty

Atrybut produktu w marketplace to wszystko, co opisuje sam produkt: kolor, materiał, wagę, wymiary, kraj pochodzenia, klasę energetyczną i tak dalej. Każda kategoria marketplace’u definiuje własny zestaw atrybutów — niektóre są obowiązkowe (marketplace odrzuca produkty bez nich), większość jest opcjonalna.

Strona Attribute Mappings to miejsce, w którym dla każdego atrybutu operatora wskazujesz pluginowi, którą daną z Shopware wysłać. Możesz powiązać atrybut z natywnym polem produktu (np. Nazwa albo Waga), z polem własnym, z grupą cech, ze stałym tekstem albo z jednym z gotowych pomocników. Każde powiązanie może mieć też reguły wartości, które przekształcają dane w drodze do marketplace’u — na przykład skracają długi tekst, zamieniają przecinek na kropkę w liczbach albo usuwają HTML z opisu sformatowanego.

Gdzie to znaleźć

Otwórz moduł admina Mirakl, a na pulpicie kliknij kafelek Attribute Mappings w sekcji Quick Start.

Lista pokazuje wszystkie powiązane atrybuty operatora z kolumnami:

Product Attribute — atrybut operatora (cel powiązania).
Mapping Type — typ powiązania w skrócie.
Required (Mirakl / Export) — dwie flagi rozdzielone ukośnikiem. Pierwsza: czy marketplace wymaga tego atrybutu. Druga: czy plugin traktuje atrybut jako obowiązkowy w momencie eksportu (patrz Atrybuty wymagane poniżej).
Source Type — jakiego rodzaju daną z Shopware czytasz (Product Field, Custom Field, Property Group itd.).
Source Value — konkretne pole lub wartość kryjąca się pod typem źródła.
Default Value — wartość zapasowa stosowana, gdy produkt nie ma żadnej wartości (patrz Wartość domyślna niżej).
Connections — połączenia, których dotyczy powiązanie.

Listę możesz filtrować po Connection, Source Type i Product Attribute. Pasek narzędzi udostępnia Refresh, Add Mapping, Auto Map, Export Mappings i Import Mappings.

Lista dostępnych atrybutów operatora, z których wybierasz, pochodzi z odświeżenia — wejdź w Product Attributes w sekcji Quick Start i użyj Refresh Attributes, albo pozwól kreatorowi pierwszego uruchomienia pobrać je w kroku 3.

Auto Map — rekomendowany punkt startu

Kliknij Auto Map w pasku narzędzi. Plugin przejdzie listę atrybutów operatora i utworzy powiązania dla wszystkiego, co rozpozna po nazwie albo kodzie. Dopasowanie jest ostrożne:

Dodaje tylko nowe powiązania — wszystko, co już skonfigurowałeś, pozostaje nietknięte.
Powiązuje tylko te atrybuty, których nazwa pasuje do znanego wzorca. Atrybuty, których dopasowanie nie rozpoznaje, zostają do ręcznej obsługi.

Co dopasowanie rozpoznaje (lista najczęstszych nazw, niewyczerpująca):

gtin, ean, product.ean → pole EAN produktu
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 → odpowiedni wymiar
supplier.part.number, manufacturer.number, mpn → Manufacturer Number
sku, product.number → Product Number
category, product.category → pomocnik Product Category
product.image, image.url → Product Image URL
tax.rate, vat.rate → Tax Rate

Po zakończeniu zobaczysz powiadomienie z liczbą nowych powiązań. Auto Map możesz uruchamiać ponownie po każdym odświeżeniu listy atrybutów albo gdy chcesz uzupełnić nowo dodane pozycje.

Ręczne dodawanie powiązania

Kliknij Add Mapping w pasku narzędzi (albo otwórz istniejący wiersz i wybierz Edit z menu kontekstowego). W oknie wskazujesz:

Product Attribute — atrybut operatora, który chcesz powiązać.
Connections — które połączenie (lub połączenia) obejmuje to powiązanie. Jedno powiązanie może dotyczyć kilku połączeń naraz, ale nie da się utworzyć dwóch powiązań dla tego samego atrybutu na tym samym połączeniu.
Source Type — jakiego rodzaju daną z Shopware chcesz czytać. Pola w oknie dostosowują się do wyboru. Dostępne typy źródła to 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 oraz Static Value. Ta sama lista typów źródła używana jest dla Offer fields — tam znajdziesz opis, co dokładnie zwraca każdy typ.
Source Value — zależnie od typu źródła: nazwa pola produktu, klucz pola własnego, referencja do grupy cech, stały tekst itp.
Default Value — wartość zapasowa (patrz niżej).
Required for export — przełącznik bezpieczeństwa na poziomie powiązania (patrz niżej).

Wartość domyślna

Każde powiązanie ma pole Default Value z małą kłódką:

Zablokowane (brak wartości domyślnej) — gdy produkt nie ma wartości, eksporter pluginu korzysta z własnej logiki zapasowej. Wybierz tę opcję, gdy wolisz zostawić decyzję standardowemu zachowaniu.
Odblokowane (jawna wartość domyślna) — wpisany tekst jest wysyłany do marketplace’u tak jak jest, gdy produkt nie ma własnej wartości. Puste pole w trybie odblokowanym wysyła jawną wartość pustą — bywa to przydatne, na przykład żeby wyczyścić wcześniej ustawiony atrybut.

Atrybuty wymagane

Lista pokazuje dwie flagi obok siebie pod nagłówkiem Required (Mirakl / Export):

Wymagane przez Mirakl — pochodzi z definicji atrybutu u operatora. Jeśli Mirakl oznacza atrybut jako wymagany, brakujące wartości skutkują odrzuceniem produktu przez operatora.
Required for export — przełącznik bezpieczeństwa na poziomie powiązania, po Twojej stronie. Gdy jest włączony, produkty bez wartości tego atrybutu są pomijane przy eksporcie katalogu — nie zostaną w ogóle wysłane. Użyj go jako miękkiej bramki dla pól, dla których wolisz pominąć produkt niż dostać błąd.

Gdy wyłączysz Required for export przy atrybucie wymaganym przez sam marketplace, okno wyświetli ostrzeżenie, że może to spowodować błędy eksportu lub odrzucenie produktów.

Reguły wartości (transformacje)

Dane przechowywane w Shopware rzadko pasują formatem jeden do jednego do tego, czego oczekuje marketplace. Każde zapisane powiązanie może mieć łańcuch reguł wartości (w oknie edytora nazywanych Value transformations), które dopasowują wartość przed wysłaniem.

Aby otworzyć edytor, najpierw zapisz powiązanie, a następnie otwórz je ponownie z menu kontekstowego → Edit i kliknij Value transformations w stopce okna. Przycisk pokazuje licznik istniejących reguł.

Jeśli klikniesz Value transformations w nowym, jeszcze niezapisanym powiązaniu, nic się nie wydarzy, a pojawi się powiadomienie: “Save the mapping first — transformations can only be added to a saved mapping.” Najpierw zapisz, dopiero potem otwórz ponownie i dodaj reguły.

Dostępne typy reguł:

Typ	Co robi
Replacement	Zwykłe znajdź-i-zamień. Tryb dopasowania to Substring (każde wystąpienie) albo Exact match (cała wartość).
Regular expression	Wzorzec PCRE w formacie `/pattern/flags` oraz szablon zamiany odwołujący się do grup przechwytujących przez `$0`, `$1`, `$2`. Dozwolone flagi: `i`, `s`, `u`. Niepoprawne wzorce są odrzucane z czytelnym błędem.
Remove HTML	Usuwa wszystkie znaczniki HTML.
HTML → plain text (formatted)	Konwertuje HTML na sformatowany tekst zwykły.
Lowercase	Zamienia na małe litery.
Uppercase	Zamienia na wielkie litery.
Capitalize first letter	Wielką literą tylko pierwszy znak.
Title Case (each word)	Wielką literą każde słowo.
Max length	Skraca do zadanej liczby znaków.

Reguły działają w kolejności Priority — niższe liczby uruchamiają się jako pierwsze. Przykład: reguła priorytet 10 Remove HTML, potem priorytet 20 Lowercase, potem priorytet 30 Max length 200 zamienia opis sformatowany w czysty tekst małymi literami, przycięty do 200 znaków.

Import / Eksport

Przyciski Export Mappings i Import Mappings pozwalają przenieść całą konfigurację powiązań (razem z regułami wartości) między połączeniami lub między sklepami:

Export Mappings otwiera okno, w którym wybierasz Source connection. Pobrany plik JSON zawiera wszystkie powiązania atrybutów dla wybranego połączenia. Atrybuty są identyfikowane po kodzie operatora, a nie po identyfikatorach wewnętrznych, dzięki czemu plik jest przenośny między połączeniami.
Import Mappings otwiera okno, w którym wybierasz Target connection, Import mode (Merge — keep existing mappings, only add new ones albo Replace — remove existing mappings of the target connection first) oraz plik JSON do wgrania. Podsumowanie na końcu pokazuje, ile powiązań zostało Imported, Replaced, Skipped oraz ile było Missing attributes (wymienionych w pliku JSON, ale nieistniejących w liście atrybutów docelowego połączenia).

Krok Auto-Map w kreatorze pierwszego uruchomienia akceptuje ten sam format JSON, więc wyeksportowany plik możesz zastosować już przy pierwszej konfiguracji.

Wskazówki i pułapki

Powiązane tematy

Categories — każda kategoria marketplace’u ma własny zestaw wymaganych atrybutów
Catalog export — korzysta z powiązań atrybutów w trakcie eksportu
Offer fields — odpowiednik per oferta; te same typy źródła i reguły wartości