Récupération des données d’un formulaire
Il s’agit ici d’une API permettant à un logiciel tiers de récupérer les données associées à un formulaire complété; cet accès peut aussi bien être initié par l’application tierce (mode pull) ou par w.c.s., à différents moments du traitement d’un formulaire (mode push).
Mode « Pull »
L’exemple suivant récupère les données d’un formulaire d’inscription à une newsletter.
GET https://www.example.net/api/forms/newsletter/16/Le contenu ainsi obtenu est le suivant :
{
"id": "16",
"receipt_time": "2013-01-04T13:39:47",
"last_update_time": "2013-01-04T13:41:21",
"fields": {
"email": "marc@example.net",
"nom": "L.",
"prenom": "Marc"
},
"geolocations": {
"base": {
"lat": 10,
"lon": -12,
}
},
"user": {
"id": 1,
"name": "Fred"
},
"workflow": {
"status": {
"id": "1",
"name": "New",
"endpoint": false
},
"data": {
"creation_status": 200,
"creation_response": {
"dn": "cn=marc@example.net,ou=people"
},
"inscription_status": 200,
"inscription_response": {
"liste": "lalettre@example.com"
}
}
},
"roles": {
"_receiver": [
{
"emails_to_members": false,
"name": "Agents traitants",
"text": "",
"emails": [],
"slug": "agents-traitants",
"details": "",
"id": "1",
"allows_backoffice_access": true
}
],
"concerned": [
{
"emails_to_members": false,
"name": "Agents traitants",
"text": "",
"emails": [],
"slug": "agents-traitants",
"details": "",
"id": "1",
"allows_backoffice_access": true
}
],
"actions": [
{
"emails_to_members": false,
"name": "Agents traitants",
"text": "",
"emails": [],
"slug": "agents-traitants",
"details": "",
"name": "test",
"id": "1",
"allows_backoffice_access": true
}
]
},
"submission": {
"backoffice": false,
"channel": "Web"
},
"evolution": [
{
"status": "1",
"time": "2013-01-04T13:39:49",
"user": {
"id": 1,
"name": "Fred"
"email": "fred@example.com",
"NameID": ["123456"]
},
"parts": [
{
"type": "wscall-error",
"summary": "description de l’erreur",
"label": "appel du web-service XYZ",
"data": "données reçues jusqu’à 10000 octets..."
},
{
"type": "workflow-comment",
"content": "commentaire"
}
]
},
]
}Seuls les champs ayant un nom de variable sont exportés dans fields.
Les différentes géolocalisation associées au formulaire sont listées dans l’attribut geolocations. Pour l’instant il n’en existe qu’une toujours nommée base.
Concernant les rôles et fonctions de workflow, les différents intervenants sont listés dans l’attribut roles, en différentes séries qui vont dépendre de fonctions attachées au workflow. Deux séries sont particulières, la série concerned reprend les rôles concernés par la demande et la série actions reprend les rôles disposant d’une capacité d’action sur la demande.
L’information sur l’origine de la demande, si la saisie a eu lieu depuis le backoffice et quel était le canal d’origine de la demande, est disponible dans l’attribut submission.
L’historique du formulaire, ses transitions dans différents statuts, est disponible dans l’attribut evolution. Cette liste de dictionnaires contient l’instant de la transition dans l’attribut time, le code du statut concerné dans status et une description de l’utilisateur responsable de la transition dans user. L’attribut optionnel parts peut contenir une liste de dictionnaires liés aux actions de workflow, comme un commentaire ou une erreur lors de l’appel d’un web service.
Il est bien sûr nécessaire de disposer des autorisations nécessaires pour accéder ainsi aux données d’un formulaire.
Mode « push »
Il est également possible pour un workflow d’être configuré pour transmettre les données à une URL fournie par une application tierce. Un document JSON (tel celui donné plus haut) est alors transmis en utilisant la méthode POST.
En retour, l’application tierce peut fournir un objet JSON qui sera enregistré dans les données du workflow du formulaire (voir le dictionnaire "data" dans l’exemple ci-dessus).
Types de données
Les données d’un formulaire sont placées dans le champs fields de la réponse. Les champs de type simple tels que « Texte », « Texte long » ou « Courriel » sont vus en tant que chaîne de caractères :
(...)
"fields": {
"email": "marc@example.net",
"nom": "L.",
"prenom": "Marc"
},
(...)
Représentation d’un champ « Fichier »
Les champs de type « Fichier » sont exportés selon le schéma suivant :
(...)
"fields": {
"photo": {
"filename": "exemple.txt",
"content_type": "text/plain",
"content": "Q2VjaSBuJ2VzdCBwYXMgdW4gZXhlbXBsZS4=",
"url": "https://.../"
}
},
(...)
La valeur de content est le contenu du fichier, encodé en base64.
Liste de formulaires
La liste des demandes pour un formulaire donné est destinée à être utilisée par un système de synchronisation. Elle ne retourne donc pour chaque demande que son numéro (id), ses dates de création et de dernière mise à jour.
Un système de synchronisation vérifiera depuis cette liste si de nouvelles demandes existent, ou si certaines ont été mises à jour, sont obsolètes ou effacées, puis effectuera pour chacune les actions nécessaires (pull, push, etc.).
GET https://www.example.net/api/forms/inscriptions/list[
{
"url": "https://www.example.net/inscriptions/1/",
"last_update_time": "2015-03-26T23:08:45",
"receipt_time": "2015-03-26T23:08:44",
"id": 1
},
{
"url": "https://www.example.net/inscriptions/3/",
"last_update_time": "2015-03-27T12:11:21",
"receipt_time": "2015-03-27T12:45:19",
"id": 3
}
]Des paramètres peuvent être envoyés dans la requête pour filtrer le listing voulu. Il s’agit des mêmes paramètres que pour l’export ou le listing en backoffice, sauf pour filter qui est fixé à all par défaut. Pour avoir une liste limitée aux demandes non terminées (pending) :
GET https://www.example.net/api/forms/inscriptions/list?filter=pendingIl est également possible de filtrer sur le contenu des formulaires, à partir des champs associés à un nom de variable et de type « Liste ». Par exemple sur un champ « Type » (nom de variable type) dont une des valeurs possibles est « gratuit » :
GET https://www.example.net/api/forms/inscriptions/list?filter-type=gratuitD’autres paramètres de filtres existent. Pour filtrer sur les demandes déposées après une date donnée (?filter-start=on&filter-start-value=2020-01-03), ou avant une date donnée (?filter-end=on&filter-end-value=2020-01-03) et de la même manière sur les demandes modifiées après ou avant une date, (?filter-start-mtime=on&filter-start-mtime-value=2020-01-03 ou ?filter-end-mtime=on&filter-end-mtime-value=2020-01-03). Pour filtrer selon l’usager associé (?filter-user-uuid=XYZ) ou selon l’appartenance d’un usager à une fonction particulière (?filter-user-function=_mandataire&filter-user-uuid=XYZ). Et pour filtrer selon l’agent qui a fait la saisie en backoffice (?filter-submission-agent-uuid=XYZ).
Afin de faciliter certains traitements batch, il est possible de demander que l’ensemble des données associées aux formulaires soient retourné, plutôt qu’un jeu réduit adapté aux systèmes de synchronisation. Pour ce faire, il suffit de passer un paramètre full=on dans l’adresse.
GET https://www.example.net/api/forms/inscriptions/list?full=onÀ noter que pour ne pas alourdir l’export en mode full=on, le contenu des champs de type « Fichier » n’est pas exporté.
Données anonymisées
Les API « Liste de formulaires » et le mode Pull de récupération d’un formulaire acceptent un paramètre supplémentaire anonymise. Quand celui-ci est présent des données anonymisées des formulaires sont renvoyées et les contrôles d’accès sont simplifiés à une signature simple, il n’est pas nécessaire de préciser l’identifiant d’un utilisateur.
GET https://www.example.net/api/forms/inscriptions/list?full=on&anonymise GET https://www.example.net/api/forms/inscriptions/10/?anonymise
Par ailleurs, l’API « Liste de formulaires » accepte un paramètre include-anonymised permettant d’inclure (on) ou non (off) les demandes anonymisées dans la liste :
GET https://www.example.net/api/forms/inscriptions/list?include-anonymised=onDonnées de l’ensemble des formulaires
De manière similaire à l’API de récupération de la liste des demandes d’un formulaire, il est possible de récupérer l’ensemble des demandes de la plateforme, peu importe leurs types.
GET https://www.example.net/api/forms/{
"data": [
{
"url": "https://www.example.net/inscriptions/1/",
"last_update_time": "2015-03-26T23:08:45",
"receipt_time": "2015-03-26T23:08:44",
"id": 1
},
{
"url": "https://www.example.net/inscriptions/3/",
"last_update_time": "2015-03-27T12:11:21",
"receipt_time": "2015-03-27T12:45:19",
"id": 3
},
{
"url": "https://www.example.net/signalement/1/",
"last_update_time": "2015-03-25T14:14:21",
"receipt_time": "2015-03-25T14:48:20",
"id": 1
}
]
}Des paramètres peuvent être envoyés dans la requête pour filtrer les résultats. Il s’agit des mêmes paramètres que ceux du tableau global en backoffice. Par exemple, pour avoir une liste limitée aux demandes terminées :
GET https://www.example.net/api/forms/?status=doneLe paramètre full n’est pas pris en charge dans cette API; le paramètre anonymise non plus, les données l’étant déjà.
Données géolocalisées
Pour les formulaires définissant une prise en charge de la géolocalisation, il est possible de récupérer les données au format GeoJSON, en faisant appel au webservice /geojson.
GET https://www.example.net/api/forms/inscriptions/geojson { "type": "FeatureCollection", "features": [ { "geometry": { "type": "Point", "coordinates": [ 1.23456789, 50.1234567 ] }, "type": "Feature", "properties": { "url": "http://example.net/backoffice/management/inscriptions/28/" } } ] }
De manière identique aux appels précédents, des filtres peuvent être passés dans l’URL.
Les URL retournées pour les demandes pointent vers l’interface de gestion de celles-ci.
Il est également possible d’obtenir les informations géographiques de l’ensemble des demandes :
GET https://www.example.net/api/forms/geojsonCode de suivi
Une API existe pour déterminer l’existence d’un code de suivi et, le cas échéant, découvrir la demande associée.
GET https://www.example.net/api/code/QRFPTSLR {"url": "...", "load_url": "...", "err": 0}
Dans l’attribut url se trouvera l’adresse native de la demande, qui demandera authentification de l’utilisateur, et dans l’attribut load_url une adresse permettant de charger la demande sur la seule foi de l’accès. Il est important d’utiliser cette adresse et de ne pas essayer de la construire manuellement avec le code de suivi car elle peut évoluer. Pour cette même raison elle devrait être utilisée immédiatement, sans être stockée.
En cas d’inexistence du code de suivi donné, une réponse avec un code de retour 404 est retourné.