Hoppa till huvudinnehåll

[Orderingång - GCW] Introduktion till mallkopplare

Juliana Maciel Maruri da Cunha avatar
Skrivet av Juliana Maciel Maruri da Cunha
Uppdaterad för mer än 3 veckor sedan

Vad är template mappers?

Mallmappare i GelatoConnect är smarta verktyg som hjälper dig att omvandla data mellan ditt system och GelatoConnect. De fungerar som översättare och ser till att informationen flyter smidigt mellan olika system, oavsett hur de är uppbyggda.

Oavsett om du skickar in beställningar till GelatoConnect eller får uppdateringar om orderstatus, gör mallmappare det enkelt att omvandla dataformat utan att du behöver ändra dina nuvarande system.

Varför använda mallmappare?

Mallkopplare löser flera vanliga integrationsutmaningar:

  1. Olika datastrukturer: Ditt system och GelatoConnect kan sortera samma information på olika sätt.

  2. Skillnader i fältnamn: Ditt system kanske kallar en leveransadress för "delivery_address" medan GelatoConnect använder "shippingAddress".

  3. Formatkonverteringar: Du kan behöva konvertera dataformat, som att ändra datumformat eller omvandla måttenheter.

  4. Välj vilka fält du vill ta med: Ibland vill du kanske bara skicka vissa delar av din data till GelatoConnect.

  5. Villkorad logik: Ibland behöver du använda olika regler beroende på till exempel ordertyp eller vilket land beställningen ska skickas till.

Så funkar mallmappare

GelatoConnect använder Jinja2-mallspråket för sina mallmappningar. Det här kraftfulla och flexibla språket gör att du kan:

  1. Hämta värden: Plocka ut data från ditt indataformat

  2. Förvandla data: Använd smarta knep och funktioner för att göra om datan

  3. Bygg utdata: Skapa det slutgiltiga resultatet i GelatoConnects förväntade format

En mallmappare tar en inmatning (din data) och producerar en utmatning (GelatoConnect-kompatibel data) baserat på en uppsättning transformationsregler som du definierar.

Komponenter för mallhantering

En vanlig mallmappare i GelatoConnect består av de här delarna:

1. Indata

Det här är källdatan du vill omvandla. Det kan vara:

  • Beställningsdata från ditt e-handelssystem

  • Kundinformation från din CRM

  • Produktdetaljer från din katalog

2. Mallbeskrivning

Här bestämmer du hur du vill omvandla din indata. Med Jinja2-syntax kan du ange:

  • Vilka fält du vill plocka ut från indata

  • Eventuella transformationer att tillämpa

  • Strukturen på utdata

3. Så här gör du

Resultatet av mallbearbetningen, vanligtvis i JSON-format som överensstämmer med GelatoConnects API-krav.

Enkel mallmappnings-exempel

Vi tar en titt på ett enkelt exempel som visar hur du kan omvandla en order från ditt systems format till GelatoConnects format:

Din systems orderdata:

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

Mallkartläggare:

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

Resulterande order som funkar med GelatoConnect:

{"orderReferenceId": "ORD-12345","orderType": "order","currency": "USD","shippingAddress": {"firstName": "John","lastName": "Doe","addressLine1": "123 Main St",\"city\": \"New York\",\"postCode\": \"10001\","country": "US",\"email\": \"[email protected]\",\"telefon\": \"+1234567890\"},"artiklar": [{"itemReferenceId": "ORD-12345-1",\"productUid\": \"flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor\","antal": 2,\"filer\": [{\"type\": \"default\","url": "https://example.com/images/poster1.jpg"}]}]}

Viktiga funktioner i mallkartläggaren

Variabelinterpolation

Använd dubbla klamrar för att lägga in värden från indata:

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

Filter

Använd filter (markerade med pipe-symbolen) för att göra om värden:

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

Vanliga filter är till exempel:

  • upper: Konvertera till versaler

  • lower: Konvertera till gemener

  • title: Skriv första bokstaven i varje ord med stor bokstav

  • trim: Ta bort tomrum i början och slutet

  • default: Tillhandahåll ett standardvärde om variabeln är odefinierad

  • js: Se till att värdet är korrekt formaterat för JSON

Styrstrukturer

Använd logik för att bara ta med innehåll när det behövs eller för att gå igenom listor:

{% for product in products %}// Bearbeta varje produkt{% endfor %}{% if customer.type == "business" %}// Lägg till fält som är specifika för verksamheten{% else %}// Inkludera individuella kundfält{% endif %}

Sökningar

Använd funktionen lookups() för att mappa värden mellan system, till exempel för att konvertera dina produkt-SKU:er till GelatoConnect produkt-UID:er:

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

Uppslagsfunktionaliteten kräver att du skapar uppslagstabeller i GelatoConnect, som mappar värdena från ditt system till GelatoConnects värden.

Skapa och testa mallmappningar

GelatoConnect erbjuder ett användarvänligt gränssnitt för att skapa och testa mallmappningar:

  1. Skapa en mall: Navigera till avsnittet Mallar och skapa en ny mall.

  2. Välj malltyp: Välj den malltyp som passar bäst (t.ex. Order Submit Request, Order Received notification).

  3. Definiera mallen: Skriv din Jinja2-mall i redigeraren.

  4. Testa med exempeldata: Tillhandahåll exempeldata och rendera mallen för att se resultatet.

  5. Felsök och förfina: Justera din mall efter behov baserat på det renderade resultatet.

  6. Spara och aktivera: När din mall fungerar korrekt, spara den för användning i din integration.

Vanliga användningsområden för mallkartläggare

1. Kartläggning av orderinlämning

Omvandla beställningar från ditt systems format till GelatoConnects API-format.

2. Statusuppdateringsaviseringar

Skapa mallar för olika orderstatushändelser (mottagen, skickad, levererad) så att dina system alltid är uppdaterade.

3. Anpassade Webhooks

Formatera data för att skicka till tredjepartssystem när specifika händelser inträffar.

4. Datanormalisering

Standardisera data från flera källor innan bearbetning.

Bästa praxis för mallkartläggare

  1. Börja enkelt: Ta en grundmall och bygg på med fler detaljer efter hand.

  2. Använd kommentarer: Lägg till kommentarer för att göra svåra förändringar enklare att förstå.

    jinja{# This extracts the first and last name from the full name #}

  3. Hantera saknade uppgifter: Se alltid till att ha standardvärden eller kontrollera om fält saknas.

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

  4. Testa gränsfall: Se till att dina mallar hanterar oväntade inmatningsformat eller värden.

  5. Använd uppslagningar för komplexa mappningar: Istället för att hårdkoda mappningar i din mall, använd uppslagningsfunktionen.

  6. Håll mallarna enkla: Skapa olika mallar för olika syften istället för att göra en enda krånglig mall.

  7. Validera output: Kontrollera alltid att din malloutput uppfyller GelatoConnect's API-krav.

Avancerade tekniker för mallkartläggning

När du blir mer bekväm med mallkartläggare kan du använda avancerade funktioner:

Makron

Skapa återanvändbara byggstenar för mallkod:

{% macro format_address(address) %}{"addressLine1": "####{{ address.street }}",\"city\": \"####{{ address.city }}\",\"postCode\": \"####{{ address.zip }}\",\"country\": \"####{{ address.country }}\"}{% endmacro %}// Använd det så här:\"shippingAddress\": ####{{ format_address(delivery) }}

Ställ in uttalanden

Skapa variabler i din mall:

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

Anpassade filter och funktioner

GelatoConnect stöder flera anpassade filter och funktioner utöver standard-Jinja2:

  • lookups(): För att översätta mellan olika värdesystem

  • js: För korrekt JSON-kodning

  • Olika datumformateringsfunktioner

Vill du lära dig mer?

Nu när du har koll på grunderna i Template Mappers i GelatoConnect är du redo att:

  1. Läs mer om hur du skapar mallar för ordermottagning

  2. Utforska Jinja2 exempel på mallar

  3. Ställ in postback-triggers som använder dina mallar

Relaterade artiklar
[Orderingång - GCW] Hur du ställer in sökningar
[Orderingång - GCW] Exempel på mallmappning
[Orderingång - GCW] Arbeta med Order API-slutpunkter
[Orderingång - GCW] Använda kundprodukter vs. ProductUID i API-beställningar
[Orderingång - GCW] Skapa mallar för orderingång
Fick du svar på din fråga?