Types de données externes
Si vous intégrez Yesplan avec un système de billetterie, vous pouvez afficher dans Yesplan des données provenant de votre système de billetterie, par le biais d’un champ de données personnalisées de type « Données externes » :
- Avant Yesplan 28, le contenu d’un tel champ était toujours de type « Texte (une seule ligne) », même si le champ contenait en réalité un nombre. Il était compliqué d’utiliser ensuite ce contenu dans des calculs, par exemple en l’exportant dans un fichier Excel.
- Depuis Yesplan 28, vous pouvez signaler explicitement que les données contenues dans un tel champ doivent être de type « Nombre ». Cela vous permet notamment de les utiliser plus facilement dans des calculs.
Remarque
Pour la période de transition, nous avons ajouté un paramètre qui vous permet de continuer de récupérer via l’API les données externes de type « Nombre » sous la forme de « Texte (une seule ligne) », pour éviter les soucis avec les intégrations existantes. Vous pouvez activer et désactiver ce paramètre sous « Paramètres du système » > « Préférences système » > « Fonctionnalités obsolètes ». Consultez la section Fonctionnalités obsolètes pour en savoir plus.
Les instructions ci-dessous décrivent les étapes à parcourir pour utiliser aisément les nouveaux types de données.
Sans intégration§
Si vous n’utilisez actuellement aucune intégration avec un système de billetterie, vous pouvez passer immédiatement au type de données « Nombre » :
- Accédez à « Paramètres du système » > « Préférences système » > « Fonctionnalités obsolètes ».
- Sélectionnez « Non » dans le menu déroulant à côté de « La valeur des champs de données externes de type « Nombre » est envoyée comme une chaîne de caractères (« string ») dans REST API ».
Aucune autre intervention de votre part n’est requise.
Nouvelle intégration§
Si vous créez une nouvelle intégration avec un système de billetterie, vous pouvez utiliser d’emblée le type de données « Nombre » :
- Utilisez le type de données adéquat lors de la création de champs de données personnalisées de type « Données externes » (par exemple « Nombre » pour les nombres, « Date » pour les dates, etc.). Consultez la section Données externes pour en savoir plus.
- Accédez à « Paramètres du système » > « Préférences système » > « Fonctionnalités obsolètes ».
- Sélectionnez « Non » dans le menu déroulant à côté de « La valeur des champs de données externes de type « Nombre » est envoyée comme une chaîne de caractères (« string ») dans REST API ».
Les champs seront toujours enregistrés avec le type de données adéquat et seront communiqués de cette manière via l’API.
Intégration existante§
Si vous avez une intégration existante avec un système de billetterie, vous utilisez probablement des champs de données personnalisées de type « Données externes » avec des valeurs de type « Texte (une seule ligne) », même s’ils contiennent en réalité un nombre. Voilà pourquoi nous recommandons de suivre les étapes ci-dessous pour convertir le type de données de ces champs en « Nombre » partout où c’est nécessaire.
Rédigez une liste§
Rédigez d’abord une liste des champs de type « Données externes » qui contiennent un nombre, ainsi que leurs champs correspondants dans le système de billetterie :
- Pour Yesplan, il vaut mieux utiliser le keyword, par exemple « billetterie_externe_nombre_vendus ».
- Utilisez le nom technique pour le champ dans le système de billetterie.
Vous trouverez ces informations à la page de configuration de votre intégration sous « Paramètres du système » > « Intégrations ».
Demandez la conversion§
Dès que vous avez la certitude que votre système de billetterie prend en charge la communication des valeurs sous forme de nombres, vous pouvez demander à Yesplan de convertir les champs. Il suffit d’envoyer un e-mail à support@yesplan.be.
Demandez à Yesplan de convertir le type de données des champs existants en « Nombre » :
- Les champs contenant des nombres auront le type de données adéquat : « Nombre ».
- Vous ne devez pas modifier la configuration de votre intégration.
- Nous vérifierons si ces champs sont utilisés dans des rapports et nous les modifierons le cas échéant.
Attention
Nous convertirons uniquement les champs effectivement associés dans l’intégration au moment de la conversion :
- Les champs de données externes qui ne sont pas associés lors de la conversion ne sont pas convertis et conservent le type de données « Texte (une seule ligne) ». Si vous les associez après la conversion, ils auront un type de données erroné.
- Voilà pourquoi nous recommandons de créer chaque fois un nouveau champ de données personnalisées après la conversion si vous voulez afficher des données externes supplémentaires dans Yesplan. En effet, vous pouvez dans ce cas lui assigner le type de données adéquat.
Contrôlez votre intégration§
La base de données de Yesplan contient désormais des valeurs avec le type de données « Nombre » pour les champs concernés. L’API continue toutefois de restituer ces valeurs comme une chaîne JSON et vous devez corriger cela.
Vérifiez quelles intégrations utilisent les champs concernés :
- Nous avons parlé de vos intégrations de billetterie, mais d’autres intégrations peuvent également utiliser ces champs (par exemple pour l’analyse des données, le site web, etc.).
- Demandez aux développeurs de ces intégrations de tester qu’ils sont en mesure d’envoyer/recevoir des valeurs avec le type de données « Nombre ». La section Pour les développeurs ci-dessous explique de manière détaillée comment ils peuvent effectuer cette vérification.
- Ne passez pas à l’étape suivante avant de savoir avec certitude que les intégrations prennent en charge les nouveaux types de données.
Passez à la nouvelle procédure§
Dès que vous avez la certitude que toutes les intégrations sont compatibles avec le type de données « Nombre », vous devez veiller à ce que l’API utilise ce format pour communiquer les valeurs :
- Accédez à « Paramètres du système » > « Préférences système » > « Fonctionnalités obsolètes ».
- Sélectionnez « Non » dans le menu déroulant à côté de « La valeur des champs de données externes de type « Nombre » est envoyée comme une chaîne de caractères (« string ») dans REST API ».
Après cette opération, Yesplan contiendra des valeurs de type « Nombre » pour les champs concernés et l’API communiquera effectivement ces valeurs sous forme de nombres. Si un problème se produit malgré tout, vous pourrez remettre le paramètre sur « Oui » le temps de régler le problème.
Pour les développeurs§
Yesplan change la manière d’enregistrer les valeurs provenant des systèmes de billetterie dans les champs de données personnalisées destinés aux données externes :
- Avant Yesplan 28, le contenu d’un tel champ était toujours de type « Texte (une seule ligne) », même si le champ contenait en réalité un nombre.
- Depuis Yesplan 28, vous pouvez choisir différents types de données pour ces valeurs. Ce changement est important surtout pour les valeurs de type « Nombre » (nombre de billets disponibles, nombre de ventes, etc.).
Depuis Yesplan 28, les valeurs que vous pouvez retourner ou récupérer via l’API ne sont donc plus limitées au type de données (« data type ») « Single-Line Text » pour les champs de données personnalisées de type « Données externes ». Consultez Datatypes of Remote Data and Integration Data pour en savoir plus sur les nouvelles possibilités.
Pour la période de transition, nous avons créé dans Yesplan un paramètre permettant de communiquer toujours ces valeurs sous forme d’une chaîne de caractères (« String ») dans l’API, même si le champ contient un nombre (et a donc le type de données « Number »). Quand ce paramètre sera désactivé, les valeurs seront retournées sous forme de nombres JSON, plutôt que sous forme de chaînes de caractères JSON.
Cela peut avoir des conséquences pour votre intégration : alors que vous avez toujours reçu une chaîne de caractères (« String ») auparavant, vous pourrez désormais recevoir aussi un nombre (« Number »), voire un autre type de données. Comment pouvez-vous avoir la certitude que votre intégration reste compatible avec la nouvelle situation ?
Module de billetterie générique§
Si votre intégration utilise le Module de billetterie générique, ainsi que des champs de données personnalisées de type « Données externes », la valeur JSON récupérée par Yesplan via votre API peut provisoirement :
- être aussi un nombre pour le type de données « Single-Line Text » (« Texte (une seule ligne) ») ;
- être aussi une chaîne JSON contenant un nombre pour le type de données « Number » (« Nombre »).
Via le REST API§
Si vous récupérez ou communiquez des valeurs destinées à des champs de données personnalisées de type « Données externes » via le REST API, vous devez parcourir les étapes suivantes :
- Le paramètre des fonctionnalités obsolètes assure le retour des valeurs de tous les champs de type « Données externes » sous forme de chaîne de caractères JSON, même si le type de données est « Number » (« Nombre »).
- Vous pouvez tester l’impact de la modification du type de données (de « String » vers « Number ») sur votre intégration en embarquant dans vos requêtes adressées à l’API Yesplan un en-tête HTTP spécifique. Consultez Datatypes of Remote Data and Integration Data pour en savoir plus.
- Dès que chaque intégrateur a confirmé au client que son intégration est compatible avec les nouveaux types de données, ce client réglera le paramètre pour fonctionnalités obsolètes sur « Non », ce qui assurera l’envoi de valeurs dans l’API avec le type de données adéquat.