doc: add page on the "webservice call" workflow action

help/fr/wf-wscall.page

@@ -0,0 +1,76 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" id="wf-wscall" xml:lang="fr">
+
+<info>
+  <link type="guide" xref="index#wf" />
+  <revision docversion="0.1" date="2015-05-01" status="draft"/>
+  <credit type="author">
+    <name>Frédéric Péters</name>
+    <email>fpeters@entrouvert.com</email>
+  </credit>
+
+</info>
+
+<title>Appel à un webservice</title>
+
+<p>
+Cette action permet d'appeler un système tiers et d'éventuellement lui
+transmettre les données du formulaire en cours.
+</p>
+
+<p>
+Le champ URL est obligatoire, il doit contenir l'adresse qui sera appelée,
+celle-ci peut contenir des <link xref="misc-substvars">variables</link>, pour
+par exemple transmettre une information particulière.
+</p>
+
+<example>
+ <code>https://www.example.net/notify?email=[session_user_email]</code>
+</example>
+
+<p>
+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 <code>POST</code>, dont le contenu correspondra au formulaire encodé au
+format JSON, comme décrit dans cette <link xref="api-get#pull">page sur
+l'API</link>.
+</p>
+
+<p>
+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
+<code><var>variable</var>_status</code> (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 <code><var>variable</var>_response</code>.
+</p>
+
+<p>
+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.
+</p>
+
+<section>
+ <title>Traitement des erreurs</title>
+
+ <p>
+  En précisant un nom de variable (exemple : <code>webservice</code>), il est
+  possible de placer derrière l'appel au webservice une action de <link
+  xref="wf-jump">changement de statut automatique</link> faisant référence
+  à la variable.
+ </p>
+
+ <p>
+  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 <code>data</code> dont la clé <code>result</code> valait
+  <code>OK</code> :
+ </p>
+
+ <example>
+  <code>webservice_status != 200 or webservice_response_data_result != 'OK'</code>
+ </example>
+
+</section>
+
+</page>