Vorlagen sind unverzichtbare Bausteine in GelatoConnect, die sowohl eingehende als auch ausgehende Datenströme steuern. Sie wandeln eingehende Kundendaten in Formate um, die Ihr Workflow verarbeiten kann, und bereiten ausgehende Daten aus GelatoConnect so auf, dass sie den Anforderungen der Systeme Ihrer Kunden entsprechen. In dieser Anleitung erfahren Sie Schritt für Schritt, wie Sie Vorlagen für beide Richtungen des Datenaustauschs in Ihren Auftragsmanagement-Workflows erstellen, testen und implementieren.
Vorlagen in GelatoConnect einfach erklärt
Vorlagen in GelatoConnect dienen als Blaupausen, die festlegen, wie Daten aufgebaut, verarbeitet und dargestellt werden sollen. Sie steuern zwei entscheidende Datenflüsse:
Vorlagen für eingehende Daten
Diese Vorlagen wandeln die Daten aus den Systemen Ihrer Kundinnen und Kunden in Formate um, die GelatoConnect verarbeiten kann:
Bestellübermittlungsanfrage: Wandelt Kundendaten in das interne Format von GelatoConnect um
Anfrage stornieren: Formatiert Stornierungsanfragen so, dass sie von GelatoConnect verstanden werden
Vorlagen für ausgehende Daten
Diese Vorlagen bereiten die Daten so auf, dass sie von GelatoConnect an Ihre Kundinnen und Kunden oder deren Systeme zurückgesendet werden:
Antwortformatierung: Strukturiert API-Antworten auf Bestellungen oder Stornierungen
Ereignisbenachrichtigungen: Erstellt einheitliche Nachrichten für Aktualisierungen zum Bestellstatus
Postbacks: Legen Sie fest, wie Daten an externe Systeme übermittelt werden, wenn sich der Bestellstatus ändert.
Alle Vorlagen verwenden die Jinja2-Templating-Sprache, die Ihnen vielseitige Möglichkeiten für die Datenverarbeitung, bedingte Logik und die Erstellung dynamischer Inhalte bietet.
Vorlagenarten, die Sie erstellen können
GelatoConnect unterstützt verschiedene Vorlagenarten für unterschiedliche Datenflussrichtungen:
Eingehende Datentemplates (Kunde → GelatoConnect)
Bestellübermittlung: Wandelt Kundendaten in das Format von GelatoConnect um
Stornierungsanfrage: Wandelt Kundenanfragen zur Stornierung in das Format von GelatoConnect um
Ausgehende Datentemplates (GelatoConnect → Kunde)
Antwort absenden: Formatiert die Rückmeldungen, die nach der Auftragserteilung gesendet werden
Antwort auf Stornierung: Formatiert die Rückmeldungen, die nach Stornierungsanfragen gesendet werden
Webhook: Erstellt JSON-Daten, um externe Systeme bei Änderungen des Bestellstatus zu benachrichtigen
E-Mail: Formatiert E-Mail-Benachrichtigungen für verschiedene Bestellereignisse
Es ist entscheidend, die Richtung des Datenflusses zu verstehen, wenn Sie Vorlagen erstellen. Sie bestimmt, welche Daten zur Verfügung stehen und wie diese aufgebaut sein sollten.
Schritt-für-Schritt-Anleitung zur Erstellung einer Vorlage
1. Gehen Sie zum Bereich Vorlagen
Melden Sie sich bei Ihrem GelatoConnect-Konto an
Gehen Sie zu Workflow > Auftragseingang > Vorlagen
Klicken Sie auf die Schaltfläche Vorlage hinzufügen, um mit der Erstellung einer neuen Vorlage zu beginnen.
2. Wählen Sie Ihren Vorlagentyp aus
Wählen Sie den Typ der Vorlage aus, den Sie erstellen möchten:
Für API-Integrationen benötigen Sie in der Regel die Vorlagen Order Submit Request, Submit Response und Cancel Response.
Für Benachrichtigungen wählen Sie Webhook oder E-Mail aus.
3. Definieren Sie das Format der Vorlage
Wählen Sie das Format für Ihre Vorlage aus:
JSON: Am häufigsten verwendet für API-Integrationen und Webhooks
XML: Wird für einige ältere Systeme verwendet
Nur Text: Wird meistens für E-Mail-Vorlagen verwendet
4. Erstellen Sie eine Beispiel-Eingabe
Um eine wirkungsvolle Vorlage zu erstellen, sollten Sie wissen, welche Daten Ihnen zur Verfügung stehen:
Klicken Sie auf die Schaltfläche Vorlage erstellen
Wählen Sie Beispiel-Eingabedaten hinzufügen, um Testdaten bereitzustellen.
Wählen Sie den passenden Ereignistyp aus dem Dropdown-Menü aus:
Bestellung eingegangen
Bestellung fehlgeschlagen
Bestellung storniert
Bestellung zurückgesendet
Bestellung produziert
Bestellung zugestellt
Bestellung versandt
Bestellung unterwegs
Das System füllt ein Beispiel mit typischen Daten für dieses Ereignis aus. So haben Sie eine praktische Vorlage, wenn Sie Ihr eigenes Template erstellen.
5. Erstellen Sie Ihren Template Mapper
Im Template Mapper legen Sie fest, wie Daten zwischen verschiedenen Formaten umgewandelt werden:
Im Bereich Template Mapper erstellen Sie Ihre Vorlage mit der Jinja2-Syntax.
Verwenden Sie doppelte geschweifte Klammern, um auf Referenzdaten aus dem Eingabepayload zuzugreifen:
####{{ variable }}Fügen Sie Formatierungsfilter mit dem Pipe-Symbol hinzu:
####{{ variable|js }}(derjs-Filter bereitet Zeichenfolgen für JSON korrekt auf)Verwenden Sie Steuerstrukturen wie
{% if %},{% for %}und{% set %}, um Bedingungen und Schleifen umzusetzen.
Worauf Sie bei der Ausrichtung von Vorlagen achten sollten
Der Inhalt Ihrer Vorlage hängt davon ab, ob Sie eingehende oder ausgehende Daten verarbeiten:
Für eingehende Datentemplates (Kunde → GelatoConnect):
Konzentrieren Sie sich darauf, Daten aus kundenspezifischen Formaten zu gewinnen
Ordnen Sie personalisierte Feldnamen den Standardfeldnamen von GelatoConnect zu
Prüfen und anpassen der Daten, damit sie den Anforderungen von GelatoConnect entsprechen
Gehen Sie flexibel auf besondere Formatierungs- oder Datenumwandlungsanforderungen ein
Für ausgehende Datentemplates (GelatoConnect → Kunde):
Strukturieren Sie die Daten so, wie es das System des Kunden erwartet.
Fügen Sie alle erforderlichen Felder für die Integration des Kunden hinzu
Formatieren Sie Daten wie Datumsangaben, Währungsbeträge und andere Informationen nach den Wünschen Ihrer Kundinnen und Kunden.
Fügen Sie alle kundenspezifischen Kennungen oder Verweise hinzu
Beispiel: Vorlage für Webhook bei eingegangener Bestellung
Hier finden Sie eine Beispielvorlage für einen "Order Received"-Webhook:
{ "event": "Bestellung eingegangen", "orderId": "####{{ orderId }}", "orderReferenceId": "####{{ orderReferenceId }}", "timestamp": "####{{ created }}", "status": "####{{ fulfillmentStatus }}", "items": [ {% for item in items %} { "itemReferenceId": "####{{ item.itemReferenceId }}", "status": "####{{ item.fulfillmentStatus }}" }{% if not loop.last %},{% endif %} {% endfor %} ], "message": "Die Bestellung ist bei uns eingegangen."}Diese Vorlage erstellt eine JSON-Struktur mit Bestelldetails und geht alle Artikel der Bestellung Schritt für Schritt durch.
6. Vorlage rendern und überprüfen
Nachdem Sie Ihre Vorlage erstellt haben:
Klicken Sie auf die Schaltfläche Render, um die Vorlage zu erstellen.
Überprüfen Sie das Ergebnis in der Vorschauansicht
Stellen Sie sicher, dass alle Daten korrekt formatiert sind und keine Syntaxfehler vorliegen.
Prüfen Sie, ob Felder fehlen oder falsch ausgefüllt sind
7. Testen Sie Ihre Vorlage
Testen ist entscheidend, damit Ihre Vorlage zuverlässig funktioniert:
Geben Sie Ihrem Test im Bereich Testvorlage einen Namen
Klicken Sie auf Test ausführen, um die Vorlage mit den Beispieldaten zu testen.
Überprüfen Sie, ob der Status als Bestanden angezeigt wird.
Überprüfen Sie das Ergebnis, um sicherzugehen, dass es Ihren Erwartungen entspricht.
8. Speichern Sie Ihre Vorlage
Sobald Sie mit der Vorlage zufrieden sind:
Geben Sie Ihrer Vorlage einen aussagekräftigen Namen
Klicken Sie auf Vorlage hinzufügen oder Änderungen speichern, um Ihre Auswahl zu sichern.
Die Vorlage steht Ihnen jetzt für Trigger und Workflow-Konfigurationen zur Verfügung.
Vorlagen mit Auslösern verwenden
Vorlagen werden am häufigsten mit Auslösern verwendet, um Benachrichtigungen automatisch zu versenden, sobald bestimmte Ereignisse eintreten:
1. Einen Auslöser erstellen
Gehen Sie zu Workflow > Auftragseingang > Auslöser
Klicken Sie auf Trigger hinzufügen
Wählen Sie den Kunden aus, für den dieser Auslöser gilt
Geben Sie Ihrem Trigger einen Namen (zum Beispiel "Benachrichtigung bei Auftragseingang")
Wählen Sie das Ereignis aus, das den Auslöser aktiviert (z. B. "Bestellung erhalten")
2. Liefermethode einrichten
Wählen Sie aus, wie Benachrichtigungen zugestellt werden sollen:
URL: Senden Sie einen Webhook an ein externes System
Geben Sie die Ziel-URL an
Wählen Sie die POST- oder GET-Methode aus
Wählen Sie das JSON- oder XML-Format aus
Konfigurieren Sie bei Bedarf die Wiederholungsoptionen
E-Mail: Senden Sie eine E-Mail-Benachrichtigung
Geben Sie die E-Mail-Adressen der Empfänger ein
Fügen Sie eine Betreffzeile hinzu
Geben Sie den Namen und die Adresse des Absenders an
3. Wählen Sie Ihre Vorlage aus
Wählen Sie im Dropdown-Menü Vorlage die Vorlage aus, die Sie zuvor erstellt haben.
Falls noch keine Vorlage existiert, können Sie direkt in der Trigger-Konfiguration eine erstellen – und zwar ganz einfach über die oben beschriebene Oberfläche.
Vorlagen direkt aus Auslösern erstellen
Damit es für Sie einfacher wird, können Sie Vorlagen auch direkt beim Einrichten von Auslösern erstellen:
Wenn Sie einen Auslöser erstellen, klicken Sie auf Vorlage erstellen, anstatt eine bestehende Vorlage auszuwählen.
Legen Sie das Format der Vorlage fest (JSON, XML oder Klartext)
Verwenden Sie den Vorlagen-Editor, um Ihre Vorlage wie oben beschrieben zu erstellen.
Speichern Sie die Vorlage, und sie wird automatisch für diesen Auslöser ausgewählt.
Diese Methode eignet sich gut, um schnell eine Vorlage zu erstellen, während Sie bereits einen Auslöser einrichten.
Vorlagen mit API-Endpunkten verbinden
Wenn Sie Bestellungen über die API einreichen, müssen Sie die Daten häufig zwischen Ihrem Format und dem Format von GelatoConnect umwandeln. Vorlagen übernehmen diese Umwandlung, aber Sie müssen Ihre Vorlage ausdrücklich mit dem API-Endpunkt verknüpfen, damit sie angewendet wird.
So verknüpfen Sie eine Vorlage mit einem Auftragseinreichungs-Endpunkt:
Gehen Sie zu Ihrer Connector-Liste und klicken Sie auf den Bearbeiten-Link neben dem Submit-Order-Endpunkt.
Gehen Sie auf der Seite für die Endpunkt-Konfiguration zum Abschnitt Endpunktvorlage.
Wählen Sie Ihre Vorlage für die Auftragsübermittlung im Dropdown-Menü aus
Klicken Sie oben rechts auf der Seite auf die Schaltfläche Endpunkt festlegen.
Klicken Sie oben rechts auf Änderungen speichern, um Ihre Einstellungen zu übernehmen.
Nachdem Sie diese Schritte abgeschlossen haben, werden alle an diesen Endpunkt gesendeten Bestellungen mithilfe Ihrer Vorlage umgewandelt, bevor sie verarbeitet werden. So wird sichergestellt, dass das Format Ihres Systems korrekt in das von GelatoConnect erwartete Format übertragen wird.
Ohne diese Konfiguration wird Ihre Vorlage nicht angewendet, selbst wenn sie existiert und korrekt gestaltet ist. Das kann dazu führen, dass Bestellungen nicht geprüft werden können, wenn Ihr Datenformat nicht genau den Anforderungen von GelatoConnect entspricht.
Fortgeschrittene Vorlagen-Techniken
Verwendung von Nachschlagefunktionen
Lookups sind besonders hilfreich, wenn Sie Daten zwischen zwei Systemen in beide Richtungen abgleichen möchten. Je nach Richtung der Vorlage funktionieren sie unterschiedlich:
Für eingehende Vorlagen (Kunde → GelatoConnect):
Ordnen Sie kundenspezifische Werte den standardisierten Werten von GelatoConnect zu:
{% set shipMethod = lookups({"shipping_code": order.shipping.method}, strict=False, default="normal") %} "shipmentMethodUid": ####{{ shipMethod|js }},Für ausgehende Vorlagen (GelatoConnect → Kunde):
Wandeln Sie die internen Werte von GelatoConnect in die von Ihren Kunden erwarteten Formate um:
{% set customerShippingCode = lookups({"gelatoShipMethod": shipment.shipmentMethodUid}, strict=False, default=shipment.shipmentMethodUid) %} "shipping_method": ####{{ customerShippingCode|js }},Bedingte Logik
Verwenden Sie Bedingungen, um Daten je nach Situation unterschiedlich einzubinden oder zu formatieren:
{% if item.fulfillmentStatus == "shipped" %} "trackingNumber": "####{{ item.trackingCode }}", "trackingUrl": "####{{ item.trackingUrl }}",{% endif %}Variablenzuweisung
Erstellen Sie Variablen, um komplizierte Ausdrücke einfacher zu machen:
{% set fullName = customer.firstName + " " + customer.lastName %} "recipientName": "####{{ fullName }}",Schleifen mit komplexen Objekten
Verschachtelte Datenstrukturen einfach durchschauen:
"Artikel": [ {% for item in items %} { "sku": "####{{ item.sku }}", "Menge": ####{{ item.quantity }}, "Optionen": [ {% for option in item.options %} { "name": "####{{ option.name }}", "value": "####{{ option.value }}" }{% if not loop.last %},{% endif %} {% endfor %} ] }{% if not loop.last %},{% endif %} {% endfor %}]Best Practices für Vorlagen
Richtungsbasierte Namenskonventionen
Verwenden Sie klare, beschreibende Namen, die sowohl den Zweck als auch die Richtung des Datenflusses deutlich machen.
Für eingehende Vorlagen: Fügen Sie Präfixe wie "IN_" oder Suffixe wie "_Request" hinzu.
Für ausgehende Vorlagen: Verwenden Sie Präfixe wie "OUT_" oder Suffixe wie "_Response" oder "_Notification".
Fügen Sie den Kundennamen für kundenspezifische Vorlagen ein
Verwenden Sie einheitliche Namensmuster, damit Sie Vorlagen leicht wiederfinden können.
Fehlerbehandlung
Legen Sie Standardwerte fest, um Fehler durch fehlende Werte zu vermeiden.
Verwenden Sie den
default-Filter für fehlende Werte:####{{ variable|default('N/A') }}Verwenden Sie
try/except-Blöcke, um auf mögliche Stolpersteine im Code vorbereitet zu sein.
Wartung
Fügen Sie Kommentare hinzu, um komplexe Logik zu erklären:
{# Dies behandelt einen Sonderfall für internationale Bestellungen #}Halten Sie Vorlagen flexibel und auf einen bestimmten Zweck ausgerichtet.
Aktualisieren Sie Vorlagen, wenn sich Datenstrukturen oder Anforderungen ändern
Testlauf
Testen Sie mit unterschiedlichen Datenszenarien, auch mit ungewöhnlichen Fällen
Prüfen Sie Vorlagen nach Möglichkeit mit echten Produktionsdaten
Erstellen Sie umfassende Tests für wichtige Vorlagen
Vorlageprobleme beheben
Häufige Probleme und wie Sie sie lösen
Problem | Mögliche Ursache | Lösung |
Syntaxfehler | Nicht zusammenpassende Klammern oder Anführungszeichen | Prüfen Sie die Vorlagensyntax sorgfältig und stellen Sie sicher, dass jede öffnende Markierung auch eine passende schließende Markierung hat. |
Fehlende Daten | Verweise auf Felder, die es gar nicht gibt | Prüfen Sie die Feldnamen anhand der Eingabedaten und fügen Sie Standardwerte für optionale Felder hinzu. |
Formatierungsprobleme | Falsche Filtereinstellung | Stellen Sie sicher, dass Sie Filter wie |
Vorlage wurde nicht übernommen | Vorlage ist nicht mit einem Auslöser verbunden | Überprüfen Sie die Auslöserkonfiguration und die Auswahl der Vorlage |
Fehler beim Zugriff auf verschachtelte Daten | Falscher Pfad zu verschachtelten Eigenschaften | Überprüfen Sie die Datenstruktur und passen Sie die Eigenschaftenpfade entsprechend an |
Fehler bei der Feldzuordnung | Falsche Feldnamen für eingehende oder ausgehende Daten | Bei eingehenden Vorlagen prüfen Sie die Kundendatenfelder; bei ausgehenden Vorlagen achten Sie auf das erwartete Antwortformat. |
Probleme bei der Datenumwandlung | Nicht kompatible Datenformate | Achten Sie darauf, dass Daten wie Datumsangaben, Zahlen und andere Werte korrekt zwischen den Systemen umgewandelt werden. |
Tipps zum Beheben von Fehlern
Verwenden Sie während der Entwicklung regelmäßig die Rendern-Schaltfläche, um Fehler frühzeitig zu erkennen.
Fügen Sie vorübergehend eine Debug-Ausgabe hinzu, um die Werte der Variablen zu überprüfen.
Überprüfen Sie die Feldnamen auf Tippfehler – das ist eine häufige Fehlerquelle.
Denken Sie daran, dass Jinja2 bei der Verwendung von Variablen zwischen Groß- und Kleinschreibung unterscheidet.