Cosa sono i Template Mapper?
I template mapper in GelatoConnect sono strumenti potenti che trasformano i dati dal formato del tuo sistema a quello di GelatoConnect. Sono come traduttori: fanno sì che le informazioni viaggino senza intoppi tra sistemi diversi, anche se ognuno organizza i dati a modo suo.
Che tu stia inviando ordini a GelatoConnect o ricevendo aggiornamenti sui cambiamenti di stato degli ordini, i template mapper ti permettono di convertire i formati dei dati senza dover modificare i tuoi sistemi attuali.
Perché scegliere i Template Mapper?
I template mapper risolvono diversi problemi comuni di integrazione:
Strutture dati diverse: il tuo sistema e GelatoConnect potrebbero organizzare le stesse informazioni in modo differente.
Differenze nei nomi dei campi: il tuo sistema potrebbe chiamare l'indirizzo di spedizione "delivery_address", mentre GelatoConnect usa "shippingAddress".
Conversioni di formato: Potresti dover cambiare il formato dei dati, ad esempio modificare il formato delle date o trasformare le unità di misura.
Selezione dei campi: puoi scegliere di includere solo alcuni campi specifici dai tuoi dati quando li invii a GelatoConnect.
Logica condizionale: Potresti dover applicare regole di mappatura diverse a seconda di alcune condizioni, come il tipo di ordine o il paese di destinazione.
Come funzionano i Template Mapper
GelatoConnect usa il linguaggio di template Jinja2 per i suoi template mapper. Questo linguaggio, potente e flessibile, ti permette di:
Estrai valori: recupera i dati dal tuo formato di input
Trasforma i dati: usa funzioni e logica per modificarli
Risultato finale: crea il risultato finale nel formato previsto da GelatoConnect
Un template mapper prende un input (i tuoi dati) e crea un output (dati compatibili con GelatoConnect) seguendo una serie di regole di trasformazione che decidi tu.
Componenti Template Mapper
Un tipico template mapper in GelatoConnect è composto da questi elementi:
1. Inserisci i dati
Questi sono i dati di partenza che vuoi trasformare. Potrebbero essere:
Dati degli ordini dal tuo sistema e-commerce
Informazioni sui clienti dal tuo CRM
Dettagli prodotto dal tuo catalogo
2. Definizione del template
Qui decidi come trasformare i dati in ingresso. Con la sintassi Jinja2, puoi specificare:
Quali campi vuoi estrarre dall'input
Eventuali trasformazioni da applicare
La struttura del risultato
3. Formato di output
Il risultato dell'elaborazione del template, di solito in formato JSON che rispetta i requisiti dell’API di GelatoConnect.
Esempio base di Template Mapper
Vediamo insieme un esempio semplice che trasforma un ordine dal formato del tuo sistema a quello di GelatoConnect:
I dati degli ordini del tuo sistema:
{"order_id": "ORD-12345","customer": {"name": "John Doe","email": "[email protected]"},"consegna": {"street": "Via Principale 123","city": "New York","zip": "10001","country": "US"},"prodotti": [{"sku": "POSTER-A4-MATTE","qty": 2,"image_url": "https://example.com/images/poster1.jpg"}]}Template Mapper:
{"orderReferenceId": "####{{ order_id }}","orderType": "ordine","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 }}","telefono": "+1234567890"},"items": [{% for product in products %}{"itemReferenceId": "####{{ order_id }}-####{{ loop.index }}","productUid": "####{{ lookups({'sku': product.sku}, strict=False, default='') }}","quantità": ####{{ product.qty }},"file": [{"type": "default","url": "####{{ product.image_url }}"}]}{% if not loop.last %},{% endif %}{% endfor %}]}Ordine compatibile con GelatoConnect ottenuto:
{"orderReferenceId": "ORD-12345","orderType": "ordine","currency": "USD","shippingAddress": {"firstName": "John","lastName": "Doe","addressLine1": "Via Principale 123","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/mq-non-patinato_cl_4-0_ct_none_prt_none_sft_none_set_none_hor","quantità": 2,"file": [{"type": "default","url": "https://example.com/images/poster1.jpg"}]}]}Funzionalità principali di Template Mapper
Interpolazione di variabili
Usa le doppie parentesi graffe per inserire i valori dai dati di input:
jinja"orderReferenceId": "####{{ order_id }}"Filtri
Applica trasformazioni ai valori usando i filtri (indicati dal simbolo della barra verticale):
jinja"firstName": "####{{ customer.name | title }}"I filtri più usati sono:
upper: Trasforma in maiuscololower: Converti in minuscolotitle: Usa la maiuscola per la prima lettera di ogni parolaFinitura: rimuovi gli spazi all'inizio e alla finedefault: Usa un valore predefinito se la variabile non è definitajs: Assicurati che il valore sia formattato correttamente per JSON
Strutture di controllo
Usa la logica per mostrare contenuti solo quando servono o per scorrere gli elenchi:
{% for product in products %}// Elabora ogni prodotto{% endfor %}{% if customer.type == "business" %}// Includi i campi specifici per l'attività{% else %}// Includi i campi specifici del cliente{% endif %}Ricerche
Usa la funzione lookups() per collegare i valori tra diversi sistemi, ad esempio per trasformare i tuoi SKU di prodotto nei codici UID dei prodotti su GelatoConnect:
jinja"productUid": "####{{ lookups({'sku': product.sku}, strict=False, default='') }}"La funzione di ricerca richiede la creazione di tabelle di corrispondenza su GelatoConnect, che collegano i valori del tuo sistema a quelli di GelatoConnect.
Creare e testare i Template Mapper
GelatoConnect offre un'interfaccia intuitiva per creare e testare i template mapper:
Crea un template: vai nella sezione Template e crea un nuovo template.
Scegli il tipo di template: seleziona il tipo di template più adatto (ad esempio, richiesta di invio ordine, notifica di ordine ricevuto).
Definisci il template: scrivi il tuo template Jinja2 nell'editor.
Prova con dati di esempio: inserisci dei dati di esempio e visualizza subito il risultato del template.
Metti a punto e perfeziona: modifica il tuo modello in base a come viene visualizzato il risultato.
Salva e attiva: quando il tuo modello funziona come desideri, salvalo per usarlo nella tua integrazione.
Esempi pratici di utilizzo dei Template Mapper
1. Mappatura dell'invio degli ordini
Trasforma gli ordini dal formato del tuo sistema al formato API di GelatoConnect.
2. Notifiche di aggiornamento dello stato
Crea template personalizzati per i diversi stati dell’ordine (ricevuto, spedito, consegnato) per tenere aggiornati i tuoi sistemi.
3. Webhook personalizzati
Prepara i dati da inviare ai sistemi di terze parti quando si verificano eventi specifici.
4. Normalizzazione dei dati
Standardizza i dati provenienti da più fonti prima di elaborarli.
Le migliori pratiche per chi usa i Template Mapper
Parti dalle basi: scegli un modello semplice e aggiungi dettagli man mano che vai avanti.
Usa i commenti: aggiungi commenti per spiegare le trasformazioni più complesse.
jinja{# Questo estrae il nome e il cognome dal nome completo #}Gestisci i dati mancanti: offri sempre valori predefiniti o controlla i campi opzionali.
jinja"additionalInfo": "####{{ customer.notes | default('') }}"Metti alla prova i casi limite: assicurati che i tuoi template gestiscano formati o valori imprevisti.
Usa le Lookups per mappature complesse: invece di inserire le mappature direttamente nel tuo template, sfrutta la funzionalità delle lookups.
Concentra i template su un obiettivo: crea template diversi per ogni esigenza invece di uno solo complicato.
Verifica l'output: controlla sempre che il risultato del tuo template rispetti i requisiti dell'API di GelatoConnect.
Tecniche avanzate per il Template Mapper
Quando prendi confidenza con i template mappers, puoi sfruttare le funzioni avanzate:
Macro
Definisci blocchi riutilizzabili di codice modello:
{% macro format_address(address) %}{"addressLine1": "####{{ address.street }}","city": "####{{ address.city }}","postCode": "####{{ address.zip }}","country": "####{{ address.country }}"}{% endmacro %}// Poi usalo così:"shippingAddress": ####{{ format_address(delivery) }}Imposta dichiarazioni
Crea variabili all'interno del tuo template:
{% set full_name = customer.firstName + ' ' + customer.lastName %}"recipientName": "####{{ full_name }}"Filtri e funzioni personalizzate
GelatoConnect offre diversi filtri e funzioni personalizzate oltre a quelle standard di Jinja2:
lookups(): Per collegare sistemi di valori diversijs: Per una corretta gestione dell'escape in JSONVarie funzioni per la formattazione delle date
Vuoi saperne di più?
Ora che hai capito le basi dei Template Mappers in GelatoConnect, sei prontə a:
Scopri di più su come creare template per la raccolta ordini
Scopri alcuni esempi di template Jinja2
Imposta i trigger di postback che usano i tuoi modelli