Les modèles sont des éléments clés de GelatoConnect. Ils gèrent les flux de données entrants et sortants. Ils transforment les données reçues de vos clients en formats adaptés à votre workflow, puis mettent en forme les données sortantes de GelatoConnect pour répondre aux besoins des systèmes de vos clients. Ce guide vous accompagne pas à pas pour créer, tester et utiliser des modèles dans les deux sens d’échange de données, au sein de vos workflows de gestion de commandes.

Comprendre les modèles dans GelatoConnect

Les modèles dans GelatoConnect servent de plans qui définissent comment les données doivent être structurées, traitées et présentées. Ils gèrent deux flux de données essentiels :

Modèles de données entrantes

Ces modèles transforment les données provenant des systèmes de vos clients en formats que GelatoConnect peut traiter :

Demande de soumission de commande : Convertit les données de commande client au format interne de GelatoConnect
Annuler la demande : Formate les demandes d'annulation pour qu'elles soient comprises par GelatoConnect

Modèles de données sortantes

Ces modèles formatent les données envoyées depuis GelatoConnect vers vos clients ou leurs systèmes :

Formatage des réponses : Structure les réponses API aux soumissions ou annulations de commandes
Notifications d'événements : Crée des messages standardisés pour les mises à jour de statut des commandes
Postbacks : Formate les données envoyées aux systèmes externes lorsque les statuts des commandes changent

Tous les modèles utilisent le langage de modélisation Jinja2, qui offre des fonctionnalités puissantes pour la transformation des données, la logique conditionnelle et la génération de contenu dynamique.

Types de modèles que vous pouvez créer

GelatoConnect prend en charge plusieurs types de modèles pour différentes directions de flux de données :

Modèles de données entrantes (Client → GelatoConnect)

Demande d'envoi de commande : Transforme les données de commande client au format GelatoConnect
Annuler la demande : Transforme les demandes d'annulation des clients au format GelatoConnect

Modèles de données sortantes (GelatoConnect → Client)

Envoyer la réponse : Formate les réponses envoyées après la soumission de la commande
Annuler la réponse : Formate les réponses envoyées après les demandes d'annulation
Webhook : génère des messages JSON pour informer des changements de statut de commande sur des systèmes externes
Email : Formate les notifications par email pour différents événements de commande

La direction du flux de données est essentielle à comprendre lors de la création de modèles, car elle détermine quelles données sont disponibles et comment elles doivent être structurées.

Guide étape par étape pour créer un modèle

1. Rendez-vous dans la section Modèles

Connectez-vous à votre compte GelatoConnect
Allez dans Flux de travail > Réception des commandes > Modèles
Cliquez sur le bouton Ajouter un modèle pour commencer à créer un nouveau modèle

2. Choisissez votre type de modèle

Sélectionnez le type de modèle que vous souhaitez créer :

Pour les intégrations API, vous aurez généralement besoin des modèles Order Submit Request, Submit Response et Cancel Response.
Pour les notifications, sélectionnez Webhook ou Email

3. Définir le format du modèle

Choisissez le format de votre modèle :

JSON : Le plus courant pour les intégrations d’API et les Webhook
XML : Utilisé pour certains systèmes anciens
Texte simple : Généralement utilisé pour les modèles d'e-mails

4. Générer un exemple de données d'entrée

Pour créer un modèle efficace, vous devez comprendre quelles données seront disponibles :

Cliquez sur le bouton Générer le modèle
Sélectionnez Ajouter un exemple de charge utile pour fournir des données de test
Choisissez le type d’événement approprié dans le menu déroulant :
- Commande reçue
- Commande échouée
- Commande annulée
- Commande retournée
- Commande fabriquée
- Commande livrée
- Commande expédiée
- Commande en cours de livraison

Le système remplira un exemple de charge utile avec des données typiques pour cet événement, que vous pourrez utiliser comme référence lors de la création de votre modèle.

5. Créez votre Template Mapper

Le Template Mapper est l'endroit où vous définissez comment les données sont transformées entre les formats :

Dans la section Template Mapper, rédigez votre modèle en utilisant la syntaxe Jinja2.
Faites référence aux données de l'entrée en utilisant des doubles accolades : ##{{ variable }}
Ajoutez des filtres de mise en forme avec le symbole pipe : ##{{ variable|js }} (le filtre js adapte les chaînes pour le format JSON)
Utilisez des structures de contrôle comme {% if %}, {% for %}, et {% set %} pour la logique conditionnelle et les boucles

Points à prendre en compte pour l’orientation du modèle

Le contenu de votre modèle variera selon que vous traitez des données entrantes ou sortantes :

Pour les modèles de données entrants (client → GelatoConnect) :

Concentrez-vous sur l'extraction de données à partir de formats personnalisés pour chaque client
Associez les noms de champs Personnalisé aux noms de champs standard de GelatoConnect
Validez et transformez les données pour qu'elles répondent aux exigences de GelatoConnect
Gérez tous les besoins particuliers de mise en forme ou de conversion de données

Pour les modèles de données sortantes (GelatoConnect → Client) :

Organisez les données selon les attentes du système du client
Incluez tous les champs nécessaires pour l’intégration du client
Formatez les dates, les montants en devise et d'autres données selon les préférences du client
Ajoutez des identifiants ou des références propres à chaque client

Exemple : modèle de Webhook pour commande reçue

Voici un exemple de modèle pour un Webhook « Commande reçue » :

{
  "event": "Order Received",
  "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": "The order has been received."
}

Ce modèle génère une structure JSON contenant les détails de la commande et parcourt tous les articles de la commande.

6. Rendre et vérifier le modèle

Après avoir créé votre modèle :

Cliquez sur le bouton Render pour générer le modèle.
Vérifiez le résultat dans le volet d’aperçu
Vérifiez que toutes les données sont correctement formatées et qu'il n'y a aucune erreur de syntaxe.
Vérifiez s'il manque des champs ou si certains champs sont mal formatés

7. Testez votre modèle

Les tests sont essentiels pour garantir que votre modèle fonctionne correctement :

Attribuez un nom à votre test dans la section Modèle de test
Cliquez sur Exécuter le test pour appliquer le modèle aux données d’exemple.
Vérifiez que le statut indique réussi
Vérifiez le résultat pour vous assurer qu'il correspond à vos attentes.

8. Enregistrez votre modèle

Une fois que vous êtes satisfait du modèle :

Donnez un nom clair et évocateur à votre modèle
Cliquez sur Ajouter un modèle ou Enregistrer les modifications pour sauvegarder.
Le modèle sera désormais disponible pour être utilisé dans les déclencheurs et les configurations de workflow.

Utiliser des modèles avec des déclencheurs

Les modèles sont le plus souvent utilisés avec des déclencheurs pour automatiser les notifications lorsque certains événements se produisent :

1. Créer un déclencheur

Allez dans Flux de travail > Réception des commandes > Déclencheurs
Cliquez sur Ajouter un déclencheur
Sélectionnez le client auquel ce déclencheur s’applique
Nommez votre déclencheur (par exemple, "Notification de commande reçue")
Sélectionnez l’événement qui déclenchera l’action (par exemple, "Commande reçue")

2. Configurez la méthode de livraison

Choisissez comment vous souhaitez recevoir les notifications :

URL : Envoyer un webhook à un système externe
- Spécifiez l'URL de destination
- Sélectionnez la méthode POST ou GET
- Choisissez le format JSON ou XML
- Configurez les options de nouvelle tentative si vous le souhaitez
Email : Envoyez une notification par email
- Saisissez les adresses e-mail des destinataires
- Ajoutez un objet
- Préciser le nom et l'adresse de l'expéditeur

3. Sélectionnez votre modèle

Dans le menu déroulant Modèle, sélectionnez le modèle que vous avez créé précédemment
Si aucun modèle n'existe, vous pouvez en créer un directement dans la configuration du déclencheur en utilisant la même interface décrite ci-dessus

Création de modèles directement à partir de déclencheurs

Pour plus de simplicité, vous pouvez aussi créer des modèles lors de la configuration des déclencheurs :

Lors de la création d'un déclencheur, au lieu de sélectionner un modèle existant, cliquez sur Créer un modèle
Définissez le format du modèle (JSON, XML ou texte brut)
Utilisez l’éditeur de modèles pour créer votre modèle comme expliqué ci-dessus.
Enregistrez le modèle, et il sera automatiquement sélectionné pour ce déclencheur

Cette méthode est pratique pour créer rapidement un modèle lorsque vous configurez déjà un déclencheur.

Lier des modèles aux points de terminaison de l’API

Lorsque vous envoyez des commandes via l’API, il est souvent nécessaire d’adapter les données entre votre format et celui de GelatoConnect. Les modèles facilitent cette transformation, mais vous devez relier explicitement votre modèle au point de terminaison de l’API pour qu’il soit pris en compte.

Comment associer un modèle à un point de soumission de commande :

Accédez à votre liste de connecteurs, puis cliquez sur le lien Modifier à côté du point de terminaison d’envoi de commande.
Sur la page de configuration de l'endpoint, repérez la section Modèle d'endpoint
Sélectionnez votre modèle de soumission de commande dans le menu déroulant
Cliquez sur le bouton Définir l'endpoint en haut à droite de la page
Cliquez sur Enregistrer les modifications en haut à droite pour appliquer votre configuration

Après avoir terminé ces étapes, toutes les commandes envoyées à ce point de terminaison utiliseront votre modèle pour transformer les données avant traitement. Cela garantit que le format de votre système est bien converti dans le format attendu par GelatoConnect.

Sans cette configuration, votre modèle ne sera pas appliqué, même s'il existe et qu'il est correctement conçu. Cela peut entraîner des échecs de validation de commande si le format de vos données ne correspond pas exactement aux exigences de GelatoConnect.

Techniques avancées de modèles

Utiliser les recherches

Les recherches sont particulièrement utiles pour la correspondance de données dans les deux sens entre différents systèmes. Leur fonctionnement varie selon la direction du modèle :

Pour les modèles entrants (client → GelatoConnect) :

Associez les valeurs spécifiques du client aux valeurs standardisées de GelatoConnect :

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

Pour les modèles sortants (GelatoConnect → Client) :

Transformez les valeurs internes de GelatoConnect aux formats attendus par les clients :

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

Logique conditionnelle

Utilisez des conditions pour inclure ou formater des données différemment selon les circonstances :

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

Attribution de variable

Créez des variables pour rendre les expressions complexes plus simples :

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

Boucles avec des objets complexes

Naviguez dans des structures de données imbriquées :

"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 %}
]

Bonnes pratiques pour les modèles

Nommage basé sur la direction

Utilisez des noms clairs et descriptifs qui indiquent à la fois l'objectif et la direction du flux de données
Pour les modèles entrants : Incluez des préfixes comme « IN_ » ou des suffixes comme « _Request »
Pour les modèles sortants : utilisez des préfixes comme "OUT_", ou des suffixes comme "_Response" ou "_Notification".
Inclure le nom du client pour les modèles personnalisés
Utilisez des modèles de nommage cohérents pour faciliter la recherche de modèles

Gestion des erreurs

Définissez des valeurs par défaut pour éviter les références nulles.
Utilisez le filtre default pour les valeurs manquantes : ##{{ variable|default('N/A') }}
Utilisez des blocs try/except pour les parties du code qui pourraient poser problème

Maintenance

Ajoutez des commentaires pour expliquer la logique complexe : {# Ceci gère le cas particulier des commandes internationales #}
Gardez les modèles modulaires et axés sur des objectifs spécifiques
Mettre à jour les modèles lorsque les structures de données ou les exigences changent

Test

Testez avec différents scénarios de données, y compris les cas limites
Vérifiez les modèles avec des données de production réelles lorsque c'est possible
Créez des tests complets pour les modèles critiques

Résoudre les problèmes de modèles

Problèmes courants et solutions

Problème	Cause possible	Solution
Erreur de syntaxe	Parenthèses ou guillemets mal appariés	Vérifiez attentivement la syntaxe du modèle ; assurez-vous que chaque balise ouvrante a bien sa balise fermante correspondante.
Données manquantes	Référencement de champs qui n'existent pas	Vérifiez les noms des champs par rapport aux données saisies, puis ajoutez des valeurs par défaut pour les champs optionnels.
Problèmes de mise en forme	Utilisation incorrecte du filtre	Vérifiez que vous utilisez correctement les filtres comme `js`, `json` ou `xml`.
Modèle non appliqué	Modèle non associé à un déclencheur	Vérifiez la configuration du déclencheur et la sélection du modèle
Erreurs d'accès aux données imbriquées	Chemin incorrect vers les propriétés imbriquées	Vérifiez la structure des données et ajustez les chemins des propriétés en conséquence.
Erreurs d’association des champs	Noms de champs incorrects pour les données entrantes ou sortantes	Pour les modèles entrants, vérifiez les noms des champs client ; pour les modèles sortants, assurez-vous que le format de réponse attendu est respecté.
Problèmes de transformation des données	Formats de données incompatibles	Assurez-vous de convertir correctement les types de données entre les systèmes (dates, nombres, etc.)

Conseils de débogage

Utilisez souvent le bouton Render pendant le développement pour repérer rapidement les erreurs.
Ajouter une sortie de débogage temporaire pour examiner les valeurs des variables
Vérifiez les fautes de frappe dans les noms des champs, qui sont une source fréquente d'erreurs
Gardez à l'esprit que Jinja2 fait la différence entre les majuscules et les minuscules lorsque vous faites référence à des variables.

[Order Intake - GCW] Créer des modèles pour la prise de commandes