Zum Hauptinhalt springen

[Auftragseingang – GCW] Einführung in Template Mappers

Juliana Maciel Maruri da Cunha avatar
Verfasst von Juliana Maciel Maruri da Cunha
Vor über 3 Wochen aktualisiert

Was sind Template-Mappers?

Vorlagen-Mapper in GelatoConnect sind leistungsstarke Werkzeuge, die Daten zwischen dem Format Ihres Systems und dem von GelatoConnect umwandeln. Sie funktionieren wie Übersetzer und sorgen dafür, dass Informationen reibungslos zwischen verschiedenen Systemen fließen – ganz gleich, wie unterschiedlich die Daten jeweils aufgebaut sind.

Egal, ob Sie Bestellungen an GelatoConnect übermitteln oder Updates zu Statusänderungen erhalten – mit Template-Mapping können Sie Datenformate flexibel umwandeln, ohne Ihre bestehenden Systeme anpassen zu müssen.

Warum sind Vorlagen-Mapping-Tools sinnvoll?

Vorlagen-Mapping-Tools lösen mehrere typische Integrationsprobleme:

  1. Unterschiedliche Datenstrukturen: Ihr System und GelatoConnect können dieselben Informationen auf verschiedene Weise organisieren.

  2. Unterschiede bei der Feldbenennung: In Ihrem System heißt die Versandadresse vielleicht "delivery_address", während GelatoConnect "shippingAddress" verwendet.

  3. Formatkonvertierungen: Es kann sein, dass Sie Datenformate anpassen müssen, zum Beispiel das Datumsformat ändern oder Maßeinheiten umrechnen.

  4. Selektive Feldzuordnung: Vielleicht möchten Sie nur bestimmte Felder aus Ihren Daten auswählen, wenn Sie sie an GelatoConnect senden.

  5. Bedingte Logik: Je nach Situation, zum Beispiel bei der Art der Bestellung oder dem Zielland, können unterschiedliche Zuordnungsregeln erforderlich sein.

So funktionieren Template Mappers

GelatoConnect verwendet die Jinja2-Templating-Sprache für seine Vorlagen-Mappings. Diese vielseitige und leistungsstarke Sprache ermöglicht es Ihnen:

  1. Werte extrahieren: Holen Sie sich die Daten aus Ihrem Eingabeformat

  2. Daten umwandeln: Wenden Sie Funktionen und Logik an, um die Daten zu verändern

  3. Ergebnis erstellen: Stellen Sie das finale Ergebnis im gewünschten Format von GelatoConnect zusammen

Ein Vorlagen-Mapping-Tool nimmt Ihre Daten als Eingabe und erstellt daraus eine Ausgabe (GelatoConnect-kompatible Daten), basierend auf den von Ihnen festgelegten Umwandlungsregeln.

Komponenten für die Vorlagenzuordnung

Ein typischer Vorlagen-Mapper in GelatoConnect besteht aus diesen Komponenten:

1. Eingabedaten

Dies sind die Ausgangsdaten, die Sie umwandeln möchten. Das kann zum Beispiel Folgendes sein:

  • Bestelldaten aus Ihrem E-Commerce-System

  • Kundendaten aus Ihrem CRM

  • Produktdetails aus Ihrem Katalog

2. Definition der Vorlage

Hier legen Sie fest, wie die Eingabedaten umgewandelt werden. Mit der Jinja2-Syntax bestimmen Sie:

  • Welche Felder sollen aus den Eingabedaten übernommen werden?

  • Gibt es Anpassungen, die vorgenommen werden sollen?

  • Der Aufbau des Ergebnisses

3. Ausgabeformat

Das Ergebnis der Vorlagenverarbeitung, in der Regel im JSON-Format, das den API-Anforderungen von GelatoConnect entspricht.

Einfaches Beispiel für die Zuordnung von Vorlagen

Schauen wir uns ein einfaches Beispiel an, das eine Bestellung aus dem Format Ihres Systems in das Format von GelatoConnect umwandelt:

Die Bestelldaten Ihres Systems:

{"order_id": "ORD-12345","Kunde": {"name": "John Doe","email": "[email protected]"},"delivery": {"street": "Hauptstraße 123","city": "New York","zip": "10001","country": "US"},"products": [{"Artikelnummer": "POSTER-A4-MATTE","Menge": 2,"image_url": "https://example.com/images/poster1.jpg"}]}

Vorlagen-Zuordnung:

{"orderReferenceId": "####{{ order_id }}","orderType": "Bestellung","currency": "USD","shippingAddress": {"firstName": "####{{ customer.name.split(' ')[0] }}","lastName": "####{{ customer.name.split(' ')[1] }}","addressLine1": "####{{ delivery.street }}","city": "####{{ delivery.city }}","postleitzahl": "####{{ delivery.zip }}","country": "####{{ delivery.country }}","email": "####{{ customer.email }}","phone": "+1234567890"},"Artikel": [{% for product in products %}{"itemReferenceId": "####{{ order_id }}-####{{ loop.index }}","productUid": "####{{ lookups({'Artikelnummer': product.sku}, strict=False, default='') }}","Menge": ####{{ product.qty }},"Dateien": [{"type": "Standard","url": "####{{ product.image_url }}"}]}{% if not loop.last %},{% endif %}{% endfor %}]}

So sieht eine Bestellung aus, die mit GelatoConnect kompatibel ist:

{"orderReferenceId": "ORD-12345","orderType": "Bestellung","currency": "USD","shippingAddress": {"firstName": "John","lastName": "Doe","addressLine1": "123 Hauptstraße","city": "New York","postCode": "10001","country": "US","email": "[email protected]","phone": "+1234567890"},"Artikel": [{"itemReferenceId": "ORD-12345-1","productUid": "flat_product_pf_a4_pt_200-g-m2-unbeschichtet_cl_4-0_ct_none_prt_none_sft_none_set_none_hor","Menge": 2,"Dateien": [{"type": "Standard","url": "https://example.com/images/poster1.jpg"}]}]}

Wichtige Funktionen des Vorlagen-Mappers

Variable Interpolation

Verwenden Sie doppelte geschweifte Klammern, um Werte aus den Eingabedaten einzufügen:

jinja"orderReferenceId": "####{{ order_id }}"

Filter

Wenden Sie Filter an, um Werte zu verändern (erkennbar am senkrechten Strich):

jinja"firstName": "####{{ customer.name | title }}"

Zu den gängigen Filtern gehören:

  • upper: In Großbuchstaben umwandeln

  • kleinbuchstaben: In Kleinbuchstaben umwandeln

  • Titel: Schreiben Sie den ersten Buchstaben jedes Wortes groß

  • Rand: Entfernt Leerzeichen am Anfang und Ende

  • default: Geben Sie einen Standardwert an, falls die Variable nicht definiert ist.

  • js: Stellen Sie sicher, dass der Wert korrekt für JSON formatiert ist.

Kontrollstrukturen

Nutzen Sie Logik, um Inhalte gezielt einzublenden oder über Listen zu gehen:

{% for product in products %}// Jeden Artikel einzeln bearbeiten{% endfor %}{% if customer.type == "business" %}// Fügen Sie geschäftsspezifische Felder hinzu{% else %}// Individuelle Kundenfelder einbeziehen{% endif %}

Suchvorgänge

Verwenden Sie die Funktion lookups(), um Werte zwischen verschiedenen Systemen zuzuordnen – zum Beispiel, um Ihre Produkt-SKUs in GelatoConnect-Produkt-UIDs umzuwandeln:

jinja"productUid": "####{{ lookups({'Artikelnummer': product.sku}, strict=False, default='') }}"

Die Nachschlagefunktion erfordert, dass Sie in GelatoConnect Nachschlagetabellen einrichten, die die Werte Ihres Systems den Werten von GelatoConnect zuordnen.

Vorlagen-Mapping erstellen und testen

GelatoConnect bietet Ihnen eine benutzerfreundliche Oberfläche, mit der Sie Vorlagen-Mappings ganz einfach erstellen und testen können:

  1. Vorlage erstellen: Gehen Sie zum Bereich „Vorlagen“ und erstellen Sie eine neue Vorlage.

  2. Vorlagentyp auswählen: Wählen Sie den passenden Vorlagentyp aus (z. B. Bestellübermittlung oder Benachrichtigung über den Bestelleingang).

  3. Vorlage festlegen: Schreiben Sie Ihre Jinja2-Vorlage im Editor.

  4. Test mit Beispieldaten: Geben Sie Beispieldaten ein und lassen Sie die Vorlage anzeigen, um das Ergebnis zu sehen.

  5. Feinabstimmung und Optimierung: Passen Sie Ihre Vorlage nach Bedarf an, sobald Sie das Ergebnis sehen.

  6. Speichern und aktivieren: Sobald Ihre Vorlage wie gewünscht funktioniert, speichern Sie sie, damit Sie sie in Ihrer Integration verwenden können.

Typische Anwendungsfälle für Vorlagen-Mapping

1. Zuordnung der Bestellübermittlung

Wandeln Sie Bestellungen aus dem Format Ihres Systems in das API-Format von GelatoConnect um.

2. Benachrichtigungen über Statusaktualisierungen

Erstellen Sie Vorlagen für verschiedene Bestellstatus-Ereignisse (eingegangen, versendet, zugestellt), um Ihre Systeme zu benachrichtigen.

3. Personalisierte Webhooks

Daten so aufbereiten, dass sie bei bestimmten Ereignissen an Drittsysteme gesendet werden können.

4. Daten-Normalisierung

Standardisieren Sie Daten aus verschiedenen Quellen, bevor Sie mit der Verarbeitung beginnen.

Best Practices für Template-Mappers

  1. Einfach anfangen: Starten Sie mit einer einfachen Vorlage und fügen Sie nach und nach mehr Details hinzu.

  2. Kommentare nutzen: Fügen Sie Kommentare hinzu, um komplizierte Abläufe verständlich zu machen.

    jinja{# Dies extrahiert den Vor- und Nachnamen aus dem vollständigen Namen #}

  3. Fehlende Daten geschickt handhaben: Geben Sie immer Standardwerte an oder prüfen Sie optionale Felder.

    jinja"additionalInfo": "####{{ customer.notes | default('') }}"

  4. Grenzfälle testen: Stellen Sie sicher, dass Ihre Vorlagen auch mit ungewöhnlichen Eingaben oder Werten umgehen können.

  5. Verwenden Sie Lookups für komplexe Zuordnungen: Statt die Zuordnungen direkt in Ihrer Vorlage festzulegen, nutzen Sie die Lookup-Funktion.

  6. Vorlagen gezielt einsetzen: Erstellen Sie für jeden Zweck eine eigene Vorlage, statt alles in eine komplizierte Vorlage zu packen.

  7. Ausgabe überprüfen: Stellen Sie immer sicher, dass Ihr Vorlagenergebnis den API-Anforderungen von GelatoConnect entspricht.

Fortgeschrittene Techniken für die Arbeit mit Vorlagen-Mapping

Sobald Sie sich mit den Vorlagen-Mapping-Tools vertraut gemacht haben, können Sie auch die erweiterten Funktionen nutzen:

Makros

Definieren Sie wiederverwendbare Bausteine für Vorlagen-Code:

{% macro format_address(address) %}{"addressLine1": "####{{ address.street }}","city": "####{{ address.city }}","postCode": "####{{ address.zip }}","country": "####{{ address.country }}"}{% endmacro %}// Und so verwenden Sie es:"shippingAddress": ####{{ format_address(delivery) }}

Aussagen festlegen

Erstellen Sie Variablen in Ihrer Vorlage:

{% set full_name = customer.firstName + ' ' + customer.lastName %}"recipientName": "####{{ full_name }}"

Personalisierte Filter und Funktionen

GelatoConnect unterstützt mehrere personalisierte Filter und Funktionen, die über den Standardumfang von Jinja2 hinausgehen:

  • lookups(): Zum Abgleichen verschiedener Wertsysteme

  • js: Für korrektes JSON-Escaping

  • Verschiedene Funktionen zur Datumsformatierung

Möchtest du mehr erfahren?

Jetzt, da Sie die Grundlagen der Template Mappers in GelatoConnect verstanden haben, sind Sie bereit für Folgendes:

  1. Mehr erfahren über das Erstellen von Vorlagen für die Auftragserfassung

  2. Entdecken Sie Jinja2 Vorlagenbeispiele

  3. Richten Sie Postback-Trigger ein, die Ihre Vorlagen verwenden

Verwandte Artikel
[Auftragseingang – GCW] So richten Sie Nachschlagefunktionen ein
[Auftragseingang – GCW] Beispiele für Template Mapper
[Auftragseingang – GCW] Arbeiten mit Order-API-Endpunkten
[Auftragseingang – GCW] Verwendung von Kundenprodukten vs. ProductUID bei API-Bestellungen
[Auftragseingang – GCW] Vorlagen für den Auftragseingang erstellen
Hat dies deine Frage beantwortet?