w.c.s. › API »

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.

$ curl -H "Accept: application/json" \
       https://www.example.net/api/forms/newsletter/16/

Le contenu ainsi obtenu est le suivant :

{
    "id": "newsletter/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"
        },
        "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. (cf Authentification pour les explications sur le sujet)

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="
        }
    },
    (...)
  

La valeur de content est le contenu du fichier, encodé en base64.

Liste de formulaires

Ce webservice n'est pas encore stabilisé, son URL peut encore changer dans les futures versions de w.c.s.

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

$ curl -H "Accept: application/json" \
       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) :

$ curl -H "Accept: application/json" \
       https://www.example.net/api/forms/inscriptions/list?filter=pending

Il 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 » :

$ curl -H "Accept: application/json" \
       https://www.example.net/api/forms/inscriptions/list?filter-type=gratuit

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.

$ curl -H "Accept: application/json" \
       https://www.example.net/api/forms/inscriptions/list?full=on

À noter que pour ne pas alourdir l'export en mode full=on, les champs de type « Fichier » ne sont pas exportés.

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.

$ curl -H "Accept: application/json" \
       https://www.example.net/api/forms/inscriptions/list?full=on&anonymise
$ curl -H "Accept: application/json" \
       https://www.example.net/api/forms/inscriptions/10/?anonymise

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.

$ curl -H "Accept: application/json" \
       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.

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

$ curl -H "Accept: application/json" \
       https://www.example.net/api/code/QRFPTSLR
{"url": "http://www.example.net/demarche/23", "err": 0}

En cas d'inexistence du code de suivi donné, une réponse avec un code de retour 404 est retourné.