I template sono elementi fondamentali in GelatoConnect: gestiscono sia i flussi di dati in entrata che quelli in uscita. Trasformano i dati dei clienti in arrivo in formati che il tuo flusso di lavoro può elaborare e adattano i dati in uscita da GelatoConnect per soddisfare le esigenze dei sistemi dei tuoi clienti. Questa guida ti accompagnerà nella creazione, nel test e nell’implementazione dei template per entrambe le direzioni dello scambio dati nei tuoi flussi di gestione ordini.
Capire i template in GelatoConnect
I template in GelatoConnect sono come progetti guida che definiscono come i dati devono essere organizzati, gestiti e presentati. Si occupano di due flussi di dati fondamentali:
Template dati in arrivo
Questi modelli trasformano i dati provenienti dai sistemi dei tuoi clienti in formati che GelatoConnect può elaborare:
Richiesta di invio ordine: trasforma i dati dell’ordine del cliente nel formato interno di GelatoConnect
Annulla richiesta: prepara le richieste di annullamento in modo che siano comprese da GelatoConnect
Template dati in uscita
Questi modelli formattano i dati inviati da GelatoConnect ai tuoi clienti o ai loro sistemi:
Formattazione delle risposte: organizza le risposte API per gli invii o le cancellazioni degli ordini.
Notifiche sugli eventi: crea messaggi standardizzati per aggiornamenti sullo stato degli ordini
Postbacks: definisce il formato dei dati inviati a sistemi esterni quando lo stato di un ordine cambia
Tutti i template usano il linguaggio di template Jinja2, che offre strumenti potenti per trasformare i dati, gestire logiche condizionali e creare contenuti dinamici.
Tipi di template che puoi creare
GelatoConnect supporta diversi tipi di template per gestire vari flussi di dati:
Template dati in arrivo (Cliente → GelatoConnect)
Richiesta di invio ordine: trasforma i dati dell’ordine del cliente nel formato di GelatoConnect
Annulla richiesta: trasforma le richieste di annullamento dei clienti nel formato di GelatoConnect.
Modelli di dati in uscita (GelatoConnect → cliente)
Invia risposta: formatta le risposte inviate dopo l'invio dell'ordine
Annulla risposta: mostra come vengono formattate le risposte inviate dopo una richiesta di annullamento
Webhook: crea payload JSON per notifiche a sistemi esterni quando cambia lo stato di un ordine
Email: Crea notifiche email per diversi eventi relativi agli ordini
Capire la direzione in cui scorrono i dati è fondamentale quando crei template, perché ti permette di sapere quali dati hai a disposizione e come organizzarli al meglio.
Guida pratica per creare un template
1. Vai alla sezione Template
Accedi al tuo account GelatoConnect
Vai su Workflow > Order Intake > Templates
Fai clic sul pulsante Aggiungi modello per iniziare a creare un nuovo modello
2. Scegli il tipo di template
Seleziona il tipo di template che vuoi creare:
Per le integrazioni API, di solito ti serviranno i template Order Submit Request, Submit Response e Cancel Response.
Per le notifiche, scegli Webhook o Email
3. Definisci il formato del template
Scegli il formato per il tuo template:
JSON: il formato più usato per integrazioni API e webhook
XML: usato in alcuni sistemi più datati
Testo semplice: usato di solito nei modelli di email
4. Genera un esempio di payload in input
Per creare un template efficace, è importante capire quali dati saranno disponibili:
Clicca sul pulsante Genera modello
Seleziona Aggiungi payload di input di esempio per inserire dati di prova
Scegli il tipo di evento giusto dal menu a tendina:
Ordine ricevuto
Ordine non riuscito
Ordine annullato
Ordine restituito
Ordine prodotto
Ordine consegnato
Ordine spedito
Ordine in viaggio
Il sistema compilerà un esempio di payload con dati tipici per quell’evento, che puoi usare come riferimento quando crei il tuo template.
5. Crea il tuo Template Mapper
Il Template Mapper è il luogo dove decidi come i dati vengono trasformati tra diversi formati:
Nella sezione Template Mapper, scrivi il tuo template usando la sintassi Jinja2
Usa i dati di riferimento dal payload di input usando le doppie parentesi graffe:
####{{ variable }}Aggiungi filtri di formattazione usando il simbolo della barra verticale:
####{{ variable|js }}(il filtrojsadatta le stringhe per JSON)Usa strutture di controllo come
{% if %},{% for %}e{% set %}per gestire condizioni e cicli
Cosa considerare quando scegli la direzione del template
Il contenuto del tuo modello cambierà a seconda che tu stia gestendo dati in entrata o in uscita:
Per i template dati in ingresso (cliente → GelatoConnect):
Concentrati sull’estrazione dei dati da formati specifici per ogni cliente
Abbina i nomi dei campi personalizzati ai nomi standard dei campi di GelatoConnect
Verifica e trasforma i dati per soddisfare i requisiti di GelatoConnect
Gestisci eventuali esigenze particolari di formattazione o conversione dei dati
Per i template dati in uscita (GelatoConnect → Cliente):
Organizza i dati in base a come il sistema del cliente si aspetta di riceverli
Includi tutti i campi necessari per l'integrazione del cliente
Formatta date, valori in valuta e altri dati in base alle preferenze del cliente
Aggiungi eventuali identificativi o riferimenti specifici del cliente
Esempio: modello di Webhook per ordine ricevuto
Ecco un esempio di template per un webhook "Ordine ricevuto":
{ "event": "Ordine ricevuto", "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": "Abbiamo ricevuto il tuo ordine."}Questo modello crea una struttura JSON con i dettagli dell’ordine e scorre tutti gli articoli presenti nell’ordine.
6. Visualizza e controlla il template
Dopo che hai creato il tuo modello:
Fai clic sul pulsante Render per compilare il modello
Controlla il risultato nel riquadro di anteprima
Verifica che tutti i dati siano formattati correttamente e che non ci siano errori di sintassi
Controlla se ci sono campi mancanti o compilati in modo errato
7. Metti alla prova il tuo template
Testare è fondamentale per assicurarti che il tuo template funzioni come si deve:
Dai un nome al tuo test nella sezione Test Template
Fai clic su Esegui test per provare il modello con i dati di esempio
Verifica che lo Status sia indicato come Passed
Controlla il risultato per vedere se corrisponde a quello che ti aspettavi
8. Salva il tuo modello
Quando sei soddisfatto del template:
Dai al tuo template un nome che lo descriva bene
Fai clic su Aggiungi modello o Salva modifiche per salvare.
Il modello sarà ora disponibile per essere usato nei trigger e nelle configurazioni dei workflow.
Usare i template con i trigger
I template vengono usati soprattutto insieme ai trigger per automatizzare le notifiche quando succedono eventi specifici:
1. Crea un trigger
Vai su Workflow > Order Intake > Triggers
Fai clic su Aggiungi trigger
Seleziona il cliente a cui si applica questo trigger
Dai un nome al tuo trigger (ad esempio: "Notifica ordine ricevuto")
Seleziona l’evento che farà scattare il trigger (ad esempio: "Ordine ricevuto")
2. Configura il metodo di consegna
Scegli come vuoi ricevere le notifiche:
URL: invia un Webhook a un sistema esterno
Specifica l'URL di destinazione
Scegli il metodo POST o GET
Scegli il formato JSON o XML
Configura le opzioni di ripetizione se vuoi
Email: Invia una notifica via email
Inserisci gli indirizzi email dei destinatari
Aggiungi un oggetto
Specifica nome e indirizzo del mittente
3. Scegli il tuo modello
Dal menu a discesa Template, scegli il template che hai creato prima
Se non esiste un modello, puoi crearne uno direttamente nella configurazione del trigger usando la stessa interfaccia descritta sopra.
Crea template direttamente dai trigger
Per comodità, puoi anche creare dei modelli mentre imposti i trigger:
Quando crei un trigger, invece di scegliere un modello già esistente, clicca su Crea modello.
Scegli il formato del template: JSON, XML o testo semplice
Usa l’editor dei modelli per creare il tuo modello come descritto sopra
Salva il modello; verrà selezionato automaticamente per questo trigger.
Questo metodo è perfetto per creare un template al volo mentre stai già impostando un trigger.
Collegare i template agli endpoint API
Quando invii ordini tramite API, spesso dovrai trasformare i dati dal tuo formato a quello di GelatoConnect. I template si occupano di questa trasformazione, ma devi collegare esplicitamente il tuo template all'endpoint API perché venga applicato.
Come collegare un template a un endpoint di invio ordine:
Vai alla tua lista di connettori e clicca sul collegamento Modifica accanto all'endpoint di invio ordine.
Nella pagina di configurazione dell'endpoint, trova la sezione Modello endpoint
Seleziona il tuo modello di invio ordine dal menu a tendina
Fai clic sul pulsante Imposta endpoint in alto a destra nella pagina
Fai clic su Salva modifiche in alto a destra per applicare la tua configurazione
Dopo aver completato questi passaggi, tutte le richieste d’ordine inviate a questo endpoint useranno il tuo template per trasformare i dati prima dell’elaborazione. Così il formato del tuo sistema verrà convertito correttamente nel formato previsto da GelatoConnect.
Senza questa configurazione, il tuo template non verrà applicato anche se esiste ed è stato progettato correttamente; questo può causare errori nella validazione degli ordini se il formato dei tuoi dati non corrisponde esattamente ai requisiti di GelatoConnect.
Tecniche avanzate per template
Come usare le ricerche
Le lookups sono particolarmente utili per mappare i dati in entrambe le direzioni tra i sistemi. Funzionano in modo diverso a seconda della direzione del template:
Per i template in arrivo (cliente → GelatoConnect):
Collega i valori specifici dei clienti ai valori standardizzati di GelatoConnect:
{% set shipMethod = lookups({"shipping_code": order.shipping.method}, strict=False, default="normale") %} "shipmentMethodUid": ####{{ shipMethod|js }},Per i template in uscita (GelatoConnect → cliente):
Trasforma i valori interni di GelatoConnect nei formati che i clienti si aspettano:
{% set customerShippingCode = lookups({"gelatoShipMethod": shipment.shipmentMethodUid}, strict=False, default=shipment.shipmentMethodUid) %} "shipping_method": ####{{ customerShippingCode|js }},Logica condizionale
Usa le condizioni per includere o formattare i dati in modo diverso a seconda della situazione:
{% if item.fulfillmentStatus == "shipped" %} "trackingNumber": "####{{ item.trackingCode }}", "trackingUrl": "####{{ item.trackingUrl }}",{% endif %}Assegnazione di variabile
Crea variabili per rendere più semplici le espressioni complesse:
{% set fullName = customer.firstName + " " + customer.lastName %} "recipientName": "####{{ fullName }}",Cicli con oggetti complessi
Esplora strutture dati annidate:
"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 %}]Le migliori pratiche per i template
Convenzioni di denominazione basate sulla direzione
Scegli nomi chiari e descrittivi che mostrino sia lo scopo che la direzione del flusso dei dati
Per i template in arrivo: aggiungi prefissi come "IN_" o suffissi come "_Request"
Per i template in uscita: usa prefissi come "OUT_" o suffissi come "_Response" o "_Notification"
Inserisci il nome del cliente per i template personalizzati
Usa nomi coerenti per trovare facilmente i tuoi modelli
Gestione degli errori
Imposta valori predefiniti per evitare errori dovuti a riferimenti nulli
Usa il filtro
defaultper i valori mancanti:####{{ variable|default('N/A') }}Usa i blocchi
try/exceptquando il codice potrebbe creare problemi
Manutenzione
Aggiungi commenti per spiegare la logica complessa:
{# Questo gestisce il caso particolare degli ordini internazionali #}Mantieni i template modulari e concentrati su scopi specifici
Aggiorna i modelli quando cambiano le strutture dei dati o le esigenze
Test in corso
Metti alla prova diversi scenari di dati, anche quelli più particolari
Verifica i template con dati di produzione reali quando puoi
Crea test completi per i template fondamentali
Risolvere i problemi con i modelli
Problemi comuni e soluzioni pratiche
Problema | Possibile motivo | Soluzione |
Errore di sintassi | Parentesi o virgolette non corrispondenti | Controlla bene la sintassi del template: assicurati che tutti i tag di apertura abbiano il loro tag di chiusura corrispondente. |
Dati mancanti | Fare riferimento a campi che non esistono | Controlla che i nomi dei campi corrispondano ai dati ricevuti; aggiungi valori predefiniti per i campi opzionali |
Problemi di formattazione | Filtro usato nel modo sbagliato | Assicurati di usare correttamente i filtri come |
Template non applicato | Template non collegato al trigger | Verifica la configurazione del trigger e la selezione del template |
Errori nell'accesso ai dati annidati | Percorso errato verso le proprietà annidate | Controlla la struttura dei dati e adatta i percorsi delle proprietà di conseguenza |
Errori nell'associazione dei campi | Nomi dei campi errati per i dati in entrata o in uscita | Per i template in entrata, controlla i nomi dei campi cliente; per quelli in uscita, verifica il formato di risposta previsto. |
Problemi nella trasformazione dei dati | Formati di dati non compatibili | Assicurati che i dati vengano convertiti correttamente tra i sistemi (date, numeri, ecc.). |
Consigli per risolvere i problemi
Usa spesso il pulsante Render durante lo sviluppo: così puoi individuare subito eventuali errori.
Aggiungi un output di debug temporaneo per controllare i valori delle variabili
Controlla che non ci siano errori di battitura nei nomi dei campi; spesso sono la causa principale dei problemi.
Ricorda che Jinja2 fa distinzione tra maiuscole e minuscole quando usi le variabili