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