L'élément "Appeler un webservice", de type Type "Actions administratives requises par un statut" permet d'appeler un système tiers; et éventuellement, de lui transmettre des données, dont celles issues de formulaires de demandes du'usagers ayant atteint le statut que cet élément configure.
L'ajout de cet élément à un statut s'effectue depuis la barre latérale de la page "Détail" du statut à configurer.
Dans la vue graphique d'un workflow, l'élément "Appeler un webservice" est symbolisé par une boucle fléchée, indiquant, le statut affecté de cet élément.
L'édition des paramètres d'un élément s'effectue depuis le plan de travail de la page d'édition de l'élément accessible en cliquant sur le bouton "Éditer" associé à l'élément à éditer listé sur la page "Détail" du statut que cet élément configure.
Les étapes d'édition de l'élément "Appeler un webservice" sont les suivantes :
Indiquer le libellé de l'appel du webservice.
Saisir l'URL du webservice sollicité.
* Le champ "URL" est obligatoire.
* L'URL peut contenir des Variables de substitution, pour afficher une information particulière.
https://www.example.net/notify?email=[session_user_email]
Dé/Cocher la case « Envoyer le formulaire (POST, en JSON) ».
Cochée, la case indique que l'ensemble des données du formulaire doit être transmis, avec un appel de type POST, dont le contenu correspondra au formulaire encodé au format JSON, comme décrit sur cette page sur l'API.
Le tableau « Données à envoyer en POST » permet de décrire des données qui seront transmises sous la forme d'un dictionnaire clé-valeur au format JSON.
Sur chaque ligne, la colonne de gauche est le nom de la clé, celle de droite, la valeur. La valeur peut être une expression Python. Pour cela, elle doit commencer par le signe « = ».
Ce tableau de valeurs :
code_appel |
w.c.s. |
form_number |
=form_number |
formera ce JSON :
{
"code_appel": "w.c.s.",
"form_number": "4"
}Si la case « Envoyer le formulaire (POST, en JSON) » est cochée et que des « Données à envoyer en POST » sont indiquées, alors ces dernières sont ajoutées dans le JSON du formulaire, dans une clé « extra ».
Si aucune donnée n'est indiquée et que le formulaire ne doit pas être transmis, alors la requête HTTP effectuée est un GET sur l'URL.
Le paramètre « Nom de variable » permet d'enregistrer le résultat retourné par le webservice. Le retour HTTP de celui-ci sera enregistré dans variable_status (voir plus loin, le traitement des erreurs) et le contenu même de la réponse, si elle est au format JSON, sera enregistré dans variable_response.
Le paramètre « Clé de signature de la requête » permet de signer la requête avant de l'envoyer au webservice, avec la valeur du champ comme clé de signature.
Traitement des erreurs:
En précisant un nom de variable (exemple : webservice), il est possible de placer derrière l'appel au webservice l'élément "Changer de statut automatiquement" faisant référence à la variable.
Par exemple, pour s'assurer que le retour fait par le webservice était bien un code HTTP 200 et que le contenu de la réponse contenait bien un dictionnaire data dont la clé result valait OK :
webservice_status != 200 or webservice_response_data_result != 'OK'
D'autres types d'actions administratives peuvent être requises par un statut :
* Agréger dans un message récapitulatif,
* Anonymiser,