Bonjour ! Dans la leçon précédente, nous avons construit le "pont" vers les services externes en configurant une intégration "Web Services Data Actions". Nous y avons aussi stocké de manière sécurisée nos informations d'authentification.
Aujourd'hui, nous allons définir le "véhicule" qui va traverser ce pont : la Data Action elle-même. L'objectif de cette leçon est de vous apprendre à créer une Data Action en définissant précisément les données qu'elle reçoit (paramètres d'entrée) et celles qu'elle renvoie (paramètres de sortie).
Cette étape est fondamentale. C'est comme dessiner le plan d'un formulaire : vous définissez quels champs doivent être remplis avant de l'envoyer, et quels champs contiendront la réponse. Dans Genesys, ce "plan" s'appelle un Contrat. Votre expérience sur UCCE, où vous deviez sans doute configurer des étapes de script pour interroger des bases de données avec des paramètres spécifiques, vous aidera à saisir rapidement ce concept.
À la fin de cette leçon, vous aurez défini la structure complète de votre première Data Action, prête à être configurée pour son premier appel API.
1. Qu'est-ce qu'un Contrat de Data Action ?
Chaque Data Action que vous créez est définie par deux contrats :
- Le Contrat d'Entrée (Input Contract) : Il spécifie les informations que vous devez fournir à la Data Action pour qu'elle puisse s'exécuter. Par exemple, pour obtenir les détails d'un client, vous devrez probablement fournir un
ID client. - Le Contrat de Sortie (Output Contract) : Il définit la structure des données que la Data Action renverra après une exécution réussie. Par exemple, elle pourrait renvoyer le
nom, l'adresseet lenuméro de téléphonedu client.
Ces contrats sont essentiels car ils permettent à Architect (ou aux scripts d'agent) de savoir quelles variables passer à la Data Action et quelles variables attendre en retour.
2. Créer une nouvelle Data Action
Commençons par créer le conteneur pour notre action. Dans l'interface d'administration de Genesys Cloud, naviguez vers Integrations > Actions.
- Cliquez sur le bouton + Add Action en haut à droite.
- Dans la fenêtre qui s'ouvre, sélectionnez dans la liste déroulante l'intégration que vous avez créée à la leçon précédente (par ex.,
Intégration pour API Publiques). - Donnez un nom à votre action. Pour notre exemple, appelons-la
Récupérer infos utilisateur. - Cliquez sur Save.
Vous êtes maintenant sur la page de configuration de votre nouvelle Data Action. La majeure partie de notre travail aujourd'hui se fera dans l'onglet Setup.
Interface de création d'une Data Action
Cette image, tirée du guide OCP Learning Center, montre la première étape : ajouter une nouvelle action et la lier à une intégration existante.
3. Définir les Contrats d'Entrée et de Sortie
La définition des contrats est la partie la plus importante. Pour bien comprendre l'interface et les options disponibles, je vous propose de consulter la documentation officielle de Genesys Cloud.
Add contracts to custom actions for integrations View summary
Cette page de la documentation officielle, intitulée 'Add contracts to custom actions', est la référence pour tout ce qui concerne les contrats. Elle explique en détail comment définir les schémas d'entrée et de sortie.
Lisez attentivement les deux sections : la première sur le 'Input contract' et la seconde sur le 'Output contract'. Portez attention aux descriptions des champs (Title, Data type selector, Asterisk) et aux exemples de schémas JSON qui sont générés automatiquement par l'interface.
Le Contrat d'Entrée (Input)
Comme l'explique la documentation, le contrat d'entrée définit les "questions" que vous posez à l'API. Chaque "question" est un paramètre avec un nom et un type de données (texte, nombre, booléen, etc.).
Prenons un exemple très concret dans un contexte de centre de contact : récupérer le temps d'attente estimé (EWT) pour une file d'attente. Pour cela, l'API a besoin de savoir quelle file d'attente et pour quel type de média.
Le Contrat de Sortie (Output)
Le contrat de sortie, lui, définit la structure de la "réponse". C'est ce que votre flux Architect ou votre script recevra si l'appel réussit.
Dans l'image ci-dessus, regardez le Output Contract. Il est configuré pour renvoyer une seule information : estimated_wait_time, qui est un nombre entier (integer).
La vidéo ci-dessous montre également le processus de configuration d'un contrat de sortie, notamment pour gérer une liste de résultats (un "array"), ce qui est un cas d'usage très fréquent.
DevCast Tutorial - Using Genesys Cloud Data Actions in Architect
Ce tutoriel de la communauté Genesys, bien que complet, a une section qui se concentre spécifiquement sur la création du contrat de sortie.
Regardez la vidéo de 09:30 à 12:06. Le présentateur montre comment ajouter un contrat de sortie pour une API qui renvoie une liste d'entités. Il explique comment configurer la Data Action pour qu'elle s'attende à recevoir un 'array of strings' (un tableau de chaînes de caractères). C'est un excellent complément visuel à la documentation.
4. Exercice pratique : Définir les contrats pour l'API JSON Placeholder
Mettons cela en pratique. Nous allons préparer une Data Action pour interroger l'API publique JSON Placeholder que vous avez déjà utilisée avec Postman. L'objectif est d'appeler l'URL https://jsonplaceholder.typicode.com/users/{userId} pour récupérer les informations d'un utilisateur spécifique.
- Assurez-vous d'être sur la page de configuration de votre Data Action
Récupérer infos utilisateur. - Allez dans l'onglet Setup.
Étape 1 : Configurer le Contrat d'Entrée
L'URL que nous voulons appeler a besoin d'un userId. Nous devons donc le définir comme paramètre d'entrée.
- Sous Input Contract, cliquez sur la ligne existante pour la modifier.
- Dans le champ Title, nommez votre paramètre
userId. - Assurez-vous que le Data type est
String. - Cochez l'astérisque
*pour le marquer comme Required. - Cliquez sur le
V(check mark) pour sauvegarder la ligne.
Votre contrat d'entrée est maintenant défini. Genesys sait qu'il doit demander une variable userId chaque fois que cette action est appelée.
Étape 2 : Configurer le Contrat de Sortie
L'API renvoie beaucoup d'informations, mais nous ne nous intéressons pour l'instant qu'au nom et à l'email de l'utilisateur.
- Sous Output Contract, cliquez sur la ligne pour la modifier.
- Assurez-vous que le type est Object.
- Cliquez sur le + à côté du titre de l'objet pour ajouter une propriété.
- Nommez la première propriété
name. - Laissez le type sur
String.
- Nommez la première propriété
- Cliquez à nouveau sur le + pour ajouter une seconde propriété.
- Nommez la seconde propriété
email. - Laissez le type sur
String.
- Nommez la seconde propriété
- Cliquez sur le
Vpour sauvegarder.
Exemple de configuration des contrats d'entrée et de sortie dans l'interface Genesys Cloud
Les sections 'Input Contract Schema' et 'Output Contract Schema' de la documentation vous montrent à quoi ressemble l'interface que vous êtes en train d'utiliser, avec les options pour ajouter des propriétés, définir leur type et les marquer comme requises.
Votre Data Action a maintenant un plan complet : elle sait qu'elle a besoin d'un userId en entrée et qu'elle fournira un name et un email en sortie. N'oubliez pas de cliquer sur Save en haut de la page pour enregistrer vos modifications.
Conclusion
Félicitations ! Vous avez franchi une étape cruciale en structurant votre première Data Action. Vous ne communiquez pas encore avec l'API, mais vous avez défini un "contrat" clair et rigoureux que Genesys Cloud peut comprendre et utiliser.
Voici les points clés à retenir :
- Une Data Action est créée sous Integrations > Actions et est toujours rattachée à une intégration spécifique.
- Le Contrat d'Entrée (Input Contract) définit les paramètres nécessaires pour exécuter l'action (par ex:
userId). - Le Contrat de Sortie (Output Contract) définit les données que l'action retournera en cas de succès (par ex:
name,email). - La définition de ces contrats se fait via une interface graphique simple dans l'onglet Setup de la Data Action.
Prochaine leçon :
Maintenant que notre "plan" est prêt, il est temps de passer à la "construction". Dans la prochaine leçon, nous allons finaliser la configuration de cette Data Action. Nous spécifierons l'URL de l'API à appeler, nous indiquerons comment insérer le userId dans cette URL, et surtout, nous utiliserons l'onglet Test pour exécuter notre action pour la première fois et voir si elle récupère bien les données comme prévu.