Informations importantes
Ce guide est conçu pour les personnes souhaitant intégrer des applications tierces à leur portail CoreView. Cela peut être pertinent si vous souhaitez déclencher un Workflow en réponse à des événements spécifiques tels que :
- Les RH soumettent un nouveau formulaire après l’embauche d’un nouvel employé ;
- La création d’un nouveau ticket dans un système de gestion de tickets d’incident.
Cependant, si votre portail CoreView est exclusivement géré par des administrateurs et des opérateurs de tenant humains, vous pouvez ignorer entièrement cette section.
L’objectif de cet article est de fournir à nos clients les informations nécessaires concernant les exigences, les prérequis et le processus étape par étape pour intégrer avec succès des applications tierces à votre tenant CoreView via l’API CoreView.
Les lecteurs visés par cet article et l’exécution des activités décrites sont des membres seniors du personnel technologique de votre organisation qui prennent en charge les services d’entreprise.
Il est crucial que les personnes appropriées au sein de votre organisation examinent les informations fournies ici et contactent CoreView pour toute question avant de planifier un déploiement.
Vue d’ensemble
Les instructions suivantes expliquent comment l’API CoreView peut être utilisée pour exécuter vos CoreView Workflows. Actuellement, l’API CoreView est simple à utiliser et prend en charge l’interaction avec les Workflow. Cela signifie que les seules actions que vous pouvez gérer de manière programmatique avec l’API publique sont :
- Obtenir les exécutions de Workflow
- Obtenir l’historique d’exécution des Workflow
- Démarrer des exécutions manuelles
- Lister les Workflows
- Obtenir les détails du Workflow
- Obtenir le jeton JWT
Avant d’utiliser l’API, vous devez déployer au moins un Workflow dans votre portail CoreView ; sinon, aucune méthode API ne peut être utilisée pour interagir avec CoreView.
Veuillez noter que les valeurs restreintes des entrées de Workflow sont actuellement appliquées uniquement dans l’interface utilisateur de l’application web, et non lors de l’exécution via l’API.
Si une entrée de Workflow est configurée avec un ensemble limité de valeurs autorisées, les opérateurs lançant le Workflow depuis l’application web peuvent sélectionner uniquement parmi les valeurs configurées. Toutefois, lorsque le même Workflow est démarré via l’API, il est actuellement possible de soumettre une valeur qui n’est pas incluse dans la liste configurée.
Si la valeur soumise est acceptée par la logique d’exécution du downstream tenant, le Workflow peut tout de même s’exécuter correctement. Par conséquent, la configuration des valeurs autorisées doit actuellement être comprise comme un contrôle au niveau de l’interface utilisateur, plutôt qu’une règle de validation au niveau du moteur.
Le tableau suivant résume ce qui est actuellement pris en charge :
| Pris en charge | Actuellement non pris en charge |
|---|---|
| Restriction des valeurs sélectionnables dans l’interface web | Application de la validation des listes restreintes au niveau du moteur de workflow |
| Orientation des opérateurs vers des valeurs prédéfinies lors du lancement manuel d’un Workflow dans l’application | Rejet des exécutions API lorsque les valeurs soumises sont en dehors de la liste d’entrées configurée |
| Retour d’une erreur de validation spécifiquement basée sur les règles de liste restreinte définies dans le concepteur de Workflow |
Si une validation stricte est requise pour l’exécution de Workflow via l’API, la validation doit actuellement être gérée en dehors de la couche de requête de la plateforme, soit par le système appelant avant la soumission de l’appel API, soit en ajoutant une logique de validation directement dans le Workflow.
PostMan
L’intégration API permet aux clients d’invoquer n’importe quel Workflow CoreView depuis des plateformes externes capables d’appeler des URL et de leur transmettre des valeurs.
Dans ce guide, nous utiliserons PostMan comme logiciel simulant l’appel API vers le centre de données CoreView. Vous pouvez télécharger la dernière version de PostMan ici.
PostMan est une plateforme API gratuite pour créer et utiliser des API. Elle simplifie chaque étape du cycle de vie des API et rationalise la collaboration, vous permettant de comprendre plus rapidement comment travailler avec les API.
Dans un premier temps, veuillez importer le fichier « CoreFlow Public API.postman_collection.json » dans votre tableau de bord Postman. Cela affichera toutes les méthodes que vous pouvez appeler.
Pour importer le fichier JSON, suivez ces étapes :
- Ouvrez Postman et créez un compte.
- Cliquez sur l’icône dans le coin supérieur droit.
- Sélectionnez : « File » > « Import ».
- Cliquez sur « Import an existing file ».
- Sélectionnez le fichier « CoreFlow Public API.postman_collection.json » que vous avez enregistré sur votre ordinateur.
Détails de l’API CoreView
Vous êtes maintenant prêt à appeler les méthodes de l’API CoreView. Avant d’appeler une méthode, vous devez gérer l’authentification.
L’authentification est gérée au moyen d’une clé API, requise pour générer un bearer token que vous devez utiliser dans chaque appel de méthode.
Pour obtenir votre bearer token, cliquez sur « Get JWT API » et définissez l’URL suivante : https://www.loginportal.online/api/auth
Générez votre clé API
Vous devez remplacer la clé API dans la section Headers par votre propre clé API, qui peut être générée dans votre portail CoreView :
Étape 1
Connectez-vous à votre portail CoreView avec des droits d’administration, ouvrez le menu déroulant « SETTINGS » et sélectionnez « API keys ».
Étape 2
Pour ajouter une nouvelle clé API, cliquez sur le bouton « Add new API key ».
Dès que vous créez la clé API, assurez-vous de la copier, car elle ne sera plus visible.
Méthode 1 : Obtenir le jeton JWT
Revenez à Postman, sélectionnez « Headers » et collez la clé API que vous venez de copier dans le champ nommé « Authorization » :
Une fois que vous avez cliqué sur « Send », vous recevrez un bearer token dans la section body du résultat, que vous utiliserez pour tout appel supplémentaire à une méthode API.
Veuillez noter que les jetons expirent au bout de 48 heures (environ 2 jours). Nous recommandons donc de générer un bearer token pour chaque requête.
Si vous souhaitez vérifier les détails du bearer token, copiez la valeur du jeton sur le site jwt.io, et vous verrez toutes les informations liées à votre jeton.
La date d’expiration sera affichée dans le champ « exp ». Survolez la valeur « exp » avec votre souris et vous verrez quand votre bearer token expire :
ID
Méthode 2 : Lister les Workflows
Cliquez maintenant sur l’élément « List Workflows » et remplacez la valeur d’autorisation par le bearer token que vous venez de générer :
Veuillez noter que pour appeler une méthode API, vous avez également besoin de la valeur « X-scompany ID ». Vous devez contacter votre consultant CoreView pour obtenir le X-scompany ID attribué à votre tenant CoreView.
Méthode 3 : Démarrer une exécution manuelle
Voyons maintenant comment démarrer un Workflow à l’aide de la méthode « Start Manual Execution ». Pour exécuter un Workflow, vous devez modifier l’URL afin d’appeler le centre de données CoreView correct.
Veuillez vous référer au tableau suivant pour identifier les URL appropriées à utiliser :
| URL de l’API V2 | |
|---|---|
| Authentification GOV US | https://uslogin.coreview.com/api/auth |
| Authentification (tous les autres DC) | https://www.loginportal.online/api/auth |
| Europe | https://coreflowapi.coreview.com |
| Canada | https://coreflowcaeapi.coreview.com |
| Est des États-Unis | https://coreflowusapi.coreview.com |
| Gov US | https://coreflowusgovapi.coreview.com |
| Australie | https://coreflowausapi.coreview.com |
Veuillez consulter toutes les étapes du processus ci-dessous :
Étape 1
Après avoir obtenu l’URL de votre centre de données, définissez-la dans la section « POST » de la méthode « Start Manual Executions ».
Étape 2
Vous pouvez trouver l’ID du Workflow dans la liste obtenue précédemment lors de l’exécution de l’API « Get Workflow Details ». Vous pouvez également trouver les mêmes informations dans la réponse JSON de l’API « List Workflows » que vous avez exécutée auparavant.
Étape 3
Maintenant, définissez l’URL avec l’ID du Workflow que vous souhaitez exécuter.
Étape 4
Définissez le bearer token et l’ID de l’entreprise dans la section headers de votre Workflow.
Étape 5
Si votre Workflow attend certaines variables d’entrée, cliquez simplement sur le Workflow que vous devez exécuter de manière programmatique dans le portail CoreView, puis affichez les variables d’entrée en cliquant sur « Edit Workflow » puis sur « Configure Execution Inputs ».
Si une variable d’entrée est configurée avec des valeurs restreintes, cette restriction n’est appliquée que dans l’interface utilisateur de l’application web. Les exécutions API ne valident actuellement pas la valeur soumise par rapport à la liste configurée des valeurs autorisées.
Étape 6
Maintenant, cliquez sur la section « Body » de votre fenêtre PostMan et définissez les propriétés en fonction des variables d’entrée que vous venez de vérifier.
Méthode 4 : Obtenir l’exécution du Workflow
Cela est utile pour obtenir les méthodes d’exécution de votre Workflow, par exemple pour vérifier si un Workflow spécifique est en cours d’exécution.
Copiez simplement l’ID de votre Workflow et collez-le dans la commande « GET » de l’API « Get Workflow Executions ».
Veuillez consulter toutes les étapes du processus ci-dessous :
Étape 1
Vous pouvez interroger un Workflow à la fois en définissant le filtre sur « Running ».
Étape 2
N’oubliez pas de définir l’ID de l’entreprise et le bearer token dans la section « Headers ».
Étape 3
Une fois cela fait, cliquez sur le bouton « Send » et vous récupérerez le Workflow en cours d’exécution à ce moment précis.
Méthode 5 : Obtenir l’historique d’exécution du Workflow
Il s’agit de la dernière méthode API disponible. Elle vous fournira les détails du Workflow exécuté, similaires aux détails que vous pouvez obtenir lorsque vous consultez l’historique d’exécution du Workflow dans le portail CoreView :
Veuillez consulter toutes les étapes du processus ci-dessous :
Étape 1
Définissez l’URL pour appeler l’ID du Workflow et l’ID d’exécution que vous venez d’obtenir à partir de « Get Workflow Execution ».
Étape 2
L’ID du Workflow est le même que celui que vous avez exécuté.
Étape 3
Copiez l’ID d’exécution depuis la réponse JSON que vous avez reçue lors de l’exécution de « Get Workflow Executions ».
Étape 4
N’oubliez pas de définir le bearer token d’autorisation et l’ID de l’entreprise dans la section « Headers » de votre requête.
Étape 5
Après avoir cliqué sur le bouton bleu « Send » dans la fenêtre PostMan, vous trouverez tous les détails concernant le Workflow que vous venez d’exécuter. Vous pouvez utiliser cette sortie JSON pour tout besoin spécifique.
