Übung 08

Ziel dieser Ausarbeitung ist ein vollständiges Architektur-Design in Xentral Connect, das alle Anforderungen (Lagerbestands-Sync, Order-Import, Versand-Rückmeldung, Fehlerbehandlung) abdeckt. Die Architektur folgt Prinzipien der Entkopplung, Skalierbarkeit, Wiederverwendbarkeit und robuster Fehlerbehandlung.

Wichtige Restriktionen / Annahmen kurz zusammengefasst:

  • Marktplatz-API-Limit: 1000 Anfragen / Stunde.

  • Marktplatz-Batch-Endpunkt: bis zu 100 Artikel pro Aufruf.

  • Kunde hat > 5000 Artikel — Performance-Strategien erforderlich.

  • Echtzeit-Anforderungen für Bestell-Import und Versand-Feedback.

  • Fehler müssen nach Slack gemeldet und Daten zur Analyse gespeichert werden.

1) Architekturbeschreibung (Übersicht)

Gesamtstruktur: 5 voneinander getrennte Workflows in Xentral Connect, dazu ein gemeinsamer Error-Handling-Workflow und ein kleiner Hilfs-Workflow für wiederverwendbare Dienste (z.B. RateLimiter/Queue-Controller).

Workflows (kurz):

  • Stock Sync Workflow (Timer)

  • Order Import Workflow (Webhook)

  • Shipment Notification Workflow (Event)

  • Error Handling Workflow (Error Trigger)

  • Shared Services Workflow (Rate Limiting / Retry Queue / Lookup Cache) — optional als Hilfs-Workflow

Warum mehrere Workflows?

  • Entkopplung: einzelne Verantwortlichkeiten erleichtern Wartung & Tests.

  • Fehlerisolation: Fehler in einem Prozess betreffen nicht andere.

  • Skalierung: Stock Sync kann unabhängig skaliert/batched / throttled werden.

  • Wiederverwendbarkeit: Shared Services (RateLimiting, Cache) von mehreren Workflows nutzbar.

Interaktion und Trigger:

  • Stock Sync: Timer-Trigger alle 15 Minuten.

  • Order Import: Webhook-Trigger (Marktplatz -> Xentral) für Near-Realtime.

  • Shipment Notification: Event-Trigger auf Xentral-Ereignis (deliverynote.created).

  • Error Handling: Error-Trigger, der Fehlkontexte empfängt.

  • Shared Services: Invoked via HTTP-Invoke oder interner Aufruf/Kanal.

Besondere Strategien:

  • Performance: nur geänderte Artikel synchronisieren (modified > letzter Lauf). Batch-Größen = 100, benutze Marktplatz-Batch-Endpunkt. Parallelisierung mit begrenzter Workeranzahl, respektiere API-Limit (RateLimiter).

  • API-Limitführung: zentraler RateLimiter-Service trackt Anfragen/Stunde; Stock Sync plant Batch-Aufrufe so, dass 1000/h nicht überschritten werden.

  • SKU-Mapping: zentrale Transformations-Funktion / Mapping-Knoten (entfernt MP- Präfix).

  • Customer-Lookup: zuerst Suche in Xentral via USt-IdNr; beim Nicht-Fund: create-customer.

  • Fehlerbehandlung: try/catch-Pattern innerhalb Workflows → bei Fehlern: Trigger an Error-Handling-Workflow mit vollständigem Input, Stack-Trace, Metadaten; persistiere fehlerhaften Payload in einem Data Store (z.B. S3 / Blob / DB).

  • Observability: strukturierte Logs, korrelations-IDs (z. B. trace_id pro Bestellung / Batch), Monitoring-Metriken (anzahl Fehler, Latenz, API-Nutzung).

2) Detaillierte Workflow-Pläne (Schritt-für-Schritt)

Hinweis: Jeder Workflow listet die Kernlogik und die wichtigsten Knoten in Xentral Connect (Trigger, HTTP, Function, If, Error-Trigger, Data Store, Slack).

1

Stock Sync Workflow (Timer-Trigger, alle 15 Minuten)

Zweck: Lagerbestände von Xentral → Marktplatz in effizienten Batches aktualisieren.

Kernschritte:

  1. Trigger: Timer (alle 15 Min).

  2. State/Kontext lesen: letzten Sync-Timestamp aus Data Store holen (z. B. KV oder DB).

  3. Query Xentral: article.list mit Filter modified > last_run_timestamp (falls Xentral das unterstützt) — sonst Änderungsspur / delta endpoint nutzen.

    • Knoten: HTTP-Request / Xentral-Connector

  4. Wenn Ergebnis leer: update last_run_timestamp und Ende.

  5. Normalisieren & Filter: nur aktive Artikel, nur relevante Lagerorte, berechne verfügbare Menge (available = total - reserved).

    • Knoten: Function / Transform

  6. Gruppieren in Batches à 100 Artikel.

    • Knoten: Function (chunk array into 100s)

  7. RateLimit-Planung: Bestimme erlaubte parallele Batch-Aufrufe basierend auf verbleibendem API-Budget (RateLimiter-Service abfragen).

    • Knoten: HTTP-Invoke RateLimiter / Function

  8. Für jeden Batch:

    • Build Marktplatz-Batch-Payload.

    • HTTP-Request zu Marktplatz Batch-Endpunkt (1 Request aktualisiert bis zu 100 SKUs).

    • On HTTP-Error: Retry-Strategie mit expon. Backoff (max N), bei dauerhaften Fehlern send Error-Trigger an Error-Handling-Workflow inkl. batch payload.

  9. Nach erfolgreichem Durchlauf: update last_run_timestamp (= Startzeit dieses Laufs).

  10. Metriken/Logs: Anzahl verarbeiteter Artikel, API-Anfragen gezählt, Laufzeit.

Wichtige Knoten: Timer Trigger, HTTP-Request (Xentral), Function (chunk/transform), Parallel-Runner begrenzt, HTTP-Request (Marktplatz), Data Store (KV), Error Trigger.

Throttling-Strategie:

  • Max 1000 Anfragen/h → bei Batch-Größe 100 benötigen wir max 10 Requests pro 1000 Artikel. Für 5000 Artikel also 50 Requests pro kompletten Sync; das ist innerhalb des Limits, aber wir planen trotzdem kontrollierte Parallelität und einen Safety-Puffer.

  • RateLimiter-Service verwaltet ein Token-Bucket. Stock Sync fragt vor Batch-Aufruf ein Token-Set an.

2

Order Import Workflow (Webhook-Trigger, Echtzeit)

Zweck: Neue Marktplatz-Bestellungen in Xentral anlegen.

Kernschritte:

  1. Trigger: Webhook (Marktplatz sendet Bestellung).

  2. Korrelations-ID erzeugen (trace_id) und Log-Eintrag.

  3. Validierung: Schema-Validation der Bestellung (relevante Felder vorhanden: customer, items, total, invoiceAddr, vatId, external_order_id).

    • On validation fail → Error-Trigger (mit Payload).

  4. Customer Lookup:

    • Extract USt-IdNr. (VAT id) aus Bestellung.

    • Query Xentral: customer.list filter by USt-IdNr.

    • If found: use existing customer_id.

    • Else: create customer via customer.create (mapping der Felder).

    • Knoten: HTTP-Request (Xentral), If node, HTTP-Request create.

    • On create-failure → Error-Trigger.

  5. Items / SKU-Mapping:

    • Für jedes order-item: remove MP- prefix (e.g. MP-1234 → 1234).

    • Option: Validiere SKU existiert in Xentral via article.get oder article.list (batch lookup).

    • Wenn eine SKU unbekannt:

      • Markiere Artikel als unknown.

      • Entweder: a) Versuch Auto-Match via EAN/Name, b) Fail the order.

      • Bei Fehlschlag → Error-Trigger (inkl. original order payload).

  6. Build Xentral Order Payload (positions, customer_id, payment/shipping, external ids, Marktplatz-Metadaten).

  7. Create Order in Xentral: order.create (oder passende endpoint).

    • On success: ack to Marktplatz falls erforderlich (HTTP 200 to webhook origin or explicit API).

  8. Post-Processing:

    • Set a flag on created order (custom field) wie origin: marketplace und marketplace_order_id.

    • Emit Trace-Event / Log.

  9. Error handling:

    • Alle Fehler (invalid data, unknown SKU, customer create fail) → call Error-Handling Workflow (Error-Trigger) with full context and persisted payload.

Wichtige Knoten: Webhook Trigger, JSON Schema Validator, Function (sku mapping), HTTP-Request Xentral (customer, article check, create order), If, Parallel batch SKU-check, Error Trigger.

Optimierung:

  • Batch-SKU-Checks in Gruppen (z. B. 50 per request) um Xentral-API-Calls zu reduzieren.

  • Local cache (Shared Services) für SKU lookups und VAT lookups (TTL z. B. 5 min – 1 h).

3

Shipment Notification Workflow (Event-Trigger: deliverynote.created)

Zweck: Sobald ein Lieferschein in Xentral für einen Marktplatz-Auftrag erstellt wird, Marktplatz informieren (versendet + Tracking).

Kernschritte:

  1. Trigger: Event Listener auf Xentral-Ereignis deliverynote.created oder Polling auf deliverynote.list mit recent new flag.

  2. Payload-Validierung: prüfe, ob zugehöriger Auftrag origin: marketplace oder custom field marketplace_order_id existiert.

    • If not marketplace-origin → End (ignorieren).

  3. Extrahiere tracking-number, carrier, marketplace_order_id.

  4. Build Marktplatz-Payload (order id + tracking + carrier + shipped flag).

  5. HTTP-Request: Marktplatz API → mark shipment as shipped.

    • On success: log & update Xentral order (set metadata shipped_confirmed:true).

    • On failure:

      • Retry (expon. backoff).

      • Bei dauerhaften Fehlern send Error-Trigger (inkl. deliverynote payload).

  6. Optional: send confirmation to ERP user via Slack/Email on critical failure.

Wichtige Knoten: Event Trigger, If (check origin), Function (transform), HTTP-Request to Marktplatz, Error Trigger.

Realtime-Anforderung: Event-Trigger ist bevorzugt; falls nicht verfügbar, Polling mit sehr kurzen Intervallen (z. B. 1–2 Minuten) wäre fallback.

4

Error Handling Workflow (Error-Trigger)

Zweck: Zentrale Verarbeitung und Persistierung aller Fehler aus anderen Workflows, Benachrichtigung an Slack, Persistenz der fehlerhaften Payloads.

Kernschritte:

  1. Trigger: Error-Trigger (Workflows senden hier standardisierte Fehlernachrichten).

    • Fehler-Payload enthält: trace_id, workflow_name, step_name, error_message, stack, original_payload, retries, timestamp.

  2. Persistieren:

    • Speichere Original-Payload + Fehler-Metadaten in persistentem Storage (z. B. S3/Blob/DB) unter generischer Pfadstruktur (workflow/date/trace_id.json).

    • Falls Storage fehlschlägt: Fallback in DB.

  3. Klassifizieren:

    • Error-Typ bestimmen: transient vs permanent vs data_error.

    • Bei transient: optional re-queue in Retry-Queue (Shared Services) mit Rate-limit/backoff.

  4. Notify Slack:

    • Formatierte Nachricht an Slack Incoming Webhook:

      • Kurzinfo: Workflow + Error.

      • Details: trace_id, error_message, link to stored payload, timestamp, suggested action.

      • Option: attach small excerpt of payload (truncate).

  5. Escalation:

    • Bei recurring errors (z. B. same error > N times in T interval) → send to escalation channel / create ticket.

  6. Metrics & Logging: increment error counters, expose for monitoring.

Wichtige Knoten: Error Trigger, HTTP-Request (to Storage), HTTP-Request (Slack), Function (classify), Data Store.

Sicherheits- / Datenschutzhinweis: Pflege sensibler Kundeninfos beim Persistieren; falls nötig, maskiere sensible Felder bevor Speicherung oder setze eingeschränkten Storage-Zugriff.

5

Shared Services Workflow (Hilfs-Workflow für RateLimiter, Cache, Retry-Queue)

Zweck: Zentraler Dienst für:

  • Rate limiting (Marktplatz API)

  • Cache für SKU- und Customer-Lookups

  • Retry-Queue (persistente Retry-Items mit Backoff)

Kernschritte:

  1. RateLimiter:

    • Exponiertes HTTP-Endpoint: callers fragen Tokens an (z. B. n tokens für n Batch-Calls).

    • Verwaltet ein Token-Bucket / Window für 1000 requests/h.

    • Antwort: allow / waitUntil (ETA) / deny.

  2. Cache:

    • API: getSkuInfo(sku) → returns cached article metadata oder miss.

    • Cache TTL konfigurierbar.

  3. Retry-Queue:

    • Aufnehmen von transient errors mit metadata (retry_count, backoff_until).

    • Worker (polling) verarbeitet due items und re-invokes relevant workflows.

  4. Auth & Security:

    • Authentifiziere Aufrufer via API-Keys oder internen Auth.

Wichtige Knoten: HTTP-Trigger (for service calls), Data Store (counter, cache), Timer (worker), Function.

Integration:

  • Stock Sync benutzt RateLimiter vor jedem Batch-Aufruf.

  • Order Import nutzt Cache für SKU/customer lookups.

  • Error Handler nutzt Retry-Queue für transient retry.

3) Mermaid-Diagramm (Architektur-Visualisierung)

Füge hier ein oder mehrere Mermaid-Diagramme ein, die die Workflows, Trigger und externen Systeme zeigen.

Code (Mermaid):

(Optional: separater Sequenz- oder detailliertes Diagramm für Order Import intern mit SKU-Checks, Customer Create, Retries.)

Zusätzliche Implementierungs-Hinweise (Kurz)

  • Korrelations-ID: Bei jedem eingehenden Request/Webhook trace_id erzeugen und in allen nachfolgenden Requests / Logs mitschicken.

  • Idempotenz: Bei Erstellen von Ressourcen (Order, Customer) externe IDs/Client-Tokens verwenden, damit doppelte Webhook-Posts nicht zu Duplikaten führen.

  • Retries: Differenziere transient HTTP 5xx (retry) vs 4xx (data error). 4xx → ErrorWF.

  • Monitoring: Exportiere Metriken (prometheus-styl) für API usage, error rate, latency.

  • Secrets: API-Keys & Webhooks in Secret Manager / Xentral Connect Secret Store.

  • Tests: Unit-Tests für Transform-Funktionen (SKU Mapping), Integration-Tests für workflows mit sandbox endpoints.

Wenn du möchtest, kann ich jetzt:

  • a) die Mermaid-Diagramme weiter aufsplitten (z. B. detaillierter Order-Import Sequenz),

  • b) konkrete Beispiel-JSON-Payloads für Webhook / Batch-Requests erzeugen,

  • c) Xentral Connect-Knoten-Mapping in exakte Knotenfolgen (Name der Knoten) übersetzen, passend zu deiner Connect-Instanz. Welche Option bevorzugst du?

PreviousLektion 08

Was this helpful?