Modifiée par : Frédéric Péters

Appeler un webservice

Cette action est plus technique que les autres et peut nécessiter qu'un connecteur vers une application tierce ait été développé au préalable. Elle est utilisée/configurée par les services informatiques.

Généralités

L'action « Webservice » permet d'appeler un système tiers et, éventuellement, de lui transmettre des données, dont celles issues de formulaires de demandes d'usagers ayant atteint le statut qui contient cette action.

L'action webservice permet de générer un fichier plutôt qu'une réponse JSON en cochant « Fichier joint » comme type de réponse (dans l'onglet réponse). Si une donnée de traitement de type « Fichier » existe dans le workflow, il sera possible de la lier à ce fichier en la sélectionnant dans la liste déroulante « Enregistrer le document généré comme donnée de traitement ».

Édition

Les étapes d'édition de l'action « 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, pour afficher une information particulière. Dans « Données à envoyer en paramètres à l'URL », on peut spécifier un couple clé/valeur. Par exemple en utilisant email et {{session_user_email}}, on va pouvoir former une URL qui sera https://www.example.net/notify?email={{session_user_email}}
Choisir la méthode utilisée
- GET : pour récupérer un élément
- POST : Pour envoyer un élément
- PUT : Pour créer un élément
- PATCH : Pour mettre à jour un élément
- DELETE : pour effacer un élément
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.
Dé/Cocher la case « Envoyer les données du formulaire ».

Ce choix est proposé si méthode POST, PUT ou PATCH choisie. Cochée, la case indique que l'ensemble des données du formulaire doit être transmis, avec un appel dont le contenu correspondra au formulaire encodé au format JSON, comme décrit sur cette page sur l'API.

Si la case « Envoyer les données du formulaire » est cochée et que des « Données à envoyer dans le corps de la requête » sont indiquées, alors ces dernières sont ajoutées dans le JSON du formulaire, dans une clé « extra ».
« Données à envoyer dans le corps de la requête » permet d'indiquer les 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.
Exemple

Ce tableau de valeurs :

code_appel

w.c.s.

form_number

{{form_number}}

~~form_number~~

formera ce JSON :
```
{
    "code_appel": "w.c.s.",
    "form_number": "4"
  }
```
Le paramètre « Identifiant » permet d'enregistrer le résultat retourné par l'appel dans une variable du type {{ form_workflow_data_IDENTIFIANT_response_XXX }} . Quand la réponse correspond au format classique des API Publik, on aura :
- {{ form_workflow_data_IDENTIFIANT_response_data }} pour récupérer les données retournées en JSON,
- {{ form_workflow_data_IDENTIFIANT_response_data.0 }} pour récupérer le premier enregistrement d'un tableau JSON,
- {{ form_workflow_data_IDENTIFIANT_response_data.0.NOM-COLONNE }} pour récupérer la valeur d'une colonne du tableau pour un enregistrement donné,
- {{ form_workflow_data_IDENTIFIANT_status }} pour récupérer le statut http de la requête (200 signifie qu'elle s'est bien passée),
- {{ form_workflow_data_IDENTIFIANT_response_err }} pour récupérer les erreurs (1 signifie qu'il y a eu une erreur, 0 signifie qu'il n'y en a pas eu)

Attention lorsque l'on utilise l'API d'Authentic (le fournisseur d'identité qui gère les rôles et les utilisateurs), la réponse ne se trouvera pas dans la variable
{{ form_workflow_data_IDENTIFIANT_response_data}} mais plutôt dans
{{ form_workflow_data_IDENTIFIANT_response_results}}

Appel à un webservice

Cette action permet d’appeler un système tiers et d’éventuellement lui transmettre des données, dont celles du formulaire en cours.

Le champ URL est obligatoire, il doit contenir l’adresse qui sera appelée, celle-ci peut contenir des variables, pour par exemple transmettre une information particulière.

https://www.example.net/notify?email={{session_user_email}}

Le tableau « Données à envoyer en paramètre » permet de décrire des données qui seront transmises sous la forme de paramètres d’URL. 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 « = ». Les paramètres d’URL ne peuvent être que des chaînes, si ce n’est pas le cas la donnée sera transformée en chaîne de force.

La case à cocher « Envoyer le formulaire (POST, en JSON) » indique que l’ensemble des données du formulaire doivent être transmises, avec un appel de type POST, dont le contenu correspondra au formulaire encodé au format JSON, comme décrit dans 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 une action de changement de statut automatique 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'

Appeler un webservice

Généralités

Édition

Exemple

Appel à un webservice

Traitement des erreurs