Gérer les workflows d’API

Créer des workflows d’API

Pour créer une solution de workflow d’API :

1. Dans votre organisation Automation Cloud™, ouvrez Studio Web.
2. Sélectionnez Créer nouveau > Workflow d’API. Une nouvelle solution s'ouvre, avec le canevas du concepteur de workflow d'API affiché.

Définir les schémas d'entrée

Les workflows d'API fonctionnent comme des API eux-mêmes et peuvent nécessiter un schéma d'entrée pour définir les paramètres d'entrée attendus. Le schéma d'entrée spécifie la structure de données qu'un service externe doit fournir lors du déclenchement du workflow.

Vous pouvez configurer le schéma d'entrée en téléchargeant un fichier JSON ou en définissant manuellement les paramètres d'entrée.

1. Dans votre projet de workflow d’API, ouvrez le panneau Data manager .
2. Sélectionnez l’onglet Entrée .

   Pour télécharger un schéma JSON, suivez l' étape 3.

   Pour définir manuellement les paramètres d'entrée, suivez l' étape 4.

3. Pour télécharger un schéma JSON avec les paramètres d'entrée déjà définis, sélectionnez Générer à partir de la charge utile.
   1. Fournissez au format JSON l’entrée attendue.
   2. Sélectionnez Générer un schéma.
   3. Examinez le schéma généré et ajoutez des descriptions aux propriétés si nécessaire.
4. Pour définir manuellement les paramètres d'entrée, sélectionnez Ajouter une propriété.
   1. Configurez les détails de la propriété :
      • Name : définissez la clé de la propriété
      • Type—Sélectionnez parmi Chaîne, Nombre, Entier, Booléen, Objet, Tableau, Date-heure, Date, Heure.
        Important : si vous utilisez un objet ou un tableau, définissez les propriétés des éléments imbriqués.
      • Obligatoire : cochez cette case pour marquer la propriété comme obligatoire.
   2. Répétez l'étape jusqu'à ce que vous définissiez tous les paramètres d'entrée.

Définir les schémas de sortie

Le schéma de sortie définit la structure des données renvoyées par le workflow d'API, garantissant que tout service appelant le workflow comprend le format de sortie à l'avance. Le schéma de sortie peut inclure des données explicitement définies dans le schéma lui-même, telles que des ID ou des valeurs fournies par l'utilisateur, ainsi que des sorties générées dynamiquement à partir des étapes du workflow, telles que des réponses d'API ou des valeurs calculées.

Vous pouvez configurer le schéma de sortie en téléchargeant un fichier JSON ou en définissant manuellement les paramètres de sortie.

1. Dans votre projet de workflow d’API, ouvrez le panneau Data manager .
2. Sélectionnez l'onglet Sortie .

   Pour télécharger un schéma JSON, suivez l' étape 3.

   Pour définir manuellement les paramètres de sortie, suivez l' étape 4.

3. Pour télécharger un schéma JSON avec les paramètres de sortie déjà définis, sélectionnez Générer à partir de la charge utile.
   1. Fournissez au fichier JSON la sortie attendue.
   2. Sélectionnez Générer un schéma.
   3. Examinez le schéma généré et ajoutez des descriptions aux propriétés si nécessaire.
4. Pour définir manuellement les paramètres de sortie, sélectionnez Ajouter une propriété.
   1. Configurez les détails de la propriété :
      • Name : définissez la clé de la propriété
      • Type—Sélectionnez parmi Chaîne, Nombre, Entier, Booléen, Objet, Tableau, Date-heure, Date, Heure.
        Important : si vous utilisez un objet ou un tableau, définissez les propriétés des éléments imbriqués.
      • Obligatoire : cochez cette case pour marquer la propriété comme obligatoire.
   2. Répétez l’étape jusqu’à ce que vous ayez défini tous les paramètres de sortie.

Utilisation de l'éditeur d'expressions

L' éditeur d'expressions vous aide à accéder, à évaluer et à manipuler les données dans les workflows d'API. Utilisez-la pour créer une logique conditionnelle, configurer des champs d’activité ou écrire des activités JavaScript.

Disposition de l’éditeur d’expression

La mise en page de l' éditeur d'expressions contient les panneaux suivants :

Panneau	Description
Entrée	Le panneau principal est le panneau d'entrée, où vous écrivez vos expressions JavaScript ou JQ. Ce panneau comprend un contrôleur de syntaxe intégré qui identifie et met en surbrillance les erreurs dans votre syntaxe d’expression.
Générateur d’expressions Autopilot	Situé dans le bas du panneau d’entrée, le générateur d’expressions Autopilot vous aide à créer des expressions de workflow à l’aide du langage naturel, au lieu d’écrire du JavaScript. Autopilot comprend le contexte de votre workflow et vous permet de référencer des objets et des étapes de workflow en décrivant simplement le résultat souhaité.
Entrée de test d’activité	À droite du panneau de code, le panneau d'entrée de test Activité vous permet d'examiner les données de test générées lors des précédentes exécutions de workflow. Il fournit des exemples de données que vous pouvez utiliser pour créer et valider des expressions, et il interagit directement avec le panneau Sortie d'expression pour garantir que vos expressions produisent les résultats souhaités.
Sortie de l’expression	Le panneau Sortie de l'expression affiche le résultat de votre expression en fonction des données des données d'entrée du test d'activité . Cela vous permet de confirmer que votre expression génère le résultat attendu. Si votre expression comporte des erreurs, la section Sortie d'expression met en surbrillance l'expression problématique et fournit un message d'erreur correspondant. Le résultat est mis à jour automatiquement chaque fois que vous modifiez l'expression dans le panneau d'entrée.

Accéder aux données à l'aide de JavaScript

Il existe deux points d’accès pour les données de workflow :

• $workflow— Fait référence à la configuration au niveau du workflow.
• $context : fait référence à la configuration au niveau de l’activité.
• $input : fait référence à la configuration de l’activité précédemment exécutée.

Important : utilisez l' écran d'entrée Test dans l' éditeur d'expressions pour référencer les propriétés d'étape lors de la création de vos expressions.

Points d’accès	Description	Comment utiliser
$workflow.input	Stocke le schéma de requête ainsi que toutes les valeurs définies dans la configuration du test.	Pour accéder aux données de configuration de test dans l' éditeur d'expressions, saisissez la syntaxe suivante et remplacez {property_name} par la propriété spécifique que vous souhaitez référencer : $workflow.input.{property_name}
$context	Stocke les données d'entrée et de sortie de chaque étape du workflow. Pour référencer ces propriétés dans vos expressions, commencez par exécuter et déboguez le workflow . Cela génère des entrées et des sorties au niveau de l'étape, visibles sur l'écran Entrée de test .	Pour accéder aux données de réponse de sortie d’une étape spécifique, utilisez le modèle de syntaxe suivant dans l’ éditeur d’expressions et remplacez {step_name} et {property_name} par vos noms d’étape et de propriété, respectivement : $context.outputs.{step_name}.content.{property_name}
$input	Stocke les données passées directement de l'étape précédente à l'étape actuelle. Utilisez $input pour référencer les propriétés de l'étape précédente sans parcourir l'ensemble $context.	Pour accéder aux propriétés de l'étape précédente, utilisez la syntaxe suivante et remplacez {property_name}par la propriété que vous souhaitez référencer : $input.{property_name}

Workflows d'API de test

Pour que l’intégration du workflow d’API réussisse, testez votre workflow rapidement et fréquemment. Des tests réguliers vous aident à identifier et à résoudre rapidement les erreurs. Des fonctionnalités telles que IntelliSense, la saisie semi-automatique, Autopilot et l'écran d'entrée de test d'activité dépendent des données de test. Exécutez régulièrement le workflow à l’aide du bouton Test pour générer ces données.

Les tests garantissent :

• Vos mappages de données entre les étapes de workflow sont corrects, évitant ainsi un comportement inattendu.
• Les requêtes d’API sont correctement configurées, garantissant des réponses fiables.
• Votre workflow fonctionne comme prévu, ce qui réduit le risque d’erreurs inattendues en production.

Comprendre les informations de sortie d’exécution

Le panneau Sortie d'exécution fournit des informations détaillées sur l'exécution du workflow.

Données d’entrée et de sortie de l’activité

Ces données sont disponibles par activité sélectionnée et fournissent :

• Données d'entrée :informations reçues d'une étape à partir de l'activité précédente.
• Output data :informations produites par l'étape actuelle, transmises à l'activité suivante.

Examinez les données d’entrée/de sortie pour confirmer l’exactitude des mappages et des transformations de données.

Informations sur la requête API

Lorsque les workflows interagissent avec les API, vérifiez les détails suivants de la requête :

• URL de la demande :confirmez que les paramètres d'URL dynamiques sont correctement résolus.
• En-têtes :vérifiez que l’authentification et les en-têtes de type de contenu sont définis de manière appropriée.
• Paramètres de requête :permet de vérifier que les filtres et les paramètres sont correctement formatés.
• Contenu du corps -La structure JSON de validation correspond aux exigences de l'API.

Requêtes API réussies

Pour les requêtes d'API réussies, développez chaque étape pour examiner :

• Détails de la demande :URL, en-têtes, paramètres de requête et corps du contenu.
• Détails de la réponse :code de statut, en-têtes et contenu de la réponse.
• Données de sortie :informations générées par l'appel d'API pour être utilisées dans les étapes suivantes du workflow.

Débogage

Pour identifier et déboguer efficacement les erreurs de workflow, suivez ces instructions :

• Indicateurs d’erreur
  • Les étapes qui rencontrent des erreurs affichent une icône d'erreur.
  • Sélectionnez l'étape pour afficher les messages d'erreur et les sorties détaillés.
• Étapes de débogage courantes
  • Valider les requêtes d’API : vérifier que les détails de la requête tels que les URL, les en-têtes, les paramètres et le contenu du corps correspondent à la documentation de l’API.
  • Examiner les messages d’erreur : examinez les messages d’erreur pour obtenir des informations sur les erreurs d’authentification, les charges utiles incorrectes ou les erreurs de script.

Ajouter une configuration de débogage

Vous pouvez créer et tester votre workflow d’API de manière itérative, en validant chaque étape au fur et à mesure que vous ajoutez de nouvelles activités. Pour exécuter ces tests efficacement, vous pouvez définir des données d’entrée spécifiques à l’aide de la fonctionnalité de configuration Déboguer . Cela vous permet de définir une entrée JSON une fois et de la réutiliser dans toutes les exécutions de test ultérieures. Vous pouvez accéder aux données émulées via l'objet $workflow.input pendant l'exécution du workflow.

Pour ajouter une configuration de débogage:

1. En haut de votre zone de dessin de conception de workflow d’API, ouvrez la liste déroulante Déboguer , puis sélectionnez Déboguer la configuration.
2. Dans la fenêtre qui s'ouvre, fournissez les données d'entrée du test au format JSON.
3. Enregistrez votre configuration de test.
4. Une fois qu'elle est enregistrée, vous pouvez accéder à la configuration du test dans l' éditeur d'expressions à l'aide de la référence $workflow.input.{propertyname}. En outre, la configuration du débogage s’affiche également dans le panneau d’entrée de test Activité de l’éditeur d’expressions.

Déboguer votre workflow d’API

Pour déboguer votre workflow d’API :

1. Ouvrez votre workflow d’API. Assurez-vous que votre workflow est entièrement configuré et prêt à s'exécuter.
2. Si votre workflow dépend des données d'entrée, par exemple celles d'un système externe, définissez la configuration de débogage avant le test. Cela garantit que chaque étape reçoit les données nécessaires.
3. Déboguez votre workflow. Le bouton Déboguer se trouve en haut de la page. Sélectionnez-le pour exécuter le workflow et afficher les résultats en temps réel.
4. Une fois le débogage démarré, le panneau Sortie d'exécution s'affiche sur le côté droit de l'écran. Ici, vous pouvez voir le statut d'exécution de chaque étape clairement marqué comme succès, échec ou en attente.

Publier les workflows d’API

Important : avant la publication, testez votre workflow d'API en utilisant à la fois des scénarios de réussite et d'échec, afin de confirmer que chaque scénario s'exécute correctement.

Pour publier votre solution de workflow d’API :

1. Sur votre canevas de conception de workflow d'API, sélectionnez Publier.
2. Sélectionnez l'emplacement où votre workflow d'API doit être publié :
   • Flux d’espace de travail personnel Orchestrator
   • Votre flux de locataire Orchestrator
3. Fournissez d’autres informations importantes pour votre workflow d’API, telles que Journal des modifications et Version.
4. Sélectionnez Publier. Une notification vous informe de la publication réussie de votre workflow d'API.

Si vous avez publié sur votre flux d'espace de travail personnel, le workflow est visible dans Orchestrator sous Mon espace de travail > Automatisations > Processus. Les workflows d’API sont identifiables par le type d’API.

Si vous avez publié dans votre flux de locataire, le workflow est visible dans Orchestrator sous Locataire > Solutions. Les workflows d’API sont identifiables par le type d’API.

Déployer des workflows d'API

Une fois que vous avez publié votre workflow d’API dans le flux de vos préférences, vous devez déployer la solution.

Déployer des workflows d'API à partir de votre flux d'espace de travail personnel

La publication dans votre espace de travail personnel prépare le workflow d'API en tant que processus dans Orchestrator > Mon espace de travail > sous-dossier Nom de votre workflow d'API > Automatisations > Processus.

Important : Un sous-dossier dédié est automatiquement créé à l'intérieur de votre dossier d'espace de travail personnel.

Déployer des workflows d’API à partir de votre flux de locataire

La publication sur votre locataire Orchestrator télécharge le package de workflow d'API dans Orchestrator > Locataire > Solutions.

Pour le déployer en tant que processus :

1. Accédez à Orchestrator > Locataire > Solutions.
2. Pour le package de workflow d’API que vous avez précédemment publié sur votre flux de locataire, sélectionnez le menu à trois points, puis sélectionnez Déployer le package.
3. Dans l’assistant Déployer la version de la solution , configurez les détails suivants :
   1. Nom du déploiement : ajoutez le nom à afficher sur toutes les pages qui mentionnent, répertorient ou surveillent des processus. Si laissé vide, le nom du package est utilisé.
   2. Dossier de destination : indiquez le dossier à utiliser comme dossier parent pour la racine de la solution. La solution n'est pas déployée dans le dossier sélectionné, mais un nouveau dossier enfant est créé.
   3. Installer en tant que nouveau dossier racine sous le locataire—cochez cette case pour installer la solution en tant que nouveau dossier racine sous le locataire actuel.
   4. Nom du dossier racine de la solution—modifiez le nom du dossier racine.
4. Sélectionnez Examiner. Vous pouvez désormais enregistrer votre solution en tant que brouillon, ou la valider et continuer.
5. Sélectionnez Déployer. Vous pouvez maintenant trouver votre workflow en tant que processus dans le dossier indiqué à l’étape 3 > Automatisations > Processus. Vous pouvez identifier un workflow d’API par le type d’API.
6. Sélectionnez Activer le déploiement pour terminer le déploiement de votre workflow d’API.

Meilleures pratiques

• Définissez des schémas d’entrée et de sortie clairs afin que les autres produits UiPath puissent comprendre et interagir avec votre workflow.
• Tirez parti de la vitesse d'exécution rapide des workflows d'API pour tester les charges utiles d'entrée et de sortie pendant la phase de conception.
• Utilisez Autopilot pour générer des expressions contextuelles et du code JavaScript.
• Validez les expressions dans le panneau de sortie de l'éditeur d'expressions pour détecter les problèmes de syntaxe ou de logique avant l'exécution.
• Interagissez avec les données d'entrée et de sortie dans le panneau Sortie d'exécution en développant, réduisant ou copiant les valeurs dans le presse-papiers.
• Quittez le workflow au début en configurant une activité Réponse. Réussite ou Échec.
• Dans les activités de boucle , à savoir Pour chaque et Faire pendant, utilisez $input au lieu de $context pour accéder à la sortie de l'objet précédent.
• Utilisez l'activité HTTP pour appeler directement les API lorsqu'un connecteur ne fournit pas la fonctionnalité requise. Choisissez entre l’activité HTTP native ou l’activité de requête HTTP spécifique au connecteur.
• Fournissez des jetons d'authentification dans la propriété En-têtes de l'activité HTTP :

  { 
      Authorization: "<my_token>",
      "Content-Type": "application/json"
  }

  Pour l’authentification de base, utilisez :

  { Authorization: "Basic " + btoa("<username>:<pass>")}