Afficher des données venues d'un service externe

À quoi ça sert

Certaines informations utiles sur une fiche vivent ailleurs : dans un logiciel de réservation, un référentiel d'entreprises, une application métier. Un champ « Web Service » ou « Source Web Service » va les chercher au moment où vous le demandez et les affiche sur la fiche, sans que vous ayez à les ressaisir.

Ces champs ne se saisissent pas. Vous les chargez, vous les rafraîchissez, et vous lisez ce que le service externe a renvoyé, ainsi que la date de la dernière récupération.

La connexion au service, les données récupérées et leur mise en forme sont décidées par un administrateur. Voir Connexions Web Service et Créer et configurer un champ.

Concepts clés

• Web Service — champ qui affiche, sur la fiche, un bloc de valeurs rapportées d'un service externe, chacune avec son libellé.
• Source Web Service — champ dont l'objet premier est de dire si la récupération a réussi. Il affiche un bandeau vert, jaune ou rouge, et les valeurs rapportées ne s'affichent que si vous les dépliez.
• Dernière sync — l'ancienneté de la dernière récupération, affichée sous la forme « il y a … ».
• Données source manquante — un champ de la fiche nécessaire pour interroger le service est vide ; l'appel ne peut pas partir.
• Reprise de valeurs — la traduction d'une valeur brute du service en un libellé lisible, définie à la configuration du champ. Quand aucune traduction ne correspond, la valeur brute est affichée telle quelle.

Comment faire

Charger les données une première fois

1. Ouvrez la fiche.
2. Sur le champ, cliquez sur « Charger les données ».
3. Patientez : le bouton affiche « Chargement... ».

Les valeurs récupérées s'affichent, avec la mention « Dernière sync : … ». Elles sont conservées sur la fiche : à la prochaine ouverture, elles sont déjà là.

Rafraîchir les données

1. Ouvrez la fiche.
2. Sur un champ « Web Service », cliquez sur l'icône circulaire à droite de « Dernière sync : … ». Sur un champ « Source Web Service », cliquez sur l'icône circulaire à droite du bandeau.

Le champ interroge de nouveau le service et remplace les valeurs affichées. L'ancienneté repart de zéro.

Voir les valeurs rapportées par un champ « Source Web Service »

1. Ouvrez la fiche.
2. Sous le bandeau, cliquez sur « Données récupérées ».

Le détail se déplie : un libellé et une valeur par donnée. Une donnée que le service n'a pas renvoyée est signalée en jaune par « Absent sur la cible ». Cliquez de nouveau sur « Données récupérées » pour replier le bloc.

Comprendre un échec de récupération

1. Sur un champ « Web Service », le message d'erreur s'affiche directement dans un bloc rouge. Cliquez sur « Réessayer ».
2. Sur un champ « Source Web Service », le bandeau rouge affiche le message prévu pour ce champ. Cliquez sur « Détails techniques » pour déplier la réponse exacte du service, puis sur l'icône circulaire pour relancer l'appel.

Si le bloc jaune « Données source manquante : … » s'affiche, aucun appel n'est tenté : renseignez d'abord les champs cités, puis rechargez.

Référence

États d'un champ « Web Service »

États d'un champ « Source Web Service »

Le bloc « Données récupérées » reste accessible dans les états vert et jaune. Il affiche « Absent sur la cible » quand le service n'a rien renvoyé pour une donnée en particulier.

Mise en forme des valeurs

• Une valeur pour laquelle une reprise de valeur est prévue s'affiche avec son libellé. Sans correspondance, la valeur brute est affichée.
• Une liste de valeurs est traduite élément par élément, puis affichée séparée par des virgules. Un élément sans correspondance reste brut.
• Une valeur vide peut recevoir un libellé dédié, si la configuration du champ en prévoit un.
• Une donnée déclarée comme une date s'affiche au format jour/mois/année ; une donnée numérique suit le format de votre langue.
• Une donnée numérique peut être transformée par une formule avant affichage, par exemple pour convertir des centimes en euros. Une division par zéro affiche un tiret.
• Sans valeur ni traduction : un tiret.

Rafraîchissement automatique

Un champ peut être rafraîchi tout seul, selon l'intervalle choisi à sa configuration : jamais, toutes les 6, 12, 24, 48 ou 72 heures, toutes les semaines, tous les mois, tous les 3 mois, tous les 6 mois, tous les ans. Le traitement passe régulièrement et ne reprend que les fiches dont le champ a dépassé son intervalle.

Le bouton de rafraîchissement reste disponible à tout moment, quelle que soit cette configuration.

Dans la liste des fiches

• Un champ « Web Service » donne une colonne par donnée rapportée, intitulée « nom de la donnée (nom du champ) ». Ces colonnes se filtrent, mais ne se trient pas.
• Un champ « Source Web Service » donne une seule colonne, qui affiche une coche verte quand la dernière récupération a réussi, une croix rouge quand elle a échoué, et un tiret quand rien n'a encore été chargé. Elle ne se trie ni ne se filtre.
• Le chargement et le rafraîchissement ne se déclenchent que depuis la fiche.

Limites

• Ces champs sont en lecture seule : leur contenu ne se saisit pas et ne se corrige pas. Ils n'apparaissent pas dans le formulaire de création ni dans celui de modification.
• Un champ « Web Service » peut dépendre d'un champ « Source Web Service » de la même fiche. Tant que la source n'a rien rapporté, le champ dépendant affiche « Données source manquante : … ».

Questions fréquentes

Les données sont-elles récupérées à chaque ouverture de la fiche ?

Non. Ce qui s'affiche est le résultat de la dernière récupération, dont l'ancienneté est rappelée par « Dernière sync : … ». Cliquez sur le bouton de rafraîchissement pour interroger de nouveau le service.

Puis-je corriger une valeur fausse rapportée par le service ?

Non. La correction se fait dans l'application d'origine, puis vous rafraîchissez le champ. Si le libellé affiché ne convient pas, c'est la reprise de valeurs du champ qu'un administrateur doit ajuster.

Pourquoi le champ affiche-t-il « Données source manquante » ?

L'interrogation du service utilise la valeur d'un ou plusieurs champs de la fiche. L'un d'eux est vide : le message en donne le libellé. Renseignez-le, puis rechargez le champ.

Pourquoi une valeur s'affiche-t-elle sous forme de code plutôt que de libellé ?

Parce qu'aucune reprise de valeur ne correspond à ce que le service a renvoyé. La valeur brute est alors affichée telle quelle.