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é par un usager; cet accès peut aussi bien être initié par l'application tierce (mode pull) ou par Publik, à différents moments du traitement d'une demande d'usager (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/inscriptions/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"
    },
    "user": {
        "id": 1,
        "name": "Fred"
    },
    "workflow": {
        "status": {
            "id": "new",
            "name": "New"
        },
        "data": {
            "creation_status": 200,
            "creation_response": {
                "dn": "cn=marc@example.net,ou=people"
            },
            "inscription_status": 200,
            "inscription_response": {
                "liste": "lalettre@example.com"
            }
        }
    }
}

Seuls les champs ayant un nom de variable sont exportés dans fields.

Il est bien sûr nécessaire de disposer des autorisations nécessaires pour accéder ainsi aux données d'un formulaire. (cf api-auth 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 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