Dépannage des erreurs de Data Action

1. Anatomie d'un échec de Data Action

Dans Architect, l'action Call Data Action a trois sorties : Success, Failure, et Timeout. Jusqu'à présent, nous nous sommes concentrés sur le chemin "Success". Un échec, qui mène au chemin "Failure" ou "Timeout", peut survenir pour de nombreuses raisons. Pour diagnostiquer efficacement, il faut d'abord comprendre les grandes catégories de problèmes.

Les échecs se classent généralement en quatre catégories :

1. Problèmes de Configuration/Connectivité : L'authentification ou la connexion de base échoue.

   • Identifiants (credentials) invalides ou expirés dans la configuration de l'intégration.
   • Permissions insuffisantes pour le compte utilisé pour l'intégration.
   • L'URL de base du service externe (API) est incorrecte ou le service est hors ligne.
   • Problèmes de réseau, de pare-feu ou de certificats SSL.

2. Problèmes de Requête : Genesys Cloud parvient à contacter l'API, mais la requête envoyée est incorrecte.

   • Les paramètres d'entrée passés depuis Architect sont incorrects (ex: un ID mal formaté, une valeur vide).
   • Le "contrat" de la Data Action ne correspond pas à ce que l'API attend.

3. Problèmes de Réponse : L'API répond, mais d'une manière que Genesys Cloud ne peut pas interpréter comme un succès.

   • L'API renvoie un code d'erreur HTTP (ex: 404 Not Found, 401 Unauthorized, 500 Internal Server Error).
   • La structure du JSON dans la réponse a changé et ne correspond plus au "contrat de succès" que vous avez défini dans la Data Action.
   • L'API met trop de temps à répondre, provoquant un timeout (délai d'attente dépassé).

4. Problèmes de Logique Métier : L'appel API est techniquement un succès, mais ne renvoie pas le résultat attendu.

   • La recherche n'a trouvé aucun résultat.
   • La recherche a trouvé plusieurs résultats alors qu'un seul était attendu.

Dans beaucoup de configurations par défaut, ces deux derniers cas ("aucun résultat" ou "plusieurs résultats") sont traités comme un échec et dirigent le flux vers la sortie Failure.

2. La boîte à outils du dépanneur

Pour enquêter sur ces échecs, Genesys Cloud vous fournit plusieurs outils. Votre travail consiste à les utiliser dans le bon ordre pour isoler le problème.

Outil n°1 : Les sorties d'erreur dans Architect

La première étape, la plus simple, consiste à récupérer les informations d'erreur directement dans votre flux Architect. L'action Call Data Action vous permet de mapper les détails de l'échec à des variables de flux.

Comme suggéré dans la ressource, vous devriez toujours configurer les sorties d'échec pour capturer au minimum :

• failure.outputs.status : Le code de statut HTTP retourné par l'API (ex: 404, 500).
• failure.outputs.errorCode : Un code d'erreur spécifique à Genesys ou à l'API.
• failure.outputs.message : Un message d'erreur lisible.

En stockant ces valeurs dans des variables, vous pouvez utiliser le mode Replay (vu dans la leçon précédente) pour voir exactement quel code d'erreur a été retourné lors d'une exécution passée.

Outil n°2 : Le mode "Test" de la Data Action

Si l'erreur n'est pas évidente à partir des informations capturées dans Architect, l'étape suivante consiste à isoler la Data Action du flux. Le mode "Test" intégré est l'outil parfait pour cela.

Rendez-vous dans Admin > Integrations > Data Actions, ouvrez votre action, et cliquez sur l'onglet Test.

1. Remplissez les contrats d'entrée avec des valeurs statiques et connues.
2. Exécutez le test.
3. Analysez les résultats.

L'onglet "Results" vous montrera la requête brute envoyée (Request), la réponse brute reçue (Response), et comment Genesys a résolu les chemins de succès ou d'échec. C'est ici que vous verrez le code de statut HTTP et le corps de la réponse d'erreur, même si le formatage échoue.

C'est votre principal outil de diagnostic. Si l'action échoue ici, le problème se situe dans la configuration de la Data Action elle-même ou dans le service externe, et non dans le flux Architect.

3. Une méthodologie de résolution systématique

Face à un échec, évitez de deviner. Suivez une méthode.

Étape 1 : Isoler le problème

La première question à se poser est : "L'action échoue-t-elle uniquement dans le flux, ou également en mode Test ?"

• Si l'action fonctionne en mode Test mais échoue dans le flux, le problème vient très probablement des données d'entrée passées par Architect.

  • Solution : Utilisez le mode Replay sur une interaction qui a échoué. Placez un point d'arrêt juste avant l'action Call Data Action. Inspectez les variables de flux que vous utilisez comme entrées. Sont-elles vides ? Ont-elles un format inattendu ? C'est le scénario de débogage le plus courant.

• Si l'action échoue aussi en mode Test, le problème est plus profond. Passez à l'étape 2.

Étape 2 : Analyser la cause racine avec la documentation

Maintenant que vous avez isolé le problème à la Data Action elle-même, vous pouvez utiliser les informations du mode Test et la documentation officielle pour trouver la cause.

En vous basant sur cet article et les informations du mode Test, vous pouvez diagnostiquer :

• Status 401 ou 403 (Unauthorized/Forbidden) : C'est un problème de Credential/Account. Vérifiez vos identifiants dans la configuration de l'intégration.
• Status 404 (Not Found) : Probablement un problème de Connection. L'URL de la requête est-elle correcte dans votre Data Action ?
• Status 400 (Bad Request) : La requête est mal formée. C'est un problème de Search result ou de configuration de la requête. Vérifiez les variables d'entrée et le requestTemplate.
• Status 500 (Internal Server Error) : Le service externe a un problème. Ce n'est pas un souci de configuration Genesys.
• Le test réussit mais le successTemplate ne parvient pas à s'appliquer : C'est un problème de Response. La structure du JSON retourné par l'API a changé. Vous devez mettre à jour votre contrat de sortie.
• L'action prend plus de 15-20 secondes et échoue sans statut : C'est un Timeout. Le service externe est trop lent.

4. Cas particuliers et erreurs avancées

Parfois, les erreurs sont plus subtiles.

• API Rate Limiting (Limitation du nombre d'appels) : De nombreuses API limitent le nombre de requêtes que vous pouvez faire par minute/heure. Si vos Data Actions échouent de manière intermittente, surtout pendant les périodes de forte charge, cela pourrait en être la cause. Des outils comme l'Operational Console peuvent vous aider à repérer ces événements.

• Problèmes de timing : Dans certains scénarios (par exemple, un flux de workflow qui s'exécute immédiatement après la fin d'un appel pour récupérer des données), il se peut que les données ne soient pas encore disponibles via l'API. La ressource de la communauté (Failure Data Action in a Flow) mentionne une astuce : ajouter un léger délai de quelques secondes avant d'appeler la Data Action.

Conclusion

Vous êtes maintenant équipé pour affronter les problèmes de Data Actions, qui sont inévitables dans tout environnement de centre de contact moderne.

Points clés à retenir :

• Classifiez l'erreur : Est-ce un problème de connectivité, de requête, de réponse ou de logique métier ?
• Adoptez une méthodologie : Isolez le problème (flux vs. test), analysez la réponse d'erreur en mode Test, et utilisez la documentation comme checklist.
• Maîtrisez vos outils : Les sorties d'erreur d'Architect, le mode Replay, et surtout le mode Test de la Data Action sont vos meilleurs alliés.
• Capturez les erreurs : Prenez l'habitude de toujours configurer les sorties d'échec (failure.outputs) dans vos flux pour faciliter le diagnostic.

Et ensuite ?
Ce module sur les Data Actions est terminé. Vous avez fait un grand pas en sortant de la "boîte" Genesys pour interagir avec le monde extérieur. Maintenant que nous savons comment récupérer des données externes, une question se pose : comment présenter ces informations de manière claire et utile à vos agents ?

La prochaine leçon entamera un tout nouveau module passionnant : les scripts d'agent. Nous commencerons par les bases en apprenant à naviguer dans le concepteur de scripts (Script Designer) de Genesys Cloud. Vous verrez comment les données que nous avons appris à manipuler dans Architect et via les Data Actions prennent vie sur l'écran de l'agent.