Hoppa till huvudinnehåll

[Orderingång - GCW] Skapa mallar för orderingång

T
Skrivet av Toby Dawson
Uppdaterad för mer än 3 veckor sedan

Mallar är viktiga byggstenar i GelatoConnect som hanterar både inkommande och utgående dataflöden. De omvandlar kunddata till format som ditt arbetsflöde kan använda, och de anpassar utgående data från GelatoConnect så att de passar dina kunders system. I den här guiden får du steg för steg lära dig hur du skapar, testar och använder mallar för att hantera data åt båda hållen i dina orderflöden.

Förstå mallar i GelatoConnect

Mallar i GelatoConnect fungerar som ritningar som visar hur data ska struktureras, hanteras och presenteras. De tar hand om två viktiga dataflöden:

Inkommande datamallar

Dessa mallar omvandlar data från dina kunders system till format som GelatoConnect kan bearbeta:

  • Orderförfrågan: Konverterar kundens orderdata till GelatoConnects interna format

  • Avbryt begäran: Gör avbokningsförfrågningar tydliga för GelatoConnect

Utgående datamall

Dessa mallar bestämmer hur data från GelatoConnect skickas tillbaka till dina kunder eller deras system:

  • Svarsmallar: Bygger upp API-svar när en order skickas in eller avbryts

  • Händelsenotiser: Skapar standardiserade meddelanden för uppdateringar av orderstatus

  • Postbacks: Formaterar data som skickas till externa system när orderstatus ändras

Alla mallar använder Jinja2-templatspråket, som ger dig smarta verktyg för att omvandla data, styra innehåll och skapa dynamiska lösningar.

Typer av mallar du kan skapa

GelatoConnect stöder flera olika malltyper för olika dataflödesriktningar:

Inkommande datamall (Kund → GelatoConnect)

  • Beställningsförfrågan: Omvandlar kundens beställningsdata till GelatoConnects format

  • Avbryt begäran: Omvandlar kunders avbokningsbegäran till GelatoConnects format

Utgående datamall (GelatoConnect → Kund)

  • Skicka svar: Formaterar svar som skickas tillbaka efter orderläggning

  • Avbryt svar: Formaterar svar som skickas tillbaka efter att en avbokning har begärts

  • Webhook: Skapar JSON-nyttolaster för aviseringar till externa system vid ändringar av orderstatus

  • E-post: Skapar e-postnotiser för olika orderhändelser

Riktningen på dataflödet är avgörande att förstå när du skapar mallar, eftersom det avgör vilken data som är tillgänglig och hur den bör struktureras.

Steg-för-steg-guide för att skapa en mall

1. Gå till avsnittet för mallar

  1. Logga in på ditt GelatoConnect-konto

  2. Gå till Arbetsflöde > Orderintag > Mallar

  3. Klicka på Lägg till mall för att börja skapa en ny mall

2. Välj vilken typ av mall du vill ha

Välj vilken typ av mall du vill skapa:

  • För API-integrationer behöver du vanligtvis mallar för Order Submit Request, Submit Response och Cancel Response

  • För notifikationer, välj Webhook eller E-post

3. Bestäm formatet för mallen

Välj format för din mall:

  • JSON: Vanligast för API-integrationer och webhooks

  • XML: Används för vissa äldre system

  • Vanlig text: Används oftast för e-postmallar

4. Generera en exempelpayload för indata

För att skapa en effektiv mall behöver du förstå vilken data som kommer att finnas tillgänglig:

  1. Klicka på knappen Skapa mall

  2. Välj Lägg till exempeldata för att lägga in testdata

  3. Välj lämplig händelsetyp från rullgardinsmenyn:

    • Order mottagen

    • Beställningen misslyckades

    • Beställning annullerad

    • Ordern har kommit tillbaka

    • Ordern är klar

    • Beställningen är framme

    • Beställning skickad

    • Beställning på väg

Systemet kommer att fylla i en exempellast med typisk data för den händelsen, som du kan använda som referens när du skapar din mall.

5. Skapa din mallkarta

I Template Mapper bestämmer du hur data ska omvandlas mellan olika format:

  1. I avsnittet Template Mapper skriver du din mall med Jinja2-syntax

  2. Hämta referensdata från indata med dubbla måsvingar: ####{{ variable }}

  3. Lägg till formateringsfilter med pipe-symbolen: ####{{ variable|js }} (filtret js gör strängar säkra för JSON)

  4. Använd kontrollstrukturer som {% if %}, {% for %} och {% set %} för villkorsstyrd logik och loopar

Överväganden för mallriktning

Innehållet i din mall kommer att variera beroende på om du hanterar inkommande eller utgående data:

För inkommande datamall (Kund → GelatoConnect):

  • Fokusera på att extrahera data från kundspecifika format

  • Matcha egna fältnamn med GelatoConnects standardfältnamn

  • Kolla och anpassa data så att det funkar med GelatoConnects krav

  • Ta hand om särskilda format eller omvandlingar av data

För utgående datamallar (GelatoConnect → kund):

  • Bygg upp datan så att den passar kundens system

  • Ta med alla obligatoriska fält för kundens integration

  • Anpassa datum, valutavärden och annan data efter vad kunden föredrar

  • Lägg till kundunika ID:n eller referenser

Exempel: mall för mottagen order Webhook

Här är ett exempel på en mall för en "Order Received" Webhook:

{ "event": "Beställning mottagen", "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": "Vi har tagit emot din beställning."}

Den här mallen skapar en JSON-struktur med orderdetaljer och går igenom alla produkter i beställningen.

6. Skapa och dubbelkolla mallen

När du har skapat din mall:

  1. Klicka på Render-knappen för att sätta ihop mallen

  2. Kolla igenom resultatet i förhandsvisningen

  3. Kontrollera att all data är korrekt formaterad och att det inte finns några syntaxfel

  4. Kolla om något saknas eller är fel ifyllt

7. Testa din mall

Att testa är superviktigt för att din mall ska funka som den ska:

  1. Ge ditt test ett namn i avsnittet Testmall

  2. Klicka på Kör test för att köra mallen mot exempeldata

  3. Kolla att Status visar Godkänd

  4. Kolla igenom resultatet och se till att det känns rätt för dig

8. Spara din mall

När du känner dig nöjd med mallen:

  1. Ge din mall ett namn som säger vad den handlar om

  2. Klicka på Lägg till mall eller Spara ändringar för att spara

  3. Mallen är nu redo att användas i triggers och arbetsflöden

Så funkar mallar ihop med triggers

Mallar används oftast tillsammans med triggers för att automatiskt skicka notiser när något särskilt händer:

1. Skapa en trigger

  1. Gå till Workflow > Order Intake > Triggers

  2. Klicka på Lägg till utlösare

  3. Välj vilken kund det här trigget gäller för

  4. Ge ditt trigger ett namn (t.ex. "Order mottagen-notis")

  5. Välj det händelse som ska starta triggern (t.ex. "Order received")

2. Ställ in leveranssätt

Välj hur du vill få dina notiser:

  • URL: Skicka en webhook till ett externt system

    • Ange webbadressen dit du vill komma

    • Välj POST- eller GET-metod

    • Välj JSON- eller XML-format

    • Ställ in alternativ för att försöka igen om du vill

  • E-post: Skicka ett mejlmeddelande

    • Skriv in mottagarens e-postadresser

    • Lägg till en ämnesrad

    • Ange avsändarens namn och adress

3. Välj din mall

  1. Välj den mall du skapade tidigare i rullgardinsmenyn Mall

  2. Om ingen mall finns kan du skapa en direkt i utlösarkonfigurationen med samma gränssnitt som beskrivs ovan

Skapa mallar direkt från triggers

För att göra det enkelt kan du också skapa mallar samtidigt som du ställer in triggers:

  1. När du skapar en trigger, klicka på Skapa mall istället för att välja en befintlig mall.

  2. Välj vilket format du vill använda för mallen (JSON, XML eller vanlig text)

  3. Använd mallredigeraren för att skapa din mall enligt beskrivningen ovan

  4. Spara mallen, så väljs den automatiskt för denna utlösare

Detta tillvägagångssätt är användbart för att snabbt skapa mallar när du redan konfigurerar en utlösare.

Koppla mallar till API-endpoints

När du skickar in beställningar via API behöver du ofta omvandla data mellan ditt format och GelatoConnects format. Mallar sköter den här omvandlingen, men du måste själv koppla din mall till API-endpointen för att den ska användas.

Hur du länkar en mall till en slutpunkt för orderinlämning:

  1. Gå till din lista med kopplingar och klicka på länken Redigera bredvid submit order-endpunkten.

  2. På sidan för slutpunktskonfiguration, hitta avsnittet Slutpunktsmall

  3. Välj din mall för orderinlämning i rullgardinsmenyn

  4. Klicka på knappen Ange slutpunkt uppe till höger på sidan

  5. Klicka på Spara ändringar uppe till höger för att spara dina inställningar

När du har gjort klart de här stegen kommer alla order som skickas till den här endpointen att använda din mall för att omvandla datan innan den behandlas. På så sätt ser du till att ditt systems format omvandlas rätt till GelatoConnects förväntade format.

Utan den här inställningen kommer din mall inte att användas, även om den finns och är rätt utformad. Det kan göra att beställningar inte går igenom om ditt dataformat inte stämmer exakt med GelatoConnects krav.

Avancerade malltekniker

Så funkar uppslag

Uppslagningar är särskilt värdefulla för dubbelriktad datamappning mellan system. De fungerar olika beroende på mallens riktning:

För inkommande mallar (kund → GelatoConnect):

Matcha kundunika värden med GelatoConnects standardvärden:

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

För utgående mallar (GelatoConnect → kund):

Gör om GelatoConnects interna värden till det format kunderna förväntar sig:

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

Villkorad logik

Använd villkor för att inkludera eller formatera data på olika sätt beroende på omständigheterna:

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

Variabeltilldelning

Skapa variabler för att göra det enklare att hantera krångliga uttryck:

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

Loopar med kluriga objekt

Navigera i nästlade datastrukturer:

"artiklar": [ {% 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 %}]

Bästa tipsen för mallar

Namngivning utifrån riktning

  • Använd tydliga och beskrivande namn som visar både syftet och åt vilket håll informationen går

  • För inkommande mallar: Lägg till prefix som "IN_" eller suffix som "_Request"

  • För utgående mallar: Använd prefix som \"OUT_\" eller suffix som \"_Response\" eller \"_Notification\"

  • Ta med kundens namn för mallar som är anpassade för varje kund

  • Använd samma namnstruktur så blir det lätt att hitta dina mallar

Felsökning

  • Sätt standardvärden så slipper du problem med tomma värden

  • Använd filtret default för att visa något när värden saknas: ####{{ variable|default('N/A') }}

  • Använd try/except-block när du har kod som kan ställa till problem

Underhåll

  • Lägg till kommentarer för att förklara kluriga delar: {# Detta tar hand om ett speciellt fall för internationella beställningar #}

  • Håll mallarna flexibla och anpassade för olika behov

  • Uppdatera mallarna när datan eller behoven förändras

Testar

  • Testa med olika typer av data, även de ovanliga situationerna

  • Testa mallarna med riktig produktionsdata när du kan

  • Skapa omfattande tester för kritiska mallar

Felsökning av mallproblem

Vanliga problem och smarta lösningar

Problem

Möjlig orsak

Lösning

Syntaxfel

Felaktigt matchade parenteser eller citattecken

Dubbelkolla mallens syntax – se till att alla öppningstaggar har matchande stängningstaggar.

Saknade data

Refererar till fält som inte finns

Dubbelkolla att fältnamnen stämmer med det du skickar in, och lägg till standardvärden för de fält som är valfria.

Formateringsproblem

Felaktig filteranvändning

Dubbelkolla att du använder filter som js, json eller xml på rätt sätt

Mallen har inte använts

Mall inte kopplad till utlösare

Verifiera triggerinställningar och mallval

Fel vid åtkomst av inbäddad data

Fel sökväg till underliggande egenskaper

Kolla hur datan är uppbyggd och ändra vägarna till egenskaperna så att de passar

Problem med att matcha fält

Felaktiga fältnamn för inkommande/utgående data

När du tar emot mallar, dubbelkolla vad kundfälten heter. När du skickar ut mallar, se till att svaret har rätt format.

Problem med dataomvandling

Oförenliga dataformat

Säkerställ korrekt datatypskonvertering mellan system (datum, siffror, etc.)

Felsökningstips

  • Använd knappen Render ofta när du utvecklar, så upptäcker du fel i tid.

  • Lägg till tillfällig felsökningsutskrift för att kolla vad variablerna innehåller

  • Dubbelkolla att du inte har råkat stava fel på fältnamnen – det är lätt hänt och ofta där det blir fel.

  • Kom ihåg att Jinja2 skiljer på stora och små bokstäver när du använder variabler

Relaterade artiklar
[Orderingång - GCW] Hur ställer man in postbacks?
[Orderingång - GCW] Arbeta med Order API-slutpunkter
[Orderingång - GCW] Begrepp och koncept för orderingång
[Orderingång - GCW] GelatoConnect API-grunder
[Orderingång - GCW] Introduktion till mallkopplare
Fick du svar på din fråga?