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)
    │       └── Auswahloptionen (bei Auswahl/Mehrfachauswahl)
    ├── 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)

Zusatzfeld-Set-Liste

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	Semikolon-getrennte Werteliste (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 (ISO 8601)
Auswahl	sw-single-select	Einzelauswahl aus vordefinierten Optionen
Mehrfachauswahl	sw-multi-select	Mehrere Optionen gleichzeitig auswählbar
Farbwähler	sw-field (colorpicker)	Farbauswahl (#RRGGBB)
Medien	sw-media-field	Medienauswahl

Auswahloptionen und Labels

Beim Import aus Shopware werden die Auswahloptionen eines Auswahl- oder Mehrfachauswahl-Feldes vollständig übernommen – inklusive der deutschen und englischen Bezeichnungen. BC speichert diese in der internen Tabelle ShopwareAPI Zusatzfeld-Option mit folgenden Feldern:

Feld	Beschreibung
Wert	Technischer Wert (wird an Shopware gesendet, z.B. `color_red`)
Bezeichnung (DE)	Anzeigename Deutsch (z.B. `Rot`)
Bezeichnung (EN)	Anzeigename Englisch (z.B. `Red`)
Position	Reihenfolge im Dropdown

Beim Rück-Sync zu Shopware werden Labels vollständig mitgeschickt:

{
  "config": {
    "options": [
      { "value": "color_red",  "label": { "de-DE": "Rot",  "en-GB": "Red"  } },
      { "value": "color_blue", "label": { "de-DE": "Blau", "en-GB": "Blue" } }
    ]
  }
}

Wurden Zusatzfelder manuell in BC angelegt (nicht importiert), können Optionen als Semikolon-getrennte Liste im Feld „Auswahloptionen" erfasst werden (Rot;Blau;Grün). In diesem Fall werden die Werte als Labels übernommen.

Zusatzfeld-Werte

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

Produktkarte → Unterseite „Shopware Zusatzfelder"
Kategoriekarte → Unterseite „Shopware Zusatzfelder"

Wert eingeben

Jede Zeile zeigt den Bezeichnungnamen des Feldes (in der Benutzersprache), den Feldtyp und ein Werteingabefeld. Für Auswahl- und Mehrfachauswahl-Felder erscheint beim Klick in das Wertefeld eine Dropdown-Liste mit den verfügbaren Optionen.

ShopwareAPI Produktkarte – Zusatzfelder im unteren Bereich

Verhalten bei Mehrfachauswahl (Toggle)

Beim Feldtyp Mehrfachauswahl verhält sich der Lookup wie ein Toggle:

Option auswählen → Wert wird zur aktuellen Auswahl hinzugefügt (Rot;Blau)
Bereits gewählte Option erneut auswählen → Wert wird aus der Auswahl entfernt
Manuell bearbeiten → Semikolon-getrennte Liste direkt eingeben

Intern werden mehrere gewählte Werte als Semikolon-getrennte Liste gespeichert (Rot;Blau;Grün) und beim Senden an Shopware automatisch als JSON-Array serialisiert:

{ "custom_field_color": ["Rot", "Blau", "Grün"] }

Serialisierungsregeln

Feldtyp	Gespeichert in BC	An Shopware gesendet
Text, Textbereich, HTML	Text	`"Text"`
Ganzzahl	`"42"`	`42`
Dezimalzahl	`"3.14"`	`3.14`
Kontrollkästchen	`"true"` / `"false"`	`true` / `false`
Datum/Uhrzeit	ISO 8601 oder BC-Format	`"2024-01-15T10:30:00.000+00:00"`
Auswahl	`"color_red"`	`"color_red"`
Mehrfachauswahl	`"Rot;Blau"`	`["Rot", "Blau"]`
Farbwähler	`"#FF0000"`	`"#FF0000"`
Medien	UUID	`"uuid"`

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:

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

Beim Import werden auch alle Auswahloptionen (inkl. Labels) übernommen.

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

Table of Contents