Qu'est-ce qu'un template mapper ?

Les mappers de modèles dans GelatoConnect sont des outils puissants qui transforment les données entre le format de votre système et celui de GelatoConnect. Ils jouent le rôle de traducteurs, garantissant une circulation fluide des informations entre différents systèmes, peu importe la façon dont chaque système organise ses données.

Que vous soumettiez des commandes à GelatoConnect ou que vous receviez des mises à jour concernant les changements de statut des commandes, les mappeurs de modèles permettent de convertir les formats de données sans nécessiter de modifications de vos systèmes existants.

Pourquoi choisir les Template Mappers ?

Les mappeurs de modèles résolvent plusieurs défis d'intégration courants :

Structures de données différentes : Votre système et GelatoConnect peuvent organiser les mêmes informations de manière différente.
Différences dans la dénomination des champs : Votre système peut appeler une adresse de livraison « delivery_address », alors que GelatoConnect utilise « shippingAddress ».
Conversions de format : Vous pourriez avoir besoin de convertir des formats de données, comme modifier des formats de date ou transformer des unités de mesure.
Mappage sélectif des champs : Vous pourriez vouloir inclure uniquement des champs spécifiques de vos données lors de l'envoi vers GelatoConnect.
Logique conditionnelle : Vous pourriez avoir besoin d'appliquer différentes règles de mappage selon certaines conditions, comme le type de commande ou le pays de destination.

Comment fonctionnent les mappeurs de modèles

GelatoConnect utilise le langage de template Jinja2 pour ses mappeurs de modèles. Ce langage puissant et flexible vous permet de :

Extraire les valeurs : Récupérer les données de votre format d'entrée
Transformer les données : Utilisez des fonctions et de la logique pour modifier les données
Sortie de construction : Créer le résultat final au format attendu par GelatoConnect

Un mappeur de modèle prend une entrée (vos données) et produit une sortie (données compatibles avec GelatoConnect) selon un ensemble de règles de transformation que vous définissez.

Composants du mappeur de modèles

Un modèle type de mappage de gabarit dans GelatoConnect comprend les éléments suivants :

1. Saisir les données

Voici les données source que vous souhaitez transformer. Cela pourrait être :

Données de commande depuis votre système de e-commerce
Informations client issues de votre CRM
Détails du produit issus de votre catalogue

2. Définition du modèle

C'est ici que vous définissez comment transformer les données d'entrée. En utilisant la syntaxe Jinja2, vous indiquez :

Quels champs extraire de l'entrée
Transformations à appliquer
La façon dont le résultat est organisé

3. Format de sortie

Le résultat du traitement du modèle, généralement au format JSON, conforme aux exigences de l’API de GelatoConnect.

Exemple de base de mappeur de modèle

Examinons un exemple simple qui convertit une commande du format de votre système au format GelatoConnect :

Données de commande de votre système :

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

Mappeur de modèles :

{
"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 }}",
"country": "{{ delivery.country }}",
"email": "{{ customer.email }}",
"phone": "+1234567890"
},
"items": [
{% for product in products %}
{
"itemReferenceId": "{{ order_id }}-{{ loop.index }}",
"productUid": "{{ lookups({'sku': product.sku}, strict=False, default='') }}",
"quantity": {{ product.qty }},
"files": [
{
"type": "default",
"url": "{{ product.image_url }}"
}
]
}{% if not loop.last %},{% endif %}
{% endfor %}
]
}

Commande compatible avec GelatoConnect obtenue :

{
"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]",
"phone": "+1234567890"
},
"items": [
{
"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",
"quantity": 2,
"files": [
{
"type": "default",
"url": "https://example.com/images/poster1.jpg"
}
]
}
]

Principales fonctionnalités du mappeur de modèles

Interpolation de variables

Utilisez des doubles accolades pour insérer des valeurs à partir des données saisies :

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

Filtres

Appliquez des transformations aux valeurs avec des filtres (indiqués par le symbole de barre verticale) :

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

Les filtres courants incluent :

upper : Mettre en majuscules
minuscules : Convertir en minuscules
title : Mettez une majuscule à la première lettre de chaque mot
trim : Supprimer les espaces blancs au début et à la fin
default : Fournissez une valeur par défaut si la variable n’est pas définie
js : Assurez-vous que la valeur est correctement formatée pour JSON.

Structures de contrôle

Utilisez la logique pour afficher du contenu selon les besoins ou parcourir des listes :

{% for product in products %}
// Process each product
{% endfor %}

{% if customer.type == "business" %}
// Include business-specific fields
{% else %}
// Include individual customer fields
{% endif %}

Recherches

Utilisez la fonction lookups() pour faire correspondre des valeurs entre différents systèmes, par exemple pour convertir les SKU de vos produits en UID de produits GelatoConnect :

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

La fonctionnalité de recherche nécessite la configuration de tables de correspondance dans GelatoConnect, qui associent les valeurs de votre système aux valeurs de GelatoConnect.

Création et test des mappeurs de modèles

GelatoConnect propose une interface simple et intuitive pour créer et tester des modèles de mappage :

Créer un modèle : Accédez à la section Modèles et créez un nouveau modèle.
Choisir le type de modèle : Sélectionnez le type de modèle approprié (par exemple, demande de soumission de commande, notification de commande reçue).
Définir le modèle : Rédigez votre modèle Jinja2 dans l’éditeur.
Testez avec des données d'exemple : Fournissez des données d'entrée et affichez le modèle pour voir le résultat.
Déboguer et affiner : Ajustez votre modèle selon vos besoins en fonction du rendu obtenu.
Enregistrez et activez : Lorsque votre modèle fonctionne comme vous le souhaitez, enregistrez-le pour l'utiliser dans votre intégration.

Exemples courants d’utilisation des outils de correspondance de modèles

1. Correspondance de la soumission de commande

Transformez les commandes du format de votre système vers le format API de GelatoConnect.

2. Notifications de mise à jour de statut

Créez des modèles pour différents événements de statut de commande (reçue, expédiée, livrée) afin de notifier vos systèmes.

3. Webhooks personnalisés

Formatez les données à envoyer aux systèmes tiers lorsque certains événements se produisent.

4. Normalisation des données

Standardisez les données provenant de sources multiples avant le traitement.

Bonnes pratiques pour les créateurs de modèles

Commencez simplement : Démarrez avec un modèle de base, puis ajoutez de la complexité petit à petit.
Utilisez les commentaires : Ajoutez des commentaires pour expliquer les transformations complexes.
```
jinja{# This extracts the first and last name from the full name #}
```
Gérer les données manquantes : Toujours fournir des valeurs par défaut ou des vérifications pour les champs facultatifs.
```
jinja"additionalInfo": "{{ customer.notes | default('') }}"
```
Testez les cas limites : Assurez-vous que vos modèles gèrent les formats ou valeurs inattendus.
Utilisez les recherches pour les mappages complexes : Plutôt que de coder en dur les mappages dans votre modèle, utilisez la fonctionnalité de recherches.
Gardez vos modèles ciblés : Créez des modèles distincts pour différents objectifs plutôt qu'un seul modèle complexe.
Valider la sortie : Vérifiez toujours que la sortie de votre modèle répond aux exigences de l'API GelatoConnect.

Techniques avancées pour mapper les modèles

Au fur et à mesure que vous vous familiarisez avec les mappers de modèles, vous pouvez explorer des fonctionnalités avancées :

Macros

Définissez des blocs de code de modèle réutilisables :

{% macro format_address(address) %}
{
"addressLine1": "{{ address.street }}",
"city": "{{ address.city }}",
"postCode": "{{ address.zip }}",
"country": "{{ address.country }}"
}
{% endmacro %}

// Then use it like this:

Définir les déclarations

Créez des variables dans votre modèle :

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

Filtres et fonctions personnalisés

GelatoConnect propose plusieurs filtres et fonctions personnalisés, en plus de ceux standard de Jinja2 :

lookups() : Pour faire le lien entre différents systèmes de valeurs
js : Pour un échappement JSON correct
Différentes fonctions de formatage de date

Vous voulez en savoir plus ?

Maintenant que vous comprenez les principes de base des Template Mappers dans GelatoConnect, vous êtes prêt à :

En savoir plus sur la création de modèles pour la réception des commandes
Explorez les exemples de modèles Jinja2
Configurez des déclencheurs de postback qui utilisent vos modèles

[Order Intake - GCW] Introduction aux outils de correspondance de modèles