Spring videre til hovedindholdet

[Ordreindtag – GCW] Opret skabeloner til ordreindtastning

T
Skrevet af Toby Dawson
Opdateret for over 3 uger siden

Skabeloner er vigtige elementer i GelatoConnect, der styrer både indgående og udgående data. De omdanner kundedata, så det passer til dit workflow, og de tilpasser udgående data fra GelatoConnect, så det matcher dine kunders systemkrav. Denne guide hjælper dig trin for trin med at oprette, teste og bruge skabeloner til begge retninger af dataudveksling i dine ordreprocesser.

Forstå skabeloner i GelatoConnect

Skabeloner i GelatoConnect fungerer som skabeloner, der viser, hvordan data skal struktureres, behandles og præsenteres. De styrer to vigtige dataflows:

Indgående dataskabeloner

Disse skabeloner gør det nemt at omdanne data fra dine kunders systemer til formater, som GelatoConnect kan arbejde med:

  • Ordreafsendelse: Gør kundens ordredata klar til GelatoConnects interne format

  • Annuller anmodning: Gør det nemt for GelatoConnect at forstå dine annulleringsanmodninger

Udgående dataskabeloner

Disse skabeloner sørger for, at data fra GelatoConnect bliver sendt tilbage til dine kunder eller deres systemer i det rigtige format:

  • Svarformat: Strukturerer API-svar på ordrer, der bliver oprettet eller annulleret

  • Begivenhedsnotifikationer: Sender klare beskeder, når der sker ændringer i ordrestatus

  • Postbacks: Sender data til eksterne systemer, når ordrestatuser ændrer sig

Alle skabeloner bruger Jinja2-skabelonsproget, som giver dig stærke muligheder for at tilpasse data, lave betinget logik og skabe dynamisk indhold.

Typer af skabeloner du kan lave

GelatoConnect understøtter flere skabelontyper til forskellige retninger for dataflow:

Indgående dataskabeloner (kunde → GelatoConnect)

  • Ordreafsendelse: Gør kundens ordredata klar til GelatoConnects format

  • Annuller anmodning: Gør det nemt at omdanne kunders annulleringsønsker til GelatoConnects format

Udgående dataskabeloner (GelatoConnect → Kunde)

  • Send svar: Formaterer de svar, der sendes tilbage efter en ordre er sendt

  • Annuller svar: Viser, hvordan svar ser ud, når du har bedt om at annullere

  • Webhook: Sender JSON-data til eksterne systemer, når der sker ændringer i ordrestatus

  • Email: Formaterer e-mailnotifikationer til forskellige ordreopdateringer

Det er vigtigt at forstå, hvilken vej dataene bevæger sig, når du laver skabeloner – det afgør nemlig, hvilke data du har adgang til, og hvordan de skal sættes op.

Trin for trin-guide til at lave en skabelon

1. Gå til skabelon-sektionen

  1. Log ind på din GelatoConnect-konto

  2. Gå til Workflow > Order Intake > Skabeloner

  3. Klik på Tilføj skabelon for at komme i gang med at lave en ny skabelon

2. Vælg din skabelontype

Vælg den type skabelon, du vil lave:

  • Til API-integrationer skal du som regel bruge Order Submit Request-, Submit Response- og Cancel Response-skabeloner.

  • Til notifikationer skal du vælge Webhook eller Email

3. Definér skabelonens format

Vælg det format, du vil bruge til din skabelon:

  • JSON: Det mest brugte format til API-integrationer og Webhook

  • XML: Bruges til nogle ældre systemer

  • Almindelig tekst: Bruges typisk til e-mailskabeloner

4. Lav et eksempel på en input-payload

For at lave en god skabelon skal du vide, hvilke data du har til rådighed:

  1. Klik på knappen Generér skabelon

  2. Vælg Tilføj eksempel på inputdata for at give testdata

  3. Vælg den rigtige begivenhedstype i rullemenuen:

    • Ordre modtaget

    • Ordre mislykkedes

    • Ordren er annulleret

    • Ordre sendt retur

    • Ordre produceret

    • Ordre leveret

    • Ordren er sendt afsted

    • Ordre på vej

Systemet udfylder et eksempel med typiske data for den begivenhed, så du kan bruge det som inspiration, når du laver din skabelon.

5. Lav din Template Mapper

Template Mapper er stedet, hvor du bestemmer, hvordan data bliver omdannet mellem forskellige formater:

  1. I afsnittet Template Mapper skriver du din skabelon med Jinja2-syntaks

  2. Brug data fra inputtet ved at skrive dobbelt krøllede parenteser: ####{{ variable }}

  3. Tilføj formateringsfiltre med pipe-symbolet: ####{{ variable|js }} (filteret js gør tekst klar til JSON)

  4. Brug kontrolstrukturer som {% if %}, {% for %} og {% set %} til at styre betingelser og gentagelser

Ting du skal tænke over, når du vælger retning for din skabelon

Indholdet i din skabelon afhænger af, om du arbejder med data, der kommer ind, eller data, der skal sendes ud:

For indgående dataskabeloner (kunde → GelatoConnect):

  • Fokusér på at hente data ud fra formater, der er tilpasset den enkelte kunde

  • Match tilpassede feltnavne med GelatoConnects standardfeltnavne

  • Tjek og tilpas data, så det passer til GelatoConnects krav

  • Tag dig af særlige formaterings- eller databehandlingsbehov

For udgående dataskabeloner (GelatoConnect → Kunde):

  • Opbyg data, så det passer til det, kundens system har brug for

  • Husk at tage alle nødvendige felter med til kundens integration

  • Formater datoer, valutaværdier og andre data, så de passer til kundens ønsker

  • Tilføj eventuelle unikke kendetegn eller referencer for kunden

Eksempel: Skabelon til Webhook for modtaget ordre

Her er et eksempel på en skabelon til en "Order Received" Webhook:

{ "event": "Bestilling modtaget", "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": "Ordren er modtaget."}

Denne skabelon laver en JSON-struktur med ordreoplysninger og gennemgår alle varer i ordren.

6. Gennemgå og tjek skabelonen

Når du har lavet din skabelon:

  1. Klik på Render-knappen for at samle skabelonen

  2. Tjek resultatet i forhåndsvisningen

  3. Tjek, at alle data er formateret korrekt, og at der ikke er nogen syntaksfejl

  4. Tjek om der mangler felter, eller om de er udfyldt forkert

7. Test din skabelon

Det er vigtigt at teste, så du er sikker på, at din skabelon fungerer som den skal:

  1. Giv din test et navn under afsnittet Testskabelon

  2. Klik på Kør test for at prøve skabelonen med eksemplet på data

  3. Tjek, at Status står som Bestået

  4. Gennemgå resultatet og tjek, om det lever op til dine forventninger

8. Gem din skabelon

Når du er tilfreds med skabelonen:

  1. Giv din skabelon et navn, der fortæller, hvad den handler om

  2. Klik på Tilføj skabelon eller Gem ændringer for at gemme den

  3. Skabelonen er nu klar til at blive brugt i triggers og workflow-indstillinger

Sådan bruger du skabeloner sammen med udløsere

Skabeloner bruges oftest sammen med udløsere til automatisk at sende beskeder, når bestemte ting sker:

1. Opret en trigger

  1. Gå til Workflow > Order Intake > Triggers

  2. Klik på Tilføj udløser

  3. Vælg den kunde, som denne trigger gælder for

  4. Giv din trigger et navn (f.eks. "Ordre modtaget-besked")

  5. Vælg den begivenhed, der skal sætte triggeren i gang (f.eks. "Ordre modtaget")

2. Vælg leveringsmetode

Vælg, hvordan du vil modtage notifikationer:

  • URL: Send en Webhook til et eksternt system

    • Angiv den URL, du vil sende til

    • Vælg POST- eller GET-metode

    • Vælg JSON- eller XML-format

    • Indstil genforsøgsindstillinger, hvis du har lyst

  • Email: Send en mailnotifikation

    • Indtast modtagerens e-mailadresser

    • Tilføj en emnelinje

    • Angiv afsendernavn og adresse

3. Vælg din skabelon

  1. Vælg den skabelon, du lavede tidligere, i Skabelon-menuen

  2. Hvis der ikke findes en skabelon, kan du nemt lave en direkte i trigger-konfigurationen med det samme interface som beskrevet ovenfor.

Lav skabeloner direkte fra triggers

For nemheds skyld kan du også lave skabeloner, mens du sætter triggers op:

  1. Når du opretter en trigger, skal du i stedet for at vælge en eksisterende skabelon klikke på Opret skabelon

  2. Vælg skabelonformat (JSON, XML eller almindelig tekst)

  3. Brug skabeloneditoren til at lave din skabelon, som beskrevet ovenfor

  4. Gem skabelonen, så bliver den automatisk valgt til denne trigger

Den her metode er smart, hvis du hurtigt vil lave en skabelon, mens du alligevel er i gang med at sætte en trigger op.

Sådan kobler du skabeloner til API-endpoints

Når du sender ordrer via API, skal du ofte omdanne data fra dit eget format til GelatoConnects format. Skabeloner klarer den omstilling, men du skal selv koble din skabelon til API-endpointet, før den bliver brugt.

Sådan kobler du en skabelon til et order submit-endpoint:

  1. Gå til din connector-liste, og klik på Rediger-linket ved siden af submit order-endpointet.

  2. På siden med endpoint-indstillinger skal du finde afsnittet Endpoint-skabelon

  3. Vælg din skabelon til ordreafgivelse i rullemenuen

  4. Klik på knappen Angiv endpoint øverst til højre på siden

  5. Klik på Gem ændringer oppe i højre hjørne for at gemme dine indstillinger

Når du har fulgt disse trin, vil alle ordreindsendelser, der sendes til dette endpoint, bruge din skabelon til at omdanne dataene, før de behandles. Det sikrer, at dit systems format bliver omdannet korrekt til det format, GelatoConnect forventer.

Uden denne opsætning bliver din skabelon ikke brugt, selvom den findes og er designet korrekt. Det kan betyde, at din ordre ikke bliver godkendt, hvis dit dataformat ikke passer præcis til GelatoConnects krav.

Smarte tricks til skabeloner

Sådan bruger du opslag

Lookups er særligt nyttige, når du skal matche data begge veje mellem systemer. De fungerer forskelligt alt efter, hvilken vej skabelonen går:

For indgående skabeloner (kunde → GelatoConnect):

Match kundespecifikke værdier med GelatoConnects standardiserede værdier:

{% set shipMethod = lookups({"shipping_code": order.shipping.method}, strict=False, default="normal") %} "shipmentMethodUid": ####{{ shipMethod|js }},

For udgående skabeloner (GelatoConnect → kunde):

Gør GelatoConnects interne værdier lette at forstå for kunderne:

{% set customerShippingCode = lookups({"gelatoShipMethod": shipment.shipmentMethodUid}, strict=False, default=shipment.shipmentMethodUid) %} "shipping_method": ####{{ customerShippingCode|js }},

Betinget logik

Brug betingelser til at tilføje eller formatere data forskelligt alt efter situationen:

{% if item.fulfillmentStatus == "shipped" %} "trackingNumber": "####{{ item.trackingCode }}", "trackingUrl": "####{{ item.trackingUrl }}",{% endif %}

Tildeling af variabel

Lav variabler, så du nemt kan holde styr på de svære udtryk:

{% set fullName = customer.firstName + " " + customer.lastName %} "recipientName": "####{{ fullName }}",

Løkker med komplekse objekter

Find rundt i indlejrede datastrukturer:

"items": [ {% for item in items %} { "sku": "####{{ item.sku }}", "quantity": ####{{ item.quantity }}, "options": [ {% for option in item.options %} { "name": "####{{ option.name }}", "value": "####{{ option.value }}" }{% if not loop.last %},{% endif %} {% endfor %} ] }{% if not loop.last %},{% endif %} {% endfor %}]

Bedste tips til skabeloner

Navngivningsregler baseret på retning

  • Brug tydelige og beskrivende navne, der viser både formål og hvilken vej dataene bevæger sig

  • For indgående skabeloner: Tilføj for eksempel præfikser som "IN_" eller suffikser som "_Request"

  • Til udgående skabeloner: Brug for eksempel præfikser som "OUT_" eller suffikser som "_Response" eller "_Notification"

  • Tilføj kundens navn til skabeloner, der er lavet specielt til dem

  • Brug ensartede navne, så du nemt kan finde dine skabeloner

Fejlhåndtering

  • Sæt standardværdier for at undgå fejl, hvis noget mangler

  • Brug default-filteret til manglende værdier: ####{{ variable|default('N/A') }}

  • Brug try/except-blokke, når du arbejder med kode, der kan give problemer

Vedligeholdelse

  • Tilføj kommentarer for at gøre svær logik nemmere at forstå: {# Dette håndterer særlige tilfælde for internationale ordrer #}

  • Hold skabelonerne enkle og målrettede, så de passer til hver opgave

  • Opdatér skabeloner, når datastrukturer eller krav ændrer sig

Tester

  • Test med forskellige datasituationer – også de skæve og uventede

  • Tjek skabeloner med rigtige produktionsdata, når det er muligt

  • Lav grundige tests for vigtige skabeloner

Sådan løser du problemer med skabeloner

Typiske udfordringer og løsninger

Udfordring

Mulig årsag

Løsning

Syntaksfejl

Parenteser eller anførselstegn, der ikke passer sammen

Tjek skabelonens syntaks grundigt – sørg for, at alle åbningstags har et tilsvarende lukningstag

Mangler data

At henvise til felter, der ikke findes

Tjek om feltnavne matcher inputdata, og tilføj standardværdier til valgfrie felter

Problemer med formatering

Forkert brug af filter

Tjek, at du bruger filtre som js, json eller xml rigtigt

Skabelon ikke brugt

Skabelonen er ikke forbundet til en udløser

Tjek om din trigger er sat rigtigt op, og om du har valgt den rigtige skabelon

Fejl ved adgang til indlejrede data

Forkert sti til underliggende egenskaber

Tjek datastrukturen og ret stierne til egenskaber, så de passer

Fejl i felt-tilknytning

Forkerte feltnavne for indgående/udgående data

For indgående skabeloner, tjek kundens feltnavne – for udgående skabeloner, sørg for at svaret har det rigtige format

Problemer med at få dataene til at spille

Uforenelige dataformater

Sørg for, at data bliver konverteret korrekt mellem systemerne (datoer, tal osv.)

Tips til fejlfinding

  • Brug Render-knappen ofte, mens du udvikler, så du hurtigt kan fange fejl undervejs

  • Tilføj midlertidig debug-output for at tjekke værdierne af variabler

  • Tjek for stavefejl i feltnavne – det er ofte der, fejl sniger sig ind.

  • Husk, at Jinja2 skelner mellem store og små bogstaver, når du bruger variabler

Relaterede artikler
[Ordreindtag – GCW] Sådan sætter du postbacks op
[Ordreindtag - GCW] Sådan opsætter du opslag
[Ordremodtagelse – GCW] Sådan arbejder du med Order API-endpoints
[Ordreindtag - GCW] Introduktion til Template Mappers
[Order Intake - GCW] Opret en skabelon
Besvarede dette dit spørgsmål?