Opérations sur les Données

Réalisez des opérations sur les Donnée telles que la récupération, la lecture, la recherche avancée ou encore l'enregistrement.

1. Opérations sur les Données

1.1. Lire les nouvelles données d'un formulaire pour une action

Cette fonction permet de lire toutes les données d'un formulaire, non marquées pour un {tag}. Cela donne donc la possibilité de lire les mêmes données pour plusieurs actions différentes.

Il s'agit d'envoyer une requête en GET à l'URL : https://forms.kizeo.com/rest/v3/forms/{formId}/data/unread/{tag}/{limit}?includeupdated

Si tout s'est bien passé, vous recevrez une réponse du type :

[
    {
        "_id": "string",
        "_record_number": "string",
        "_form_id": "string",
        "_user_id": "string",
        "_create_time": "string",
        "_update_time": "string",
        "_update_user_id": "string",
        "_update_answer_time": "string",
        "_start_time": "string",
        "_end_time": "string",
        "_direction": "string",
        "_recipient_id": "string",
        "_history": "string",
        "_form_unique_id": "string",
        "_origin_answer": "string",
        "_answer_time": "string",
        "_user_name": "string",
        "_update_user_name": "string",
        "_recipient_name": "string",
        "_transform_status": "string" ou null,
        "_can_edit": boolean,
        "_can_delete": boolean,
        "_contains_file": boolean,
        "_can_send_mail": boolean,
        "_pull_time": "string",
        "_user_ref1": "string",
        "..."
        "_user_ref20": "string",
        "_update_user_ref1": "string" ou null,
        "_update_user_ref2": "string" ou null,
        "..."
        "_update_user_ref20": "string" ou null,
        "_recipient_user_ref1": "string" ou null,
        "..."
        "_recipient_user_ref20": "string" ou null,
        "field": "string",
        "..."
    },
    ...
]

• {tag}: nom de l'action sous forme de chaîne de caractères (string).
• {limit}: nombre maximum de données lues.
• ?includeupdated: inclus des données marquées comme lues mais qui ont été modifiées depuis (optionnel)

Cette fonction a une option de format. Soit simple soit basic. Avec simple la requête ne retourne que le premier niveau de la donnée. Avec basic, la donnée retourne complète.

Pour récupérer l'intégralité de la donnée, il faut donc construire la requête comme suit :
https://forms.kizeo.com/rest/v3/forms/{{formId}}/data/unread/{tag}/100?includeupdated&format=basic

Après avoir lu les données, vous pourrez choisir de marquer ces données comme lues pour qu'elles ne soient plus affichées comme "nouvelles".

Pour cela, il faut utiliser une requête en POST à l'URL : https://forms.kizeo.com/rest/v3/forms/{formId}/markasreadbyaction/{tag}.

Vous devrez cependant ajouter, dans le corps de la requête, les identifiants des données que vous souhaitez marquer comme "lues", de la façon suivante :

{
    "data_ids": ["dataId1", "dataId2", "dataId3", "dataId4"]
}

1.2. Recherche avancée dans les données d'un formulaire

Pour approfondir les recherches dans les données d'un formulaire, il existe une fonction de recherche avancée.

Pour utiliser cette dernière, vous devez envoyer une requête en POST à l'URL suivante : https://forms.kizeo.com/rest/v3/forms/{formId}/data/advanced.

Afin de définir les filtres que vous voulez utiliser pour rechercher précisément vos données, vous disposez des filtres au format suivant en JSON.

{
    "global_filters": "string", // Une chaîne de caractères à rechercher dans la donnée
    "format": "basic", // Optionnel, par défaut `basic`
    "filters": [
        {
            "type": "OR", // Afin de rajouter un groupe de conditions `Ou inclusif`
            "components": [
                // L'ensemble des conditions du groupe
                {
                    "field": "string", // Le champ sur lequel repose la recherche avancée
                    "operator": "string", // L'opérateur utilisé pour comparer la donnée à la valeur de référence
                    "type": "simple",
                    "val": "string" // Valeur de référence pour la recherche avancée
                }
                // ...
            ]
        }
    ],
    "order": [
        {
            "col": "string", // Donnée sur laquelle seront classés les résultats
            "type": "string" // Type de la donnée de classement
        }
    ]
}

• format : Vous pouvez utiliser le format basic (contient tous les détails) ou simple (plus simple mais moins exhaustif et ne contient pas les tableaux).
• operator : Les différents opérateurs sont : =, >, >=, <, <=, !=, like, notlike (attention, sensible à la casse).
• field : Correspond à la racine de la balise de chaque champ. Exemple : _update_time (date de mise-à-jour) et _user_id (id de l'utilisateur ayant saisi la donnée). Vous pouvez également rechercher sur des champs du formulaire définis par vous-même (client par exemple, ou bien numero_de_contrat).
• type : Les différents types sont : simple (on recherche sur un champ hors d'un tableau), global (on recherche dans l'ensemble de la donnée), AND et OR (permet de faire des conditions multiples dans l'attribut components comme présenté ci-dessus).
• order: Permet de choisir l'ordre de tri du résultat. Le type est soit ascpour un ordre croissant, soit desc pour un ordre décroissant.

1.3. Enregistrer une donnée sans enregistrer le formulaire complet

Vous avez aussi la possibilité d'envoyer des données sans avoir besoin d'enregistrer le formulaire, au cas où vous avez besoin d'ajouter d'autres données plus tard. On appelle cet envoi de donnée un envoi par "push".

Pour réaliser cette opération, il vous faut envoyer une requête en POST à l'URL suivante : https://forms.kizeo.com/rest/v3/forms/{formId}/push en remplaçant {formId} par l'identifiant du formulaire.

Il vous faudra aussi ajouter dans le corps de la requête les données à transmettre de la façon qui suit :

{
    "recipient_user_id": "integer",
    "fields": {
        "field_id": {
            "value": "string"
        }
    }
}

Pour utiliser l'option planning :

{
    "recipient_user_id": "integer",
    "planningStart": "AAAA-MM-JJ HH:MM",
    "planningEnd": "AAAA-MM-JJ HH:MM",
    "fields": {
        "field_id": {
            "value": "string"
        }
    }
}

2. Exemples de code en PHP

Si cURL n'est pas déjà préinstallé, voici un lien qui pourrait vous aider à l'installer.

2.1. L'exemple suivant montre comment lire les données non lues d'un formulaire

<?php

$formId;
// Initialisation de la requête
$curl = curl_init();

// Définition des entêtes et paramètres
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://forms.kizeo.com/rest/v3/forms/' . $formId . '/data/unread/' . $tag . '/100?includeupdated&format=basic',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: YOUR_TOKEN",
    "cache-control: no-cache",
    "content-type: application/json"
  ),
));

// Envoi de la requête et affichage de la réponse
$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Avec la fonction qui y est liée, pour noter les données comme "lues" :

<?php

$formId;
// Initialisation de la requête
$curl = curl_init();

// Définition des paramètres et entêtes de la requête
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://www.kizeoforms.com/rest/v3/forms/' . $formId . '/markasreadbyaction/" . $tag,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  // Définition de la donnée dans le corps de la requête
  CURLOPT_POSTFIELDS => "{\n  \"data_ids\": [\n    dataId1, dataId2\n  ]\n}",
  CURLOPT_HTTPHEADER => array(
    "Authorization: YOUR_TOKEN",
    "cache-control: no-cache",
    "content-type: application/json"
  ),
));

// Envoi de la requête et affichage de la réponse
$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

2.2. Voici un exemple permettant de faire une recherche avancée dans les données d'un formulaire

<?php

$formId;
// Initialisation de la requête
$curl = curl_init();

// Définition des paramètres et entêtes de la requête
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://forms.kizeo.com/rest/v3/forms/' . $formId . '/data/advanced",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  // Définition de la donnée dans le corps de la requête
  CURLOPT_POSTFIELDS => "{\n  \"global_filters\": \"\",\n  \"filters\": [\n    {\n      \"field\": \"field_name\",\n      \"operator\": \"comparison_operator\",\n      \"type\": \"simple\",\n      \"val\": \"compare_value\"\n    }\n  ],\n  \"order\": [\n    {\n      \"col\": \"order_data\",\n      \"type\": \"col_type\"\n    }\n  ]\n}",
  CURLOPT_HTTPHEADER => array(
    "Authorization: YOUR_TOKEN",
    "cache-control: no-cache",
    "content-type: application/json"
  ),
));

// Envoi de la requête et affichage de la réponse
$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

2.3. Voici un exemple permettant de transférer des données (Push)

<?php

$formId;
// Initialisation de la requête
$curl = curl_init();

// Définition des paramètres et entêtes de la requête
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://forms.kizeo.com/rest/v3/forms/' . $formId . '/data/push",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  // Définition de la donnée dans le corps de la requête
  CURLOPT_POSTFIELDS => "{\n  \"recipient_user_id\": \"integer\",\n  \"fields\": {\n    \"field_id\": {\n      \"value\": \"string\"\n    }\n  }\n}",
  CURLOPT_HTTPHEADER => array(
    "Authorization: YOUR_TOKEN",
    "cache-control: no-cache",
    "content-type: application/json"
  ),
));

// Envoi de la requête et affichage de la réponse
$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

3. Exemples de code en Java

3.1. L'exemple suivant montre comment lire les données non lues d'un formulaire

string formId;
// Initialisation de la requête
OkHttpClient client = new OkHttpClient();

// Définition des paramètres et des entêtes de la requête
Request request = new Request.Builder()
  .url("https://forms.kizeo.com/rest/v3/forms/" . formId . "/data/unread/" . tag . "/100?includeupdated&format=basic")
  .get()
  .addHeader("content-type", "application/json")
  .addHeader("Authorization", "YOUR_TOKEN")
  .addHeader("cache-control", "no-cache")
  .build();

// Envoi de la requête
Response response = client.newCall(request).execute();

Avec la fonction qui y est liée, pour noter les données comme "lues" :

string formId;
// Initialisation de la requête
OkHttpClient client = new OkHttpClient();

// Définition des données à modifier dans le corps de la requête
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"data_ids\": [\r\n    dataId1, dataId2\r\n  ]\r\n}");
// Définition des entêtes et des paramètres de la requête
Request request = new Request.Builder()
  .url("https://forms.kizeo.com/rest/v3/forms/" . formId . "/markasreadbyaction/" . tag)
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("Authorization", "YOUR_TOKEN")
  .addHeader("cache-control", "no-cache")
  .build();

// Envoi de la requête
Response response = client.newCall(request).execute();

3.2. Voici un exemple permettant de faire une recherche avancée dans les données d'un formulaire

string formId;
// Initialisation de la requête
OkHttpClient client = new OkHttpClient();

// Ajout des filtres à appliquer dans le corps de la requête
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"global_filters\": \"\",\r\n  \"filters\": [\r\n    {\r\n      \"field\": \"field_name\",\r\n      \"operator\": \"comparison_operator\",\r\n      \"type\": \"simple\",\r\n      \"val\": \"compare_value\"\r\n    }\r\n  ],\r\n  \"order\": [\r\n    {\r\n      \"col\": \"order_data\", \r\n      \"type\": \"col_type\"\r\n    }\r\n  ]\r\n}");
// Définition des entêtes et des paramètres de la requête
Request request = new Request.Builder()
  .url("https://forms.kizeo.com/rest/v3/forms/" . formId . "/data/advanced")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("Authorization", "YOUR_TOKEN")
  .addHeader("cache-control", "no-cache")
  .build();

// Envoi de la requête
Response response = client.newCall(request).execute();

3.3. Voici un exemple permettant d'enregistrer des données sans enregistrer le formulaire

string formId;
// Initialisation de la requête
OkHttpClient client = new OkHttpClient();

// Ajout des filtres à appliquer dans le corps de la requête
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"recipient_user_id\": \"integer\",\r\n  \"fields\": {\r\n    \"field_id\": {\r\n      \"value\": \"string\"\r\n    }\r\n  }\r\n}");
// Définition des entêtes et des paramètres de la requête
Request request = new Request.Builder()
  .url("https://forms.kizeo.com/rest/v3/forms/" . formId . "/push")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("Authorization", "YOUR_TOKEN")
  .addHeader("cache-control", "no-cache")
  .build();

// Envoi de la requête
Response response = client.newCall(request).execute();

4. Exemples de code en Javascript

4.1. L'exemple suivant montre comment lire les données non lues d'un formulaire

var formId;
// Initialisation de la requête et définition des entêtes
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://forms.kizeo.com/rest/v3/forms/" . formId . "/data/unread/" . tag . "/100?includeupdated&format=basic",
  "method": "GET",
  "headers": {
    "content-type": "application/json",
    "Authorization": "YOUR_TOKEN",
    "cache-control": "no-cache",
  }
}

// Envoi de la requête et affichage de la réponse
$.ajax(settings).done(function (response) {
  console.log(response);
});

Avec la fonction qui y est liée, pour noter les données comme "lues" :

var formId;
// Initialisation de la requête et définition des entêtes
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://forms.kizeo.com/rest/v3/forms/" . formId . "/markasreadbyaction/" . tag,
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "Authorization": "YOUR_TOKEN",
    "cache-control": "no-cache"
  },
  // Définition des données à modifier dans le corps de la requête
  "processData": false,
  "data": "{\r\n  \"data_ids\": [\r\n    dataId1, dataId2\r\n  ]\r\n}"
}

// Envoi de la requête et affichage de la réponse
$.ajax(settings).done(function (response) {
  console.log(response);
});

4.2. Voici un exemple permettant de faire une recherche avancée dans les données d'un formulaire

var formId;
// Initialisation de la requête et définition des entêtes
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://forms.kizeo.com/rest/v3/forms/" . formId . "/data/advanced",
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "Authorization": "YOUR_TOKEN",
    "cache-control": "no-cache",
  },
  // Ajout des filtres à appliquer dans le corps de la requête
  "processData": false,
  "data": "{\r\n  \"global_filters\": \"\",\r\n  \"filters\": [\r\n    {\r\n      \"field\": \"field_name\",\r\n      \"operator\": \"comparison_operator\",\r\n      \"type\": \"simple\",\r\n      \"val\": \"compare_value\"\r\n    }\r\n  ],\r\n  \"order\": [\r\n    {\r\n      \"col\": \"order_data\",\r\n      \"type\": \"col_type\"\r\n    }\r\n  ]\r\n}"
}

// Envoi de la requête et affichage de la réponse
$.ajax(settings).done(function (response) {
  console.log(response);
});

4.3. Voici un exemple permettant d'enregistrer des données sans enregistrer le formulaire

var formId;
// Initialisation de la requête et définition des entêtes
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://forms.kizeo.com/rest/v3/forms/" . formId . "/push",
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "Authorization": "YOUR_TOKEN",
    "cache-control": "no-cache",
  },
  // Ajout des filtres à appliquer dans le corps de la requête
  "processData": false,
  "data": "{\r\n  \"recipient_user_id\": \"integer\",\r\n  \"fields\": {\r\n    \"field_id\": {\r\n      \"value\": \"string\"\r\n    }\r\n  }\r\n}"
}

// Envoi de la requête et affichage de la réponse
$.ajax(settings).done(function (response) {
  console.log(response);
});