Spring videre til hovedindholdet

[Ordreindtag - GCW] Introduktion til Template Mappers

Juliana Maciel Maruri da Cunha avatar
Skrevet af Juliana Maciel Maruri da Cunha
Opdateret for over 3 uger siden

Hvad er template mappers?

Template mappere i GelatoConnect er smarte værktøjer, der omdanner data mellem dit systems format og GelatoConnects format. De fungerer som oversættere og sørger for, at information glider let mellem forskellige systemer – uanset hvordan de hver især organiserer deres data.

Uanset om du sender ordrer til GelatoConnect eller får besked om ændringer i ordrestatus, gør template mappers det nemt at omdanne dataformater – helt uden at du behøver ændre på dine nuværende systemer.

Hvorfor bruge template mappers?

Template-mappere løser flere typiske integrationsudfordringer:

  1. Forskellige datastrukturer: Dit system og GelatoConnect kan have hver sin måde at holde styr på de samme oplysninger på.

  2. Forskelle i feltnavne: Dit system kalder måske en leveringsadresse for "delivery_address", mens GelatoConnect bruger "shippingAddress".

  3. Formatkonverteringer: Du kan få brug for at ændre dataformater, for eksempel ved at lave datoer om til et andet format eller ændre måleenheder.

  4. Selektiv feltmapping: Du vil måske kun tage bestemte felter med fra dine data, når du sender dem til GelatoConnect.

  5. Betinget logik: Du kan have brug for at bruge forskellige mapping-regler alt efter situationen – for eksempel hvilken type ordre det er, eller hvilket land ordren skal sendes til.

Sådan fungerer Template Mappers

GelatoConnect bruger Jinja2-skabelonsproget til sine template-mappere. Det her stærke og fleksible sprog giver dig mulighed for at:

  1. Træk værdier ud: Hent data fra dit inputformat

  2. Forvandl data: Brug funktioner og logik til at ændre dine data

  3. Byg resultatet: Lav det endelige output i det format, GelatoConnect forventer

En template mapper tager dine data og laver dem om til GelatoConnect-kompatible data ud fra de regler, du selv sætter op.

Template Mapper-komponenter

En typisk template mapper i GelatoConnect består af disse elementer:

1. Indtast data

Dette er de data, du gerne vil ændre. Det kan for eksempel være:

  • Hent ordredata fra dit e-commerce system

  • Kundeinformation fra dit CRM

  • Produktdetaljer fra dit katalog

2. Skabelondefinition

Her kan du bestemme, hvordan inputdata skal ændres. Med Jinja2-syntaks angiver du:

  • Hvilke felter skal vi tage med fra inputtet

  • Eventuelle ændringer, der skal laves

  • Sådan er outputtet bygget op

3. Outputformat

Resultatet af skabelonbehandlingen, som oftest er i JSON-format og opfylder GelatoConnects API-krav.

Eksempel på enkel skabelon-mapper

Lad os tage et kig på et enkelt eksempel, hvor vi omdanner en ordre fra dit systems format til GelatoConnects format:

Dine ordredetaljer fra systemet:

{"order_id": "ORD-12345","customer": {"name": "John Doe","email": "[email protected]"},"delivery": {"street": "123 Main St","city": "New York","zip": "10001","country": "US"},"produkter": [{"sku": "PLAKAT-A4-MATTE","qty": 2,"image_url": "https://example.com/images/poster1.jpg"}]}

Skabelon-mapper:

{"orderReferenceId": "####{{ order_id }}","orderType": "ordre","currency": "USD","shippingAddress": {"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 }}","phone": "+1234567890"},"items": [{% for product in products %}{"itemReferenceId": "####{{ order_id }}-####{{ loop.index }}","productUid": "####{{ lookups({'VARENUMMER': product.sku}, strict=False, default='') }}","quantity": ####{{ product.qty }},"filer": [{"type": "default","url": "####{{ product.image_url }}"}]}{% if not loop.last %},{% endif %}{% endfor %}]}

Resulterende ordre, der er kompatibel med GelatoConnect:

{"orderReferenceId": "ORD-12345","orderType": "ordre","currency": "USD","shippingAddress": {"firstName": "John","lastName": "Doe","addressLine1": "123 Main St","city": "New York","postCode": "10001","country": "US","email": "[email protected]","phone": "+1234567890"},"items": [{"itemReferenceId": "ORD-12345-1","productUid": "flat_product_pf_a4_pt_200-g/m²-ubestrøget_cl_4-0_ct_none_prt_none_sft_none_set_none_hor","antal": 2,"filer": [{"type": "default","url": "https://example.com/images/poster1.jpg"}]}]}

Vigtige funktioner i Template Mapper

Variabelindsættelse

Brug dobbelte krøllede parenteser for at indsætte værdier fra inputdata:

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

Filtre

Brug filtre til at ændre værdier (markeret med lodret streg):

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

Almindelige filtre er for eksempel:

  • upper: Lav om til store bogstaver

  • lower: Konverter til små bogstaver

  • title: Skriv det første bogstav i hvert ord med stort

  • trim: Fjern mellemrum i starten og slutningen

  • default: Giv en standardværdi, hvis variablen ikke er defineret

  • js: Sørg for, at værdien er korrekt formateret til JSON

Kontrolstrukturer

Brug logik til at vise indhold efter behov eller gentage over lister:

{% for product in products %}// Gennemgå hvert produkt{% endfor %}{% if customer.type == "business" %}// Inkludér felter, der er specifikke for din forretning{% else %}// Inkludér individuelle kundefelter{% endif %}

Opslag

Brug lookups()-funktionen til at matche værdier mellem systemer, for eksempel når du vil omdanne dine produkt-SKU’er til GelatoConnect produkt-UID’er:

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

Opslagsfunktionen kræver, at du opretter opslagstabeller i GelatoConnect, som matcher værdierne fra dit system med værdierne i GelatoConnect.

Opret og test skabelon-mappere

GelatoConnect giver dig en brugervenlig platform, hvor du nemt kan oprette og teste skabelon-mappere:

  1. Opret en skabelon: Gå til skabelon-sektionen og opret en ny skabelon.

  2. Vælg skabelontype: Vælg den skabelontype, der passer bedst (f.eks. Ordreafsendelse, Ordrebekræftelse).

  3. Definér skabelonen: Skriv din Jinja2-skabelon i editoren.

  4. Test med eksempler: Giv nogle prøveinput og se, hvordan skabelonen ser ud i praksis.

  5. Test og finpuds: Tilpas din skabelon, så den passer, når du ser resultatet.

  6. Gem og aktiver: Når din skabelon fungerer, som den skal, kan du gemme den og bruge den i din integration.

Typiske måder at bruge Template Mappers på

1. Kortlægning af ordreafgivelse

Omform dine ordrer fra dit systems format til GelatoConnects API-format.

2. Statusopdateringsnotifikationer

Lav skabeloner til forskellige ordrestatusser (modtaget, afsendt, leveret), så dine systemer får besked.

3. Tilpassede Webhooks

Formater data, så det er klar til at blive sendt til tredjepartssystemer, når bestemte begivenheder sker.

4. Datatilpasning

Standardisér data fra flere kilder, før du går i gang med behandlingen.

Best practice for skabelon-mappere

  1. Start simpelt: Begynd med en grundskabelon og byg stille og roligt videre derfra.

  2. Brug kommentarer: Tilføj kommentarer for at gøre svære ændringer nemmere at forstå.

    jinja{# Dette udtrækker fornavn og efternavn fra det fulde navn #}

  3. Håndter manglende data: Sørg altid for at have standardværdier eller tjek for valgfrie felter.

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

  4. Test grænsetilfælde: Sørg for, at dine skabeloner kan håndtere uventede input eller værdier.

  5. Brug opslag til komplekse sammenhænge: I stedet for at kode sammenhænge direkte ind i din skabelon, kan du bruge opslag-funktionen.

  6. Hold skabelonerne enkle: Lav forskellige skabeloner til forskellige formål i stedet for én stor og rodet skabelon.

  7. Tjek output: Sørg altid for, at dit skabelon-output lever op til GelatoConnects API-krav.

Avancerede teknikker til Template Mapper

Når du bliver mere fortrolig med template mappers, kan du tage de smarte funktioner i brug:

Makroer

Definér genanvendelige blokke af skabelonkode:

{% macro format_address(address) %}{"addressLine1": "####{{ address.street }}","city": "####{{ address.city }}","postCode": "####{{ address.zip }}","country": "####{{ address.country }}"}{% endmacro %}// Sådan bruger du det:"shippingAddress": ####{{ format_address(delivery) }}

Indstil statements

Opret variable i din skabelon:

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

Tilpassede filtre og funktioner

GelatoConnect understøtter flere tilpassede filtre og funktioner ud over standard Jinja2:

  • lookups(): Til at bygge bro mellem forskellige værdisystemer

  • js: For korrekt JSON-escaping

  • Forskellige funktioner til datoformatering

Vil du vide mere?

Nu hvor du har styr på det grundlæggende i Template Mappers i GelatoConnect, er du klar til at:

  1. Lær mere om at lave skabeloner til ordreindtastning

  2. Udforsk Jinja2 skabeloneksempler

  3. Opsæt postback-triggere, der bruger dine skabeloner

Relaterede artikler
[Ordreindtag – GCW] Sådan sætter du postbacks op
[Ordreindtag - GCW] Sådan opsætter du opslag
[Ordreindtag - GCW] Skabelonmapper-eksempler
[Ordreindtag – GCW] Opret skabeloner til ordreindtastning
[Ordreindtag - GCW] Ordreflows og statusser – sådan fungerer det
Besvarede dette dit spørgsmål?