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
Auftragszeile	Bestellzeilen (nur Import aus Shopware, kein Rück-Sync)
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"
Bestellkarte → FactBox „Zusatzfelder Auftragszeilen" (zeigt CF-Werte pro Auftragszeile; rein lesend, kein Rück-Sync)

Sprachspezifische Zusatzfeld-Werte (Übersetzungen)

Zusatzfeld-Werte können für jede Sprache separat gepflegt werden. Die Aktion Übersetzungen im Zusatzfeld-Werte-ListPart öffnet die Seite Shopware Zusatzfeld-Wertübersetzungen — gefiltert auf die aktuelle Entität. Der Name des Zusatzfelds wird dabei als Überschrift oberhalb der Liste angezeigt (keine eigene Spalte mehr).

Feld	Beschreibung
Sprachcode	BC-Sprachcode für diese Übersetzung
Sprache	Anzeigename der Sprache
Wert	Übersetzter Wert in der jeweiligen Sprache

Beim Produktsync werden Werte mit gesetztem Sprachcode als sprachspezifische customFields-Überschreibung an Shopware gesendet.

Die Aktion Von Shopware importieren im Zusatzfeld-Werte-ListPart ruft die Zusatzfeld-Werte inklusive sprachspezifischer Übersetzungen erneut aus Shopware ab. Sie ist aktuell nur für die Entitätstypen Produkt und Kategorie implementiert; bei allen anderen Entitätstypen (Hersteller, Kunde, Kundenadresse, Bestellung, Lieferzeit) erscheint die Meldung „Import aus Shopware wird für diesen Entitätstyp nicht unterstützt."

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.

Übersetzungen

Zusatzfeld-Sets, -Felder und -Optionen können für beliebig viele Sprachen übersetzt werden. Änderungen an Übersetzungen setzen den Sync-Status des zugehörigen Sets automatisch auf „nicht synchronisiert".

Set-Übersetzungen werden auf der Zusatzfeld-Set-Karte in der FactBox Übersetzungen gepflegt:

Feld	Beschreibung
Sprachcode	BC-Sprachcode (Lookup auf Sprachen mit Shopware-ID)
Bezeichnung	Anzeigename des Sets in dieser Sprache

Feld-Übersetzungen sind über die FactBox auf der Feldliste des Sets erreichbar:

Feld	Beschreibung
Sprachcode	BC-Sprachcode
Bezeichnung	Anzeigename des Feldes in dieser Sprache
Platzhalter	Platzhaltertext in dieser Sprache

Options-Übersetzungen stehen für Auswahl- und Mehrfachauswahl-Felder zur Verfügung und werden in der FactBox auf der Optionsliste gepflegt:

Feld	Beschreibung
Sprachcode	BC-Sprachcode
Bezeichnung	Anzeigename der Option in dieser Sprache

Beim Import aus Shopware werden alle vorhandenen Übersetzungen automatisch den passenden BC-Sprachcodes zugeordnet (über das Feld Shopware ID an der BC-Sprachtabelle).

Beim Sync nach Shopware werden die Übersetzungen vollständig mitgesendet:

{
  "translations": {
    "de-DE": { "label": "Farbe" },
    "en-GB": { "label": "Color" }
  }
}

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

Automatischer Sync-Trigger

Jede Änderung an einem Zusatzfeld-Wert löst automatisch den Sync der zugehörigen Entität aus – ohne dass ein manueller Sync-Anstoß erforderlich ist:

Wird ein Produktwert geändert → das zugehörige Shop-Item wird in den Sync-Puffer eingestellt
Wird ein Kategoriewert geändert → die zugehörige Kategorie wird in den Sync-Puffer eingestellt

Dies gilt für das Anlegen, Ändern und Löschen von Werten. Der Sync erfolgt asynchron über die normalen Sync-Pipelines (PrepareShopItemSyncEntries bzw. PrepareCategorySyncEntries).

Zusatzfelder auf Auftragszeilen

Beim Bestellimport aus Shopware werden customFields auf Auftragszeilen automatisch ausgelesen und in BC gespeichert. Sie sind in der FactBox „Zusatzfelder Auftragszeilen" auf der Bestellkarte einsehbar sowie über die Aktion Zusatzfelder direkt auf der Auftragszeile erreichbar.

Note

Auftragszeilen-Zusatzfelder werden nur importiert (Shopware → BC), nicht zurückgeschrieben. Eine manuelle Bearbeitung in BC hat keinen Effekt auf Shopware.

Table of Contents