Services web
Déclarer les API externes (ERP, outil de CAO) appelées par les actions des tâches et les automatisations, les tester et lire le journal des appels
À quoi ça sert
Un service web est une API externe, par exemple un ERP ou un outil de CAO, que Deltia appelle pour envoyer ou récupérer des données. Un administrateur du module Connecteurs la déclare une fois. Elle sert ensuite à deux endroits :
- une action sur une tâche : un bouton sur la tâche envoie les données de la tâche au service, puis écrit dans la tâche les valeurs qu'il renvoie ;
- une règle d'automatisation dont l'action est « Appeler un web service ».
Deux onglets de l'administration des connecteurs y sont consacrés : « Services web » (les connexions) et « Journal des appels » (l'historique des envois).
Concepts clés
- Service web — une connexion à une API : adresse de base, authentification et secret.
- Workflow — la suite d'appels que fait une action, dans l'ordre ; chaque appel peut lire ce que les précédents ont renvoyé. Il est défini dans l'action de la tâche ou de la règle, pas sur le service.
- Appel — une exécution d'un workflow, avec les requêtes envoyées et les réponses reçues.
- Reprise — relancer une action déjà exécutée : les étapes réussies ne sont pas renvoyées quand elles ne peuvent pas l'être sans risque.
Comment faire
Déclarer un service web
- Ouvrez l'administration des connecteurs, onglet « Services web ».
- Cliquez sur « Ajouter un service web ».
- Renseignez le « Nom » et l'« Adresse de base (https) ».
- Choisissez l'« Authentification » et saisissez ses champs (voir la référence).
- Cliquez sur « Enregistrer ».
Le service apparaît avec le statut « Actif » : il est utilisable tout de suite. Il n'est pas modifiable ; pour changer son adresse ou son secret, révoquez-le, supprimez-le et déclarez-le de nouveau.
Tester un service web
- Dans la ligne d'un service « Actif », cliquez sur « Tester ».
Un message indique « Service joignable : réponse HTTP … en … ms », ou la cause de l'échec : « Authentification refusée par le service », « Service injoignable », « Connexion inutilisable ».
Révoquer puis supprimer un service web
- Cliquez sur « Révoquer » dans la ligne d'un service « Actif ».
- Une fois le statut « Révoqué », cliquez sur « Supprimer ».
Lancer une action depuis une tâche
- Ouvrez la tâche dont le type porte une action de web service.
- Renseignez les champs que l'action demande : sinon le bouton reste désactivé et la mention « À renseigner : … » les liste.
- Cliquez sur le bouton de l'action.
La mention « En cours… » puis « Terminé » s'affiche, et les champs que le service renvoie sont remplis sur la tâche. En cas d'échec, « Dernier envoi en échec » donne le code d'erreur. Si l'écriture des résultats sur la tâche échoue, un message le précise. Voir Types de tâches pour déclarer l'action.
Relancer une action
Quand une étape a peut-être déjà été appliquée par le service, la fenêtre « Vérifier avant de renvoyer » apparaît. Contrôlez dans le système externe, puis cliquez sur « J'ai vérifié, renvoyer » : sinon l'étape pourrait être créée en double. Une action dont aucune étape ne peut être rejouée affiche « Déjà exécuté ».
Lire le journal des appels
- Ouvrez l'onglet « Journal des appels ».
- Filtrez par connexion, code d'erreur, étape en échec ou date.
- Cliquez sur une ligne.
Le détail liste les « Valeurs envoyées », puis chaque étape avec sa « Requête », sa « Réponse », le nombre de tentatives et les « Valeurs récupérées ». Les secrets sont retirés et les corps tronqués à 64 Ko. L'« Origine » est « Action sur une tâche » ou « Automatisation ».
Référence
Authentifications
| Mode | Champs |
|---|---|
| « Aucune » | aucun |
| « Jeton Bearer » | « Secret » |
| « Clé d'API » | « Transmise dans » (l'en-tête ou l'adresse), « Nom de l'en-tête ou du paramètre », « Secret » |
| « Identifiant et mot de passe » | « Identifiant », « Secret » |
| « OAuth2 (client credentials) » | « Adresse du jeton (https) », « Identifiant client », « Portée (optionnel) », « Secret » |
Le secret est chiffré et n'est plus jamais affiché.
Statuts d'un service
| Statut | Actions possibles |
|---|---|
| « Actif » | « Tester », « Révoquer » |
| « Révoqué » | « Supprimer » |
Statuts d'un appel
« En attente », « En cours », « Terminé », « Échoué ». Une étape est « En cours », « Terminée », « Échouée », « Ignorée » ou « Reprise du run précédent ».
Règles
- Les adresses doivent être en https ; les adresses internes et les redirections sont refusées.
- Si l'organisation limite les domaines autorisés, un super-administrateur de Deltia doit y ajouter ceux du service : le test affiche alors « domaine non autorisé par la politique ».
- Un appel interrompu est repris automatiquement. Les appels plus anciens que 90 jours sont purgés, sauf le dernier d'une action encore relançable.
Questions fréquentes
Qui voit le journal des appels ? Les administrateurs du module Connecteurs.
Le service appelle-t-il deux fois en cas de double clic ? Non : une action n'a qu'un appel en attente ou en cours à la fois.