Comment récupérer des actions dans Zoho

La récupération des actions dans Zoho consiste à itérer sur la liste d'actions d'un plan structuré et à exécuter chaque appel d'outil en séquence, le système gérant automatiquement les permissions en lecture seule ou en écriture tout au long du processus.

Pourquoi c'est important

Lorsque vous créez des automatisations ou des workflows assistés par IA sur Zoho, votre intégration doit récupérer et exécuter de manière fiable la séquence correcte d'actions à partir d'un objet plan. Comprendre le fonctionnement du pipeline de récupération et d'exécution vous aide à déboguer les étapes échouées, à gérer les questions de clarification avec élégance et à vous assurer que vos identifiants de connexion sont valides avant tout appel d'outil.

Étape par étape

Étape 1. Confirmez que votre connexion Zoho est active avant de tenter de récupérer ou d'exécuter des actions. Le système appelle getzohoapi avec votre userid et votre apptype pour obtenir un handle d'API actif et les métadonnées de connexion. Si aucune connexion valide n'est retournée, le pipeline s'arrête immédiatement et renvoie une erreur de reconnexion à l'appelant. ^[2]

Étape 2. Analysez l'objet plan pour accéder à sa liste actions. Le plan est stocké en JSON (communément appelé plan_json), et vous récupérez la liste avec plan.get("actions"). Si le JSON est malformé ou si la liste est absente, le système enregistre l'échec et retourne une erreur "Invalid plan" — validez donc toujours votre payload de plan avant de continuer. ^[4]

Étape 3. Itérez sur chaque action de la liste. Chaque entrée d'action contient au minimum une clé tool (le nom de l'outil Zoho à invoquer) et un dictionnaire params contenant les arguments de cet outil. Parcourez la liste et extrayez les deux valeurs pour chaque étape. ^[1]

Étape 4. Validez chaque appel d'outil avant son exécution. Pour chaque action, appelez validatetoolcall avec l'apptype, le nom de l'outil et ses params. Cela retourne un niveau de permission — soit "read", soit autre chose. Si chaque action du plan résout en permission "read", l'ensemble du plan est classifié comme lecture seule et peut être exécuté immédiatement sans étape d'approbation séparée. Si une action ne dispose pas de la permission "read", le flag allread_only est défini à False et le plan nécessite une confirmation explicite de l'utilisateur avant d'être appliqué. ^[5]

Étape 5. Exécutez chaque action en utilisant executetoolwithrepair. Transmettez le handle api, l'apptype, le nom du tool et les params. Pour les outils en lecture seule, définissez allowrepair=True afin que le système puisse automatiquement réessayer avec des paramètres corrigés si la première tentative échoue. La fonction retourne un dictionnaire execout contenant le result, et éventuellement une clarifyingquestion si l'outil a besoin de plus d'informations de la part de l'utilisateur. ^[3]

Étape 6. Vérifiez la sortie de chaque exécution. Si execout.get("clarifyingquestion") est renseigné, mettez en pause la boucle d'actions, présentez la question à l'utilisateur et enregistrez-la dans votre store de messages de chat avant de libérer les verrous de concurrence. Si le résultat est un dictionnaire contenant une clé "error", capturez ce message d'erreur pour l'afficher. Sinon, considérez l'action comme exécutée avec succès. ^[2]

Étape 7. Après une exécution réussie, construisez des liens contextuels vers les enregistrements affectés en utilisant buildzoholinks. Fournissez le result, le nom d'outil résolu (execout.get("tool") or tool), les params résolus, l'apptype, le code du centre de données (dc), ainsi que les identifiants d'organisation/portail issus des métadonnées de connexion (crmorgid, deskorgid, desk_portal). Ces liens permettent aux utilisateurs de naviguer directement vers les enregistrements qui ont été lus ou modifiés. ^[8]

Étape 8. Pour les outils basés sur le navigateur (tels que browsernavigateandscreenshot pour inspecter les pages d'administration Zoho), le chemin d'exécution est légèrement différent. Le BROWSERTOOLREGISTRY est d'abord vérifié pour confirmer que l'outil existe, puis les params requis sont validés, et enfin le statut d'authentification de la session du navigateur est vérifié. Si la session a expiré, le système retourne un champ actionrequired vous indiquant de vous ré-authentifier via l'endpoint de connexion du navigateur. ^[7]

Erreurs courantes

• Connexion Zoho manquante : Si getzohoapi ne retourne rien, aucune action ne sera exécutée. Vérifiez toujours que la connexion est établie et que l'app_type correct est spécifié avant de déclencher un plan. ^[4]
• JSON de plan invalide : Une chaîne plan_json malformée entraîne l'abandon de l'ensemble de l'opération d'application. Le système enregistre un échantillon du payload défectueux (jusqu'à 200 caractères) pour faciliter le débogage. ^[4]
• Dépassement de la limite du nombre d'actions : Le système vérifie planactioncount par rapport à Config.MAXPLANACTIONS lorsque le flag d'application du moteur de workflow est actif. Les plans comportant trop d'actions peuvent être refusés avant tout appel d'outil. ^[4]
• Expiration de la session du navigateur : Pour les appels d'outils basés sur le navigateur, une session expirée ou non authentifiée retourne une erreur plutôt qu'un échec silencieux — surveillez la clé "action_required" dans la réponse. ^[7]
• Actions non en lecture seule en mode streaming : Dans l'endpoint de plan en streaming, les plans en lecture seule s'exécutent en ligne avec un flux de statut en direct. Les plans contenant des actions d'écriture sont retournés au client sous forme de payload de plan en attente, nécessitant une étape d'application séparée. ^[5]

Ce qu'il faut vérifier

• Confirmez que getzohoapi retourne un handle d'API valide et que la valeur dc (centre de données) dans les métadonnées de connexion correspond à la région de votre compte Zoho.
• Vérifiez que la clé tool de chaque action correspond à un nom d'outil enregistré et que tous les params REQUIRED sont présents avant de soumettre le plan.
• Après l'exécution, inspectez le champ status de chaque résultat — recherchez "success" ou "error" — et confirmez que buildzoholinks retourne des URL d'enregistrements navigables pour toutes les données affectées. ^[3][8]

---

*Beam Help fournit une assistance experte indépendante pour Zoho et ne constitue pas le support officiel de Zoho. Testez toujours l'exécution des plans dans un environnement sandbox avant d'appliquer des modifications aux données de production.*