Lektion 06

Heute wird es ernst! Wir kombinieren alles, was du in den letzten fünf Modulen gelernt hast, um einen der wichtigsten und häufigsten E-Commerce-Workflows zu bauen: den automatischen Import von Bestellungen aus einem Webshop nach Xentral. Dies ist ein Meilenstein auf deinem Weg zum Xentral Connect Entwickler.

Platz für deine Notizen:

---

Checkliste: Was du heute erreichen wirst

• Die logischen Schritte eines Bestell-Import-Workflows skizzieren können.

• Einen Workflow mit einem Webhook-Trigger starten.

• Einen "Customer-Lookup" implementieren, um Kunden-Duplikate zu vermeiden.

• Einen Auftrag in Xentral anlegen (salesorder.create).

• Eine Schleife bauen, die durch Bestellpositionen iteriert und diese zu einem Auftrag hinzufügt (salesorder.add_item).

• Verstehen, wie man mit verschachtelten Daten (Kopf- und Positionsdaten) umgeht.

---

Übung: Der Bestell-Import-Workflow (vereinfacht)

Ziel: Wir bauen die Kernlogik des Bestell-Imports. Wir verwenden Testdaten und vereinfachen einige Schritte, aber die grundlegende Struktur ist identisch mit einem Live-Workflow.

1

Vorbereitung & Testdaten

• Workflow erstellen:

  • Erstelle einen neuen Workflow mit dem Namen M06-Order-Import.

• Testdaten simulieren:

  • Füge einen Set-Knoten hinzu, um eine eingehende Bestellung vom Shop zu simulieren.

  • Nenne ihn shop_order und gib folgenden JSON-Wert ein.

  • Wichtig: Ersetze die E-Mail-Adresse durch eine, die in deiner Xentral-Demoinstanz existiert, und teste zusätzlich mit einer E-Mail, die nicht existiert, um beide Fälle zu prüfen.

{
  "customer": {
    "email": "[email protected]",
    "firstName": "Test",
    "lastName": "Kunde"
  },
  "shipping_address": {
    "street": "Musterstraße 1",
    "zip": "12345",
    "city": "Musterstadt"
  },
  "line_items": [
    {
      "sku": "ART-0001",
      "quantity": 2,
      "price": 50.0
    },
    {
      "sku": "ART-0002",
      "quantity": 1,
      "price": 75.5
    }
  ]
}

2

Kunde finden oder erstellen

• Kunde in Xentral suchen:

  • Füge einen Xentral > customer.list-Knoten hinzu.

  • Setze einen Filter, um nach der E-Mail aus den Testdaten zu suchen: {{$node["shop_order"].json["customer"]["email"]}}

• Prüfen, ob Kunde existiert:

  • Füge einen If-Knoten hinzu.

  • Prüfe, ob das Ergebnis des customer.list-Aufrufs leer ist.

  • Expression: {{$node["Xentral"].json.length}} — Operation Equal — Value 0.

• Kunde anlegen (im true-Pfad):

  • Im true-Pfad (Kunde nicht gefunden) füge einen Xentral > customer.create-Knoten hinzu.

  • Mappe die Kundendaten aus dem shop_order-Knoten.

• Kunden-ID speichern:

  • Füge nach dem If-Block einen Set-Knoten hinzu, um die Kunden-ID zu speichern. Nenne ihn xentral_customer_id.

  • Der Wert muss eine Expression sein, die beide Pfade abdeckt, z. B.: {{$node["If"].json["true"] ? $node["Create Customer"].json["id"] : $node["Find Customer"].json[0]["id"]}}

  • Passe die Knotennamen an deine tatsächlichen Knotennamen an.

3

Auftrag und Positionen anlegen

• Auftragskopf anlegen:

  • Füge einen Xentral > salesorder.create-Knoten hinzu.

  • Gib als kundenid die Variable {{$node["xentral_customer_id"].json}} an.

  • Mappe außerdem die Adressdaten (z. B. shipping_address).

• Durch Positionen loopen:

  • Füge einen Loop over Items-Knoten hinzu.

  • Verbinde ihn mit dem line_items-Array aus dem shop_order-Knoten.

• Positionen hinzufügen:

  • Innerhalb der Schleife füge einen Xentral > salesorder.add_item-Knoten hinzu.

  • id: Die ID des Auftrags aus dem salesorder.create-Knoten.

  • artikel (SKU): Aus der aktuellen Schleifeniteration: {{$node["Loop"].context["value"]["sku"]}}

  • menge & preis: Ebenfalls aus der aktuellen Schleifeniteration.

• Workflow testen:

  • Speichere, aktiviere und teste den Workflow.

Erwartetes Ergebnis:

• Der Workflow läuft erfolgreich durch.

• In deiner Xentral-Instanz wurde ein neuer Auftrag für den entsprechenden Kunden angelegt.

• Der Auftrag enthält genau die zwei Positionen aus den Testdaten mit den korrekten Mengen und Preisen.

---

Cheat Sheet: Wichtige Begriffe aus Modul 6

Begriff	Erklärung
End-to-End-Workflow	Ein Workflow, der einen kompletten Geschäftsprozess von Anfang bis Ende abbildet und dabei mehrere Systeme und Logikschritte integriert.
Webhook	Ein Mechanismus, bei dem ein System (z.B. der Shop) bei einem Ereignis (z.B. neue Bestellung) automatisch eine Nachricht an eine vordefinierte URL (den Webhook-Trigger in Connect) sendet.
Customer-Lookup	Der Prozess, bei dem vor dem Anlegen eines neuen Kunden geprüft wird, ob dieser bereits im Zielsystem existiert, um Duplikate zu vermeiden.
Kopfdaten (Header)	Die allgemeinen Daten eines Belegs, die für den gesamten Beleg gelten (z.B. Kundennummer, Lieferadresse, Datum).
Positionsdaten (Items)	Die Detail-Daten eines Belegs, die sich auf einzelne Zeilen beziehen (z.B. Artikelnummer, Menge, Preis pro Stück). Oft als Array im JSON.
SKU-Mapping	Die Zuordnung von Artikelnummern (Stock Keeping Units) zwischen verschiedenen Systemen, falls diese nicht identisch sind.
Try-Catch (Fehlerbehandlung)	Ein Programmierkonzept, bei dem ein "riskanter" Code-Block (Try) ausgeführt wird. Wenn ein Fehler auftritt, wird die Ausführung nicht abgebrochen, sondern in einen Catch-Block umgeleitet, wo der Fehler behandelt werden kann. In Connect wird dies über den Error Trigger realisiert.

---

Wenn du möchtest, kann ich dir aus diesem Workbook auch eine fertige Knotenkonfiguration (JSON-Export/Import-fähig) für Connect skizzieren — sag Bescheid, welche Knotennamen du verwenden willst, dann passe ich die Expressions entsprechend an.