Complétion et modification d’un formulaire
w.c.s expose une API autorisant les logiciels tiers à transmettre des données structurées permettant la complétion d’un formulaire ou la modification d’un formulaire existant.
Il n’y a aucune vérification du format des données reçues, elles sont enregistrée telles quelles. Les contraintes de validation ou les conditions d’affichage ne sont pas prises en compte.
Complétion d’un formulaire
La complétion d’un formulaire se fait par une requête POST à l’adresse /api/formdefs/slug/submit, le contenu de la requête doit être un dictionnaire contenant obligatoirement un attribut data et optionnellement un attribut meta et un attribut context.
Le slug est l’identifiant non-numérique utilisé dans les URL, il est visible depuis l’écran d’un formulaire, dans la fenêtre de modification du titre.
L’attribut data est obligatoire et contient un dictionnaire dont les clés sont les noms de variable (remplacé ici par varname) des champs du formulaire et les valeurs le contenu de ces champs.
Les champs de type simple tels que « Texte », « Texte long » ou « Courriel » sont des chaînes de caractères.
Les champs de type « Liste » et « Liste à choix multiples » acceptent différentes valeurs selon leur configuration, ceci est décrit dans Transmission des champs « Liste » et « Liste à choix multiple ».
Les champs de type « Date » sont des chaînes de caractères au format ISO-8601, i.e. YYYY-MM-DD.
Les champs de type « Fichier » sont des dictionnaires contenant les clés filename pour le nom de fichier et content pour le contenu de celui-ci, encodé en base64.
Les champs de type « Carte » sont des dictionnaires contenant les clés lat pour la latitute en nombre décimal et lon pour la longitude en nombre décimal.
Les blocs de champs sont des listes de dictionnaires, avec comme clés les différents champs du blocs, par exemple pour un bloc contenant deux champs, avec les identifiants article et quantite : [{"article": "Pomme", "quantite": "2"}, {"article": "Poire", "quantite": 4}]
L’attribut user est optionnel et peut contenir un identifiant permettant d’associer la demande à un usager existant; l’identifiant peut être soit l’identifiant unique (UUID/NameID), passé dans une clé NameID, soit l’adresse électronique de l’usager, passée dans une clé email.
L’attribut meta est optionnel et contient une série de paramètres supplémentaires concernant le formulaire.
Métadonnées
draft |
true pour enregistrer le formulaire comme étant un brouillon. |
backoffice-submission |
true pour enregistrer le formulaire comme étant saisi depuis le backoffice. |
L’attribut context est également optionnel et contient une série de renseignements supplémentaires sur le contexte de l’envoi du formulaire. Les attributs reconnus sont channel, thumbnail_url, user_id et comments.
L’exemple suivant complète un formulaire d’inscription à une newsletter, qui demanderait trois champs : prénom (nom de variable prenom), nom (nom de variable nom) et adresse électronique (nom de variable email).
POST https://www.example.net/api/formdefs/newsletter/submit {"err": 0, "data": {"id": "1"}}
Avec les données suivantes en entrée :
{
"data": {
"prenom": "Marc",
"nom": "L.",
"email": "marc@example.net"
},
"user": {
"email": "marc@example.net"
}
}
Modification d’un formulaire
Un formulaire qui peut être modifié (par la présence d’une action de workflow de type « Édition ») peut également être modifié via un appel à l’API, en faisant un POST sur l’adresse du formulaire.
Les données attendues sont similaires à la création d’un nouveau formulaire, seuls les champs présents seront pris en compte.
Cet appel :
POST https://www.example.net/api/forms/newsletter/1/ {"err": 0}
Avec les données suivantes en entrée, modifiera donc uniquement le champ « email ».
{
"data": {
"email": "marc@example.org"
}
}
Transmission des champs « Liste » et « Liste à choix multiple »
Pour les champs de type « Liste », si le champ est configuré avec une simple liste d’options, la valeur doit être une chaîne tirée de la liste.
"data": {
"varname": "Libellé 1"
}
Si le champ est configuré pour tirer ses options depuis une source de données, la valeur peut être l’identifiant d’une donnée structurée ou si la donnée structurée complète est transmise, l’identifiant de la donnée dans une clé suffixée de _raw, le libellé de la donnée dans la clé normale et éventuellement la donnée structurée complète dans une clé suffixée de _structured.
Identifiant d’une option
"data": {
"varname": "1"
}
Donnée structurée
"data": {
"varname": "Libellé 1",
"varname_raw": "1",
"varname_structured": {
"id": "1",
"text": "Libellé 1",
"foo": "bar"
}
}
Pour les champs de type « Liste à choix multiple », si le champ est configuré avec une simple liste d’options, la valeur doit être une liste de chaînes tirées de la liste.
"data": {
"varname": ["Libellé 1", "Libellé 2"]
}
Si le champ est configuré pour tirer ses options depuis une source de données, la valeur peut être une liste d’identifiants ou, si la donnée structurée complète est transmise, la liste des identifiants de la donnée dans une clé suffixée de _raw, la liste des libellés de la donnée dans la clé normale et éventuellement la liste des données structurées complètes dans une clé suffixée de _structured.
Liste d’identifiants d’options
"data": {
"varname": ["1", "2"]
}
Listes de données structurées
"data": {
"varname": ["Libellé 1", "Libellé 2"],
"varname_raw": ["1", "2"],
"varname_structured": [
{
"id": "1",
"text": "Libellé 1",
"foo": "bar"
},
{
"id": "2",
"text": "Libellé 2",
"foo": "bar2"
}
]
}