Zusatzfelder

Zusatzfelder ermöglichen es, eigene Felder für verschiedene Shopware-Entitäten zu definieren und deren Werte aus Business Central heraus zu pflegen und zu synchronisieren.

Unterstützte Entitäten

Zusatzfelder können für folgende Shopware-Entitäten definiert werden:

Entität	Beschreibung
Produkt	Produkte
Kategorie	Kategorien
Hersteller	Hersteller
Kunde	Kunden
Kundenadresse	Kundenadressen
Bestellung	Bestellungen
Lieferzeit	Lieferzeiten

Struktur

Zusatzfelder sind in drei Ebenen organisiert:

Zusatzfeld-Set (Gruppe)
    │
    ├── Zusatzfeld (Felddefinition)
    ├── Zusatzfeld (Felddefinition)
    └── Zusatzfeld (Felddefinition)

Zusatzfeld-Wert (Wert pro Entität)
    └── Verknüpft mit Set + Feld + konkreter Entität (z.B. Produkt X)

Zusatzfeld-Sets

Ein Zusatzfeld-Set ist eine Gruppe zusammengehöriger Felder.

Felder auf der Set-Karte

Feld	Beschreibung
Shopware Zusatzfeld-Set-Id	Eindeutige UUID des Sets in Shopware
Name	Technischer Name des Sets
Bezeichnung (DE) / Bezeichnung (EN)	Anzeigename (Deutsch / Englisch)
Aktiv	Set aktiv/inaktiv
Position	Reihenfolge in der Shopware-Administration

Entitäts-Zuordnung

Über Checkboxen wird festgelegt, für welche Entitäten das Set gilt:

• Für Kategorien, Für Produkte, Für Hersteller
• Für Kunden, Für Kundenadressen
• Für Bestellungen, Für Lieferzeiten

Sync-Status

Feld	Beschreibung
Synchronisiert	Set wurde erfolgreich synchronisiert
Letzter Sync	Zeitpunkt der letzten Synchronisation
Feldanzahl	Anzahl der Felder im Set (berechnet)

Zusatzfelder (Felddefinitionen)

Auf der Set-Karte werden die einzelnen Felder als ListPart verwaltet:

Feld	Beschreibung
Shopware Zusatzfeld-Id	Eindeutige UUID des Feldes
Name	Technischer Feldname
Bezeichnung (DE) / Bezeichnung (EN)	Anzeigename (Deutsch / Englisch)
Feldtyp	Datentyp des Feldes
Position	Reihenfolge im Set
Aktiv	Feld aktiv/inaktiv
Pflichtfeld	Pflichtfeld
Platzhalter	Platzhaltertext im Admin
Auswahloptionen	JSON-Array mit Optionen (nur bei Auswahl/Mehrfachauswahl)

Feldtypen

Typ	Shopware-Komponente	Beschreibung
Text	sw-field (text)	Einzeiliges Textfeld
Textbereich	sw-field (textarea)	Mehrzeiliges Textfeld
HTML	sw-text-editor	HTML-Editor
Ganzzahl	sw-field (number, int)	Ganzzahl
Dezimalzahl	sw-field (number, float)	Dezimalzahl
Kontrollkästchen	sw-field (checkbox)	Ja/Nein
Datum/Uhrzeit	sw-field (datetime)	Datum und Uhrzeit
Auswahl	sw-single-select	Einzelauswahl
Mehrfachauswahl	sw-multi-select	Mehrfachauswahl
Farbwähler	sw-field (colorpicker)	Farbauswahl
Medien	sw-media-field	Medienauswahl

Zusatzfeld-Werte

Zusatzfeld-Werte werden direkt auf den jeweiligen Entitätskarten gepflegt:

• Produktkarte → Unterseite "Shopware Zusatzfelder"
• Kategoriekarte → Unterseite "Shopware Zusatzfelder"

Jeder Wert-Eintrag enthält:

Feld	Beschreibung
Zusatzfeld-Set-Id	Zugehöriges Zusatzfeld-Set
Shopware Zusatzfeld-Id	Zugehöriges Zusatzfeld
Entitätstyp	Entitätstyp (Produkt, Kategorie etc.)
Entitäts-ID	UUID der konkreten Entität
Wert	Feldwert (Text)
Wert JSON	Komplexer Wert (JSON, für Arrays/Objekte)

Die Werte werden bei der Synchronisation als customFields-Objekt im Entity-JSON mitgeschickt.

Synchronisation

Sets und Felder an Shopware senden

Zusatzfeld-Sets werden inklusive aller Felder an Shopware gesendet:

• POST /api/custom-field-set – Neues Set erstellen (mit verschachtelten Fields und Relations)
• PATCH /api/custom-field-set/{id} – Set aktualisieren
• DELETE /api/custom-field-set/{id} – Set löschen

JobQueue-Funktion: SyncCustomFieldSets (Direkt-Sync, kein Puffer)

Aktionen auf der Zusatzfeld-Set-Karte/Liste

Aktion	Beschreibung
An Shopware senden	Set mit allen Feldern an Shopware synchronisieren
Alle nicht synchronisierten senden	Alle Sets mit Synchronisiert = Nein senden
Aus Shopware importieren	Zusatzfeld-Sets aus Shopware laden
Sync-Status zurücksetzen	Set für erneute Synchronisation vormerken
Shopware Transaktionsprotokoll	Transaktionsprotokoll anzeigen

Sets und Felder aus Shopware importieren

Bestehende Zusatzfeld-Sets können aus Shopware importiert werden:

1. JobQueue: GetCFSetImport – Shopware Zusatzfeld-Sets abrufen → Transaktionsprotokoll
2. JobQueue: ProcessCFSetImport – Transaktionsprotokoll → Zusatzfeld-Set + Zusatzfeld-Tabellen in BC

Der Import kann über den Setup-Wizard (Schritt: Shopware-Daten importieren) oder manuell ausgelöst werden.

Werte synchronisieren

Zusatzfeld-Werte werden automatisch mitgesendet, wenn die zugehörige Entität synchronisiert wird:

• Bei Produktsync: Zusatzfeld-Werte werden als customFields-Objekt im Produkt-JSON mitgesendet
• Bei Kategoriesync: Zusatzfeld-Werte werden als customFields-Objekt im Kategorie-JSON mitgesendet