Appeler un webservice

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.

Édition

Les étapes d'édition de l'action « Webservice » sont les suivantes :

1. Indiquer le libellé de l'appel du webservice.

2. 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}}

3. 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.

4. 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 ».

5. « 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.

6. 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}}

   formera ce JSON :

     {
       "code_appel": "w.c.s.",
       "form_number": "4"
     }

7. Le paramètre « Identifiant » permet d'enregistrer le résultat retourné par l'appel dans des variables nommées form_workflow_response_IDENTIFIANT_…

   • form_workflow_response_IDENTIFIANT_datetime pour récupéer la date et l’heure de l’appel,

   • form_workflow_response_IDENTIFIANT_url pour récupérer l’URL appelée,

   • form_workflow_response_IDENTIFIANT_status pour récupérer le code de statut HTTP de la réponse (200 signifie qu’elle s’est bien passée),

   • form_workflow_response_IDENTIFIANT_success pour récupérer un booléen indiquant si la requête s’est bien passée,

   • form_workflow_response_IDENTIFIANT_response_… pour récupérer le contenu de la réponse, avec un accès standardisé aux détails de celle-ci, par exemple form_workflow_response_IDENTIFIANT_response_data pour accéder à la clé data,  pour accéder à la clé form_workflow_response_IDENTIFIANT_response_data_0_id du premier élément de la clé data, etc.

8. L'onglet « gestion des erreurs » permet de faire partir la demande dans le statut de votre choix lorsque l'appel renvoie une erreur. Cela permet d'identifier rapidement une demande en erreur.