Wat zijn template mappers?

Template mappers in GelatoConnect zijn krachtige tools die gegevens omzetten van het formaat van jouw systeem naar het formaat van GelatoConnect. Zie ze als vertalers die ervoor zorgen dat informatie moeiteloos tussen verschillende systemen stroomt, hoe die systemen hun data ook hebben opgebouwd.

Of je nu bestellingen doorstuurt naar GelatoConnect of updates ontvangt over de status van je bestelling, met template mappers kun je gegevens omzetten naar het juiste formaat zonder dat je je bestaande systemen hoeft aan te passen.

Waarom zou je template mappers gebruiken?

Sjabloonmappers lossen verschillende veelvoorkomende integratieproblemen op:

Verschillende gegevensstructuren: jouw systeem en GelatoConnect kunnen dezelfde informatie op een andere manier ordenen.
Verschillen in veldnamen: Jouw systeem noemt een verzendadres misschien "delivery_address", terwijl GelatoConnect "shippingAddress" gebruikt.
Formaatconversies: Het kan nodig zijn om gegevensformaten te converteren, zoals het wijzigen van datumnotaties of het omzetten van maateenheden.
Selectief veldtoewijzing: Soms wil je alleen bepaalde velden uit je gegevens meesturen naar GelatoConnect.
Voorwaardelijke logica: Soms moet je verschillende regels toepassen, bijvoorbeeld afhankelijk van het soort bestelling of het land van bestemming.

Zo werken template mappers

GelatoConnect gebruikt de Jinja2-sjabloontaal voor zijn template mappers. Deze krachtige en flexibele taal geeft je de mogelijkheid om:

Waarden ophalen: Haal gegevens uit je invoerformaat
Gegevens transformeren: Pas functies en logica toe om de gegevens aan te passen
Output maken: Zet het eindresultaat in het formaat dat GelatoConnect verwacht

Een sjabloonmapper neemt een invoer (jouw gegevens) en produceert een uitvoer (GelatoConnect-compatibele gegevens) op basis van een reeks transformatieregels die je definieert.

Template mapper componenten

Een standaard template mapper in GelatoConnect bestaat uit deze onderdelen:

1. Gegevens invoeren

Dit is de brondata die je wilt omtoveren. Dat kan bijvoorbeeld zijn:

Bestelgegevens van je e-commercesysteem
Klantgegevens uit je CRM
Productdetails uit je catalogus

2. Sjabloondefinitie

Hier bepaal je hoe je de invoergegevens wilt omzetten. Met Jinja2-syntax geef je het volgende aan:

Welke velden wil je uit de invoer halen
Toe te passen transformaties
De opbouw van het resultaat

3. Uitvoerformaat

Het resultaat van het verwerken van de template, meestal in JSON-formaat dat voldoet aan de API-eisen van GelatoConnect.

Eenvoudig voorbeeld van een template mapper

Laten we eens kijken naar een simpel voorbeeld waarin we een bestelling omzetten van het formaat van jouw systeem naar het formaat van GelatoConnect:

De bestelgegevens van je systeem:

{"order_id": "ORD-12345","klant": {"name": "John Doe",\"email\": \"[email protected]\"},""levering": {"street": "123 hoofdstraat","city": "New York","zip": "10001","country": "VS"},"\"products\": [{"sku": "POSTER-A4-MATTE","qty": 2,"image_url": "https://example.com/images/poster1.jpg"}]}

Template mapper:

{"orderReferenceId": "####{{ order_id }}",\"orderType\": \"order\",\"valuta\": \"USD\",\"verzendadres\": {"firstName": "####{{ customer.name.split(' ')[0] }}","lastName": "####{{ customer.name.split(' ')[1] }}","addressLine1": "####{{ delivery.street }}",\"city\": \"####{{ delivery.city }}\","postCode": "####{{ delivery.zip }}","country": "####{{ delivery.country }}","email": "####{{ customer.email }}",\"telefoon\": \"+1234567890\"},"\"items\": [{% for product in products %}{"itemReferenceId": "####{{ order_id }}-####{{ loop.index }}","productUid": "####{{ lookups({'sku': product.sku}, strict=False, default='') }}","aantal": ####{{ product.qty }},\"bestanden\": [{"type": "standaard","url": "####{{ product.image_url }}"}]}{% if not loop.last %},{% endif %}{% endfor %}]}

Resulterende GelatoConnect-compatibele bestelling:

{"orderReferenceId": "ORD-12345",\"orderType\": \"order\",\"valuta\": \"USD\",\"verzendadres\": {\"firstName\": \"John\",\"lastName\": \"Doe\","addressLine1": "123 hoofdstraat","city": "New York","postCode": "10001",\"country\": \"US\",\"email\": \"[email protected]\","telefoon": "+1234567890"},"\"items\": [{"itemReferenceId": "ORD-12345-1","productUid": "flat_product_pf_a4_pt_200-g-m2-ongecoat_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",\"aantal\": 2,\"bestanden\": [{"type": "standaard","url": "https://example.com/images/poster1.jpg"}]}]}

Belangrijkste functies van de template mapper

Variabele invoeging

Gebruik dubbele accolades om waarden uit de invoergegevens in te voegen:

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

Filters

Pas filters toe op waarden (aangegeven met het pijpteken):

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

Veelvoorkomende filters zijn onder andere:

upper: Zet om naar hoofdletters
lower: Omzetten naar kleine letters
title: Begin elk woord met een hoofdletter
trim: Verwijder witruimte van begin en eind
default: Geef een standaardwaarde op als de variabele niet is gedefinieerd
js: Zorg dat de waarde goed is opgemaakt voor JSON

Besturingsstructuren

Gebruik logica om content alleen te tonen als het nodig is, of om door lijsten heen te gaan:

{% for product in products %}// Verwerk elk product{% endfor %}{% if customer.type == "business" %}// Voeg bedrijfsspecifieke velden toe{% anders %}// Voeg velden voor individuele klanten toe{% endif %}

Opzoeken

Gebruik de functie lookups() om waarden tussen systemen te koppelen, bijvoorbeeld om je product-SKU's om te zetten naar GelatoConnect product-UID's:

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

De zoekfunctie werkt pas als je in GelatoConnect lookup-tabellen instelt. Daarmee koppel je de waarden uit je eigen systeem aan die van GelatoConnect.

Sjablonen mappers maken en testen

GelatoConnect biedt een gebruiksvriendelijke omgeving om sjabloonmappers te maken en te testen:

Maak een template: Ga naar het gedeelte Templates en maak een nieuwe template aan.
Kies sjabloontype: Selecteer het juiste sjabloontype (bijv. verzoek voor orderindiening, orderbevestiging).
Stel je template op: Schrijf je Jinja2-template in de editor.
Testen met voorbeeldgegevens: Vul wat voorbeeldgegevens in en bekijk direct het resultaat van je template.
Testen en bijschaven: Pas je template aan als het resultaat niet helemaal is wat je wilt.
Opslaan en activeren: Als je sjabloon goed werkt, sla je hem op zodat je hem kunt gebruiken in je integratie.

Veelvoorkomende toepassingen voor template mappers

1. Orderverzend mapping

Zet bestellingen om van het formaat van jouw systeem naar het API-formaat van GelatoConnect.

2. Statusupdate meldingen

Maak sjablonen voor verschillende orderstatussen (ontvangen, verzonden, geleverd) zodat je systemen altijd op de hoogte zijn.

3. Gepersonaliseerde Webhooks

Zorg dat je gegevens klaar zijn om te delen met andere systemen zodra er iets belangrijks gebeurt.

4. Gegevens normaliseren

Zorg dat je gegevens uit verschillende bronnen op één lijn brengt voordat je ze verwerkt.

Best practices voor template mappers

Begin eenvoudig: Start met een simpele template en voeg stap voor stap meer toe.
Gebruik opmerkingen: Voeg opmerkingen toe om lastige aanpassingen uit te leggen.
```
jinja{# Dit haalt de voornaam en achternaam uit de volledige naam #}
```
Omgaan met ontbrekende gegevens: Zorg er altijd voor dat je standaardwaarden gebruikt of controleert of optionele velden zijn ingevuld.
```
jinja"additionalInfo": "####{{ customer.notes | default('') }}"
```
Test uitzonderlijke gevallen: Zorg ervoor dat je sjablonen ook werken als er onverwachte invoer of waarden zijn.
Gebruik lookups voor ingewikkelde koppelingen: In plaats van alles handmatig in je template te zetten, kun je beter de lookups-functie gebruiken.
Houd sjablonen overzichtelijk: Maak aparte sjablonen voor verschillende doelen in plaats van één ingewikkeld sjabloon.
Uitvoer valideren: Controleer altijd of de uitvoer van je sjabloon voldoet aan de API-vereisten van GelatoConnect.

Geavanceerde technieken voor het koppelen van sjablonen

Naarmate je meer vertrouwd raakt met template mappers, kun je de geavanceerde functies gaan gebruiken:

Macro's

Definieer herbruikbare blokken sjablooncode:

{% macro format_address(address) %}{\"addressLine1\": \"####{{ address.street }}\","city": "####{{ address.city }}",\"postCode\": \"####{{ address.zip }}\","country": "####{{ address.country }}"}{% endmacro %}// Gebruik het dan als volgt:\"verzendadres\": ####{{ format_address(delivery) }}

Instellingen

Maak variabelen aan in je template:

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

Gepersonaliseerde filters en functies

GelatoConnect ondersteunt verschillende gepersonaliseerde filters en functies naast standaard Jinja2:

lookups(): Voor het in kaart brengen tussen waardesystemen
js: Voor correcte JSON-escaping
Verschillende datumformatteringsfuncties

Wil je meer weten?

Nu je de basisprincipes van Template Mappers in GelatoConnect begrijpt, ben je klaar om:

Meer informatie over het maken van sjablonen voor orderverwerking
Verken Jinja2 sjabloonvoorbeelden
Stel postback triggers in die je sjablonen gebruiken

[Orderintake - GCW] Introductie tot Template Mappers