Gå til hovedinnhold

[Ordremottak – GCW] Lage maler for ordremottak

T
Skrevet av Toby Dawson
Oppdatert for over 3 uker siden

Maler er viktige byggesteiner i GelatoConnect som styrer både innkommende og utgående datastrømmer. De gjør om kundedata til formater som passer inn i arbeidsflyten din, og tilpasser utgående data fra GelatoConnect slik at de møter kravene til kundens system. Denne veiledningen viser deg hvordan du lager, tester og tar i bruk maler for begge retninger av datautveksling i ordrehåndteringen din.

Slik fungerer maler i GelatoConnect

Maler i GelatoConnect fungerer som oppskrifter som viser hvordan data skal organiseres, behandles og vises. De styrer to viktige datastrømmer:

Innkommende datamaler

Disse malene gjør om data fra kundens systemer til formater GelatoConnect kan bruke:

  • Ordreinnsendingsforespørsel: Gjør kundeordren om til GelatoConnect sitt interne format

  • Avbryt forespørsel: Gjør det enkelt for GelatoConnect å forstå avbestillinger

Utgående datamaler

Disse malene setter opp data som sendes fra GelatoConnect tilbake til kundene dine eller systemene deres:

  • Svarformat: Strukturerer API-svar for innsending eller kansellering av bestillinger

  • Hendelsesvarsler: Lager tydelige meldinger om oppdateringer på ordrestatus

  • Postbacks: Slik sender vi data til eksterne systemer når ordrestatus endres

Alle maler bruker Jinja2-malspråket, som gir deg mange muligheter for å tilpasse data, bruke betinget logikk og lage dynamisk innhold.

Ulike maler du kan lage

GelatoConnect støtter flere maltyper for ulike retninger på dataflyten:

Innkommende datamaler (kunde → GelatoConnect)

  • Bestillingsforespørsel: Gjør om kundeordren til GelatoConnect sitt format

  • Avbryt forespørsel: Gjør kundens ønske om avbestilling om til GelatoConnect sitt format

Utgående datamaler (GelatoConnect → kunde)

  • Send inn svar: Formaterer svarene som sendes tilbake etter at en bestilling er sendt inn

  • Avbryt svar: Viser hvordan svar sendes tilbake etter at du har bedt om å avbryte

  • Webhook: Lager JSON-meldinger for varsler til eksterne systemer når ordrestatus endres

  • E-post: Lager e-postvarsler for ulike ordreoppdateringer

Det er viktig å forstå hvilken vei dataene flyter når du lager maler, fordi det avgjør hvilke data som er tilgjengelige og hvordan de bør organiseres.

Enkel guide: Slik lager du en mal, steg for steg

1. Gå til maler

  1. Logg inn på GelatoConnect-kontoen din

  2. Gå til Arbeidsflyt > Ordremottak > Maler

  3. Klikk på Legg til mal for å begynne å lage en ny mal

2. Velg hvilken mal du vil bruke

Velg hvilken type mal du vil lage:

  • For API-integrasjoner trenger du som regel maler for Order Submit Request, Submit Response og Cancel Response.

  • For varsler, velg Webhook eller E-post

3. Definer malformatet

Velg formatet for malen din:

  • JSON: Vanligst for API-integrasjoner og webhooks

  • XML: Brukes fortsatt i noen eldre systemer

  • Ren tekst: Brukes vanligvis i e-postmaler

4. Lag et eksempel på en inndata

For å lage en god mal, må du vite hvilke data du har å jobbe med:

  1. Trykk på Generer mal-knappen

  2. Velg Legg til eksempel på inndata for å legge inn testdata

  3. Velg riktig type arrangement fra rullegardinmenyen:

    • Bestillingen er mottatt

    • Bestillingen gikk ikke gjennom

    • Bestilling kansellert

    • Bestillingen er returnert

    • Bestillingen er ferdig produsert

    • Bestillingen er levert

    • Bestilling sendt

    • Bestillingen er på vei

Systemet fyller ut et eksempel med typiske data for denne hendelsen, så du kan bruke det som referanse når du lager malen din.

5. Lag din egen mal-mapper

Template Mapper er stedet der du bestemmer hvordan data blir gjort om mellom ulike formater:

  1. I delen Template Mapper skriver du malen din med Jinja2-syntaks

  2. Hent referansedata fra innlastet payload ved å bruke doble krøllparenteser: ####{{ variable }}

  3. Legg til formateringsfiltre med pipe-symbolet: ####{{ variable|js }} (filteret js gjør strenger trygge for JSON)

  4. Bruk kontrollstrukturer som {% if %}, {% for %} og {% set %} for å lage betingelser og gjentakelser

Ting å tenke på når du lager maler

Innholdet i malen din vil variere avhengig av om du jobber med innkommende eller utgående data:

For innkommende datamaler (kunde → GelatoConnect):

  • Fokuser på å hente ut data fra kundens egne formater

  • Koble personlig tilpassede feltnavn til GelatoConnects standardfeltnavn

  • Sjekk og tilpass dataene slik at de passer med kravene til GelatoConnect

  • Ta hånd om spesielle formateringsbehov eller konvertering av data

For utgående datamaler (GelatoConnect → kunde):

  • Strukturer data slik kundens system forventer det

  • Ta med alle nødvendige felt for kundens integrasjon

  • Formater datoer, valutaverdier og annen informasjon slik kunden ønsker det

  • Legg til eventuelle unike kjennetegn eller referanser for kunden

Eksempel: mal for mottatt ordre Webhook

Her er et eksempel på en mal for en «Order Received» Webhook:

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

Denne malen lager en JSON-struktur med ordreopplysninger og går gjennom alle varer i ordren.

6. Gjør klar og sjekk malen

Når du har laget malen din:

  1. Trykk på Render-knappen for å sette sammen malen

  2. Se gjennom resultatet i forhåndsvisningen

  3. Sjekk at alle data er riktig formatert og at det ikke finnes noen syntaksfeil

  4. Se etter manglende eller feil utfylte felt

7. Test ut malen din

Testing er viktig for å være sikker på at malen din fungerer som den skal:

  1. Gi testen din et navn i delen Testmal

  2. Klikk på Kjør test for å prøve malen med eksempeldata

  3. Sjekk at Status viser Bestått

  4. Se over resultatet og sjekk at det er som du ønsker

8. Lagre malen din

Når du er fornøyd med malen:

  1. Gi malen din et beskrivende navn

  2. Klikk på Legg til mal eller Lagre endringer for å lagre

  3. Malen er nå klar til bruk i utløser- og arbeidsflytoppsett

Slik bruker du maler sammen med utløsere

Maler brukes som regel sammen med utløsere for å automatisk sende varsler når noe spesielt skjer:

1. Lag en utløser

  1. Gå til Workflow > Order Intake > Triggers

  2. Klikk på Legg til utløser

  3. Velg kunden denne utløseren gjelder for

  4. Gi triggeren et navn (for eksempel «Varsel om mottatt bestilling»

  5. Velg hendelsen som skal starte utløseren (for eksempel «Bestilling mottatt»).

2. Velg leveringsmetode

Velg hvordan du vil få varsler:

  • URL: Send en Webhook til et eksternt system

    • Oppgi destinasjonsadressen

    • Velg POST- eller GET-metode

    • Velg JSON- eller XML-format

    • Velg innstillinger for nye forsøk hvis du ønsker det

  • E-post: Send en e-postvarsling

    • Skriv inn e-postadressene til mottakerne

    • Legg til en emnelinje

    • Skriv inn navn og adresse til avsender

3. Velg mal

  1. Velg malen du lagde tidligere fra Mal-menyen

  2. Hvis det ikke finnes en mal, kan du lage en direkte i utløseroppsettet med det samme grensesnittet som beskrevet over

Lag maler direkte fra utløsere

For enkelhets skyld kan du også lage maler mens du setter opp utløsere:

  1. Når du lager en utløser, klikker du på Opprett mal i stedet for å velge en eksisterende mal.

  2. Velg hvilket format malen skal ha (JSON, XML eller ren tekst)

  3. Bruk malredigereren for å lage malen din slik som beskrevet over

  4. Lagre malen, så blir den automatisk valgt for denne utløseren

Denne metoden er smart når du vil lage en mal raskt mens du allerede setter opp en utløser.

Koble maler til API-endepunkter

Når du sender inn bestillinger via API, må du ofte gjøre om data fra ditt format til GelatoConnect sitt format. Maler tar seg av denne omformingen, men du må selv koble malen til API-endepunktet for at den skal brukes.

Slik kobler du en mal til et endepunkt for innsending av bestilling:

  1. Gå til listen over koblinger og klikk på Rediger-lenken ved siden av send inn bestilling-endepunktet.

  2. På siden for endepunktoppsett finner du delen Endepunktmal

  3. Velg malen for innsending av bestilling fra rullegardinmenyen

  4. Trykk på Angi endepunkt-knappen øverst til høyre på siden

  5. Trykk på Lagre endringer oppe til høyre for å ta i bruk oppsettet ditt

Når du har gjort disse stegene, vil alle ordreinnsendinger til dette endepunktet bruke malen din for å endre dataene før de behandles. Da blir formatet til systemet ditt riktig gjort om til det GelatoConnect forventer.

Uten denne konfigurasjonen blir ikke malen din brukt, selv om den finnes og er riktig utformet. Det kan føre til at ordre ikke blir godkjent hvis dataformatet ditt ikke stemmer helt med kravene til GelatoConnect.

Avanserte malteknikker

Slik bruker du oppslag

Oppslag er spesielt nyttige når du skal koble data begge veier mellom ulike systemer. De fungerer litt forskjellig avhengig av hvilken vei malen går:

For innkommende maler (kunde → GelatoConnect):

Koble kundespesifikke verdier til GelatoConnects standardverdier:

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

For utgående maler (GelatoConnect → kunde):

Gjør om GelatoConnects interne verdier til det kundene forventer:

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

Betinget logikk

Bruk betingelser for å inkludere eller formatere data forskjellig avhengig av situasjonen:

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

Tildele variabel

Lag variabler for å gjøre kompliserte uttrykk enklere:

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

Løkker med komplekse objekter

Finn frem i lag på lag med data:

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

Beste praksis for maler

Navngivningsregler basert på retning

  • Bruk tydelige og beskrivende navn som viser både hensikt og hvilken vei dataene går

  • For innkommende maler: Bruk prefikser som «IN_» eller suffikser som «_Request»

  • For utgående maler: Bruk prefikser som «OUT_» eller suffikser som «_Response» eller «_Notification»

  • Ta med kundenavnet for personlig tilpassede maler

  • Bruk samme navnemønster hver gang, så finner du enkelt igjen malene dine

Feilhåndtering

  • Sett standardverdier for å unngå nullreferanser

  • Bruk default-filteret for manglende verdier: ####{{ variable|default('N/A') }}

  • Bruk try/except-blokker der det kan oppstå problemer i koden

Vedlikehold

  • Legg til kommentarer for å forklare komplisert logikk: {# Dette tar seg av spesielle tilfeller for internasjonale bestillinger #}

  • Hold malene fleksible og rettet mot bestemte formål

  • Oppdater maler når datastrukturer eller krav endrer seg

Tester

  • Test med ulike datasituasjoner, også de som er litt utenom det vanlige

  • Test malene med ekte produksjonsdata når det er mulig

  • Lag grundige tester for viktige maler

Feilsøking av problemer med maler

Vanlige utfordringer og løsninger

Utfordring

Mulig årsak

Vår løsning

Syntaksfeil

Ulike klammeparenteser eller anførselstegn

Se nøye over malens syntaks – sørg for at alle åpningstagger har en tilhørende lukkingstag.

Mangler data

Viser til felter som ikke finnes

Sjekk at feltnavn stemmer med innsendt data, og legg til standardverdier for valgfrie felt

Formateringsproblemer

Feil bruk av filter

Sjekk at du bruker filtre som js, json eller xml riktig

Mal ikke tatt i bruk

Mal er ikke koblet til utløser

Sjekk oppsettet for utløser og valg av mal

Feil ved tilgang til innhold i flere lag

Feil sti til underliggende egenskaper

Sjekk datastrukturen og tilpass egenskapsstiene deretter

Feil ved feltmapping

Feil feltnavn for innkommende eller utgående data

For innkommende maler, sjekk at kundenavnene på feltene stemmer. For utgående maler, se at svaret har riktig format.

Problemer med datakonvertering

Uforenlige dataformater

Sørg for riktig konvertering av datatyper mellom systemene (datoer, tall og lignende)

Tips for feilsøking

  • Bruk Render-knappen ofte når du utvikler, så oppdager du feil tidlig

  • Legg til midlertidig feilmeldingsutskrift for å sjekke verdiene til variablene

  • Sjekk om det er skrivefeil i feltnavn – det er ofte der feil oppstår

  • Husk at Jinja2 skiller mellom store og små bokstaver når du refererer til variabler

Relaterte artikler
[Ordremottak – GCW] Hvordan setter du opp postbacks?
[Ordremottak – GCW] Slik setter du opp oppslag
[Ordremottak – GCW] Introduksjon til mal-mappere
[Order Intake – GCW] Lage en mal
[Ordremottak – GCW] Integrere GelatoConnect med Cloudprinter
Svarte dette på spørsmålet?