Webservices liés aux formulaires
Les APIs de participations aux formulaires peuvent être utilisés pour faire le lien entre ACTITO et des formulaires qui n'ont pas forcément été définis par ACTITO.
Ceci peut être utile d'une part pour pouvoir collecter des données qui proviennent d'un partenaire extérieur et de les soumettre vers ACTITO à des fins d'enrichissement, tout en conservant la source de l'information d'une façon qui s'accorde avec la réglementation RGPD.
D'autre part, cela peut être typiquement utilisé quand la conception du formulaire est gérée par une autre plateforme. Les réponses données par les profils peuvent être ainsi directement poussées dans un formulaire technique ACTITO via l'utilisation des APIs de formulaires.
La conception en tant que telle d'un formulaire ACTITO n'est pas possible via l'utilisation des APIs. Ceci doit être fait via l'interface ACTITO. Pour plus d'informations à ce sujet, vous pouvez vous référez au chapitre consacré aux formulaires.
En revanche, les APIs liés aux formulaires vous permettent :
d'obtenir la structure d'un formulaire
-
d'obtenir les détails de participation d'un profil
-
de créer et de mettre à jour des participations à un formulaire, en appliquant les règles d'enrichissement
Préparer un formulaire compatible avec l'utilisation d'API
L'utilisation des APIs liés aux formulaires implique que votre formulaire devra respecter certaines contraintes pour garantir que l'utilisation des webservices se fasse avec succès. Il convient de les garder à l'esprit lors de la création de votre formulaire dans l'interface ACTITO.
Noms d'affichage et traductions
Lors de la création de votre formulaire dans l'interface d'ACTITO, si vous optez pour des questions à réponses multiples, vous avez la possibilité de définir des valeurs d'affichages différentes des valeurs techniques. Vous pouvez également traduire ces valeurs en fonction du langage.
Néanmoins, cette notion n'est pas prise en compte dans les APIs liés aux formulaires. Seules les valeurs techniques, qui restent identiques quel que soit le langage, peuvent être obtenues ou poussées via un appel.
Les questions peuvent par contre être traduites, car elles pourront être associées à des noms techniques.
Définition des noms techniques du formulaire
Les APIs liés aux formulaires font usage de noms techniques pour soumettre les données. Il est important de donner des noms clairs et précis à vos questions, à la fois pour des questions de facilité d'usage et pour éviter tout risque d'erreur dans la paramétrisation des APIs.
Le texte court que vous pouvez associer à chaque question lors de la création de votre formulaire est utilisé pour le reporting mais il ne s'agit pas du nom technique. Ceux-ci doivent être ajoutés ultérieurement. Pour cela, rendez-vous dans la liste des formulaires existant dans l'onglet "Activés". Cliquez sur le bouton "Plus" puis, dans le menu déroulant, cliquez sur "Définir les noms techniques".
Vous pouvez alors définir des noms techniques pertinents à la fois pour l'enquête générale et pour chaque question individuelle.
Astuce
Si vous avez inclus des "Question Prédéfinies", celles-ci auront déjà un nom technique prérempli.
Règles d'enrichissement de la base de données
Les formulaires permettent à vos contacts de modifier directement leurs informations de profils. Lors de la création d'un formulaire destiné à être utilisé avec un API ACTITO, il est important de définir de bonnes règles d'enregistrement de profils.
En effet, une des règles d'enrichissement disponible consiste à enrichir la base de données si les réponses d'une page en particulier sont enregistrées. Or la notion de page n'est pas prise en compte dans le cas d'une utilisation des APIs.
De ce fait, il est nécessaire de ne pas utiliser cette règle mais de plutôt privilégier une condition d'enrichissement quand "la participation au formulaire est terminée".
Pour des informations plus complètes sur les règles d'enrichissement, nous vous invitons à vous référer à la page "Enrichir une base de données".
Les APIs de formulaires
Obtenir la structure d'un formulaire
Étant donné que la conception de votre formulaire dans ACTITO est totalement personnalisable, à la fois pour ce qui est de ses questions et de leur agencement, il est nécessaire de savoir comment la structure de votre formulaire se traduit dans les APIs.
Pour cela, vous avez la possibilité d'utiliser la méthode GET/entity{e}/form/{f}
Les paramètres à renseigner pour cette opération sont :
-
l'entité à laquelle formulaire appartient
-
l'identifiant du formulaire en question : il s'agit soit du nom technique que vous avez défini, soit de son id, qui est un numéro généré automatiquement à sa conception. Dans les deux cas, ils sont accessibles dans l'interface ACTITO via le bouton "Définir les noms techniques", comme expliqué ci-dessus.
Exemple de requête et de réponse pour cette opération: (Téléchargez cet exemple)
Curl callcurl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/form/72"
Response body
{ "id": 72,
"technicalName": "DemoDocForm",
"status": "ACTIVE",
"name": {
"localized": [],
"default": "Demo Doc"
}, "creationMoment": "20190214154537",
"updateMoment": "20190320104310",
"activeMoment": "20190220092641",
"closeMoment": null,
"participantParameters": {
"presence": "ALLOWED",
"table": "DemoDoc"
}, "questions": [
{ "id": 281,
"technicalName": "source",
"type": "String",
"valueType": "SINGLE",
"possibleValues": [],
"text": {
"localized": [],
"default": "source"
}, "other": {
"allowed": false,
"texts": []
}, "required": false
}, { "id": 282,
"technicalName": "language",
"type": "Language",
"valueType": "SINGLE",
"possibleValues": [],
"text": {
"localized": [],
"default": "language"
}, "other": {
"allowed": false,
"texts": []
}, "required": false
}, { "id": 296,
"technicalName": "where",
"type": "Country",
"valueType": "SINGLE",
"possibleValues": [
{ "value": "BE",
"text": {
"localized": [
{ "language": "FR",
"text": "Où habitez vous ?"
}, { "language": "EN",
"text": "Where are you from ?"
} ], "default": null
} }, { "value": "FR",
"text": {
"localized": [
{ "language": "FR",
"text": "Où habitez vous ?"
}, { "language": "EN",
"text": "Where are you from ?"
} ], "default": null
} }, { "value": "GB",
"text": {
"localized": [
{ "language": "FR",
"text": "Où habitez vous ?"
}, { "language": "EN",
"text": "Where are you from ?"
} ], "default": null
} } ], "text": {
"localized": [
{ "language": "FR",
"text": "Où habitez vous ?"
}, { "language": "EN",
"text": "Where are you from ?"
} ], "default": null
}, "other": {
"allowed": true,
"texts": [
{ "language": "FR",
"text": "Autre (spécifiez)"
}, { "language": "EN",
"text": "Other (specify)"
} ] }, "required": false
}, { "id": 297,
"technicalName": "subscriptions",
"type": "String",
"valueType": "MULTI",
"possibleValues": [
{ "value": "Info",
"text": {
"localized": [
{ "language": "FR",
"text": "Quelles communications souhaitez vous recevoir ?"
}, { "language": "EN",
"text": "Which communications do you wish to subscribe to
?"
} ], "default": "Quelles communications souhaitez vous recevoir ?"
} }, { "value": "Newsletter",
"text": {
"localized": [
{ "language": "FR",
"text": "Quelles communications souhaitez vous recevoir ?"
}, { "language": "EN",
"text": "Which communications do you wish to subscribe to
?"
} ], "default": "Quelles communications souhaitez vous recevoir ?"
} }, { "value": "Offer",
"text": {
"localized": [
{ "language": "FR",
"text": "Quelles communications souhaitez vous recevoir ?"
}, { "language": "EN",
"text": "Which communications do you wish to subscribe to
?"
} ], "default": "Quelles communications souhaitez vous recevoir ?"
} } ], "text": {
"localized": [
{ "language": "FR",
"text": "Quelles communications souhaitez vous recevoir ?"
}, { "language": "EN",
"text": "Which communications do you wish to subscribe to
?"
} ], "default": "Quelles communications souhaitez vous recevoir ?"
}, "other": {
"allowed": false,
"texts": []
}, "required": false
}, { "id": 304,
"technicalName": "AddressEmail",
"type": "EmailAddress",
"valueType": "SINGLE",
"possibleValues": [],
"text": {
"localized": [
{ "language": "FR",
"text": "Tapez votre adresse e-mail :"
}, { "language": "EN",
"text": "Type your email address:"
} ], "default": null
}, "other": {
"allowed": false,
"texts": []
}, "required": false
}, { "id": 305,
"technicalName": "emailAddress",
"type": "EmailAddress",
"valueType": "SINGLE",
"possibleValues": [],
"text": {
"localized": [
{ "language": "EN",
"text": "E-mail address"
}, { "language": "FR",
"text": "Adresse e-mail"
}, { "language": "NL",
"text": "E-mailadres"
} ], "default": "E-mail address"
}, "other": {
"allowed": false,
"texts": []
}, "required": null
} ]}La réponse obtenue contiendra les éléments suivants :
Paramètres globaux
-
"id" : identifiant technique du formulaire, généré automatiquement
-
"technicalName" : nom technique du formulaire, que vous avez pu définir comme expliqué précédemment
-
"status" : indique si le formulaire est encore en cours de conception (IN_DEFINITION), actif (ACTIVE) ou si les participations sont clôturées (STOPPED)
-
"participantParameters" : indique si le formulaire est lié à une table de profil
-
"presence" : "FORBIDDEN" si le formulaire est public et non lié à une base de données, "ALLOWED" si la participation est liée à une base de profils, "UNIQUE" si une seule participation est possible par profil
-
"table" : le nom de la base de données de profils liée (si applicable)
-
Paramètres des questions
-
"id" : identifiant technique de la question, généré automatiquement. Il pourra être utilisé pour enregistrer des participations via API
-
"technicalName" : nom technique de la question, que vous avez pu définir comme expliqué précédemment. Il pourra être utilisé pour enregistrer des participations via API
-
"type" : le type (format) de la réponse attendue. Téléchargez un fichier reprenant les différents types possibles pour les réponses dans les formulaires : TypesDeValeursFormulaires.docx
-
"valueType" : indique si une seule réponse est possible (SINGLE) ou si plusieurs réponses sont acceptées (MULTI)
-
"possibleValues" : il s'agit d'un tableau de valeurs reprenant les valeurs techniques de chaque réponse possible proposée (dans le cas où des réponses sont prédéfinies, comme des cases à cocher)
-
"localized" : il s'agit d'un tableau de valeurs reprenant les traductions de la question. Ce paramètre doit être répété pour chaque valeur de réponse possible
-
-
"required" : indique si la question est obligatoire (true) ou pas (false)
Obtenir des informations sur les participations
Vous avez la possibilité d'obtenir plusieurs types d'information à propos des participations passées à un formulaire :
Obtenir le détail des participations d'un profil
Pour cela, vous pouvez utiliser l'opération GET/entity/{e}/form{f}/profile/{p}
Vous devrez utiliser comme paramètres l'entité, l'identifiant du formulaire ainsi que l'identifiant du profil dont vous souhaitez obtenir les interactions.
Vous pouvez ensuite définir des filtres :
-
sur la date de création ou de mise à jour
-
inclure uniquement les participations complètes à un formulaire ou les participations incomplètes. Pour obtenir toutes les participations (complètes et incomplètes), il convient de ne pas inclure ce paramètre
-
sur le nombre de participations à afficher (la valeur maximum et par défaut est de 200)
Exemple de requête et de réponse pour cette opération : (Téléchargez cet exemple)
Curl callcurl -X GET --header "Accept: application/json" -d "{}" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/form/demodocform/profile/1147690"
Response body
{ "FormParticipations": [
{ "interactionId": 2482,
"FormId": {
"name": "DemoDocForm",
"id": 72
}, "AnswerForms": {
"AnswerGroup": [
{ "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": [
{ "Question": {
"name": "language",
"questionId": 282
}, "Values": [
"FR"
], "OtherValue": null
} ] }, { "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": [
{ "Question": {
"name": "subscriptions",
"questionId": 297
}, "Values": [
"Newsletter"
], "OtherValue": null
} ] }, { "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": []
} ], "Profile": "1147690",
"ParticipationMoment": "2019-03-20 11:28:48",
"Test": false,
"Completed": true
} }, { "interactionId": 2485,
"FormId": {
"name": "DemoDocForm",
"id": 72
}, "AnswerForms": {
"AnswerGroup": [
{ "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": [
{ "Question": {
"name": "language",
"questionId": 282
}, "Values": [
"FR"
], "OtherValue": null
} ] }, { "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": [
{ "Question": {
"name": "subscriptions",
"questionId": 297
}, "Values": [
"Newsletter",
"Offer"
], "OtherValue": null
} ] }, { "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": []
} ], "Profile": "1147690",
"ParticipationMoment": "2019-03-20 11:29:46",
"Test": false,
"Completed": true
} }, { "interactionId": 2478,
"FormId": {
"name": "DemoDocForm",
"id": 72
}, "AnswerForms": {
"AnswerGroup": [
{ "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": [
{ "Question": {
"name": "language",
"questionId": 282
}, "Values": [
"FR"
], "OtherValue": null
} ] }, { "QuestionGroupId": null,
"Answers": [
{ "Question": {
"name": "where",
"questionId": 296
}, "Values": [],
"OtherValue": "USA"
} ] }, { "QuestionGroupId": null,
"Answers": [
{ "Question": {
"name": "subscriptions",
"questionId": 297
}, "Values": [
"Info"
], "OtherValue": null
} ] }, { "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": []
} ], "Profile": "1147690",
"ParticipationMoment": "2019-03-20 11:27:34",
"Test": false,
"Completed": true
} }, { "interactionId": 2487,
"FormId": {
"name": "DemoDocForm",
"id": 72
}, "AnswerForms": {
"AnswerGroup": [
{ "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": [
{ "Question": {
"name": "language",
"questionId": 282
}, "Values": [
"FR"
], "OtherValue": null
} ] }, { "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": []
}, { "QuestionGroupId": null,
"Answers": []
} ], "Profile": "1147690",
"ParticipationMoment": "2019-03-20 11:31:12",
"Test": false,
"Completed": true
} } ]}Obtenir le détail d'une participation
Il est possible d'obtenir le détail d'une participation en particulier via l'opération GET/entity/{e}/form{f}/interaction{i}
Pour cela, il faut indiquer comme paramètres l'entité, l'identifiant du formulaire, ainsi que l'identifiant technique de la participation. Cette identifiant de la participation peut être obtenu de différentes manières :
-
il est donné comme réponse lorsque vous soumettez une participation via API
-
il est indiqué dans la liste de participations obtenues via l'opération précédente
La réponse obtenue pour cet appel sera similaire à celle de l'opération précédente, à ceci près qu'elle ne contiendra les détails que d'une seule participation.
Créer une participation à un formulaire
Il est possible de soumettre directement une participation à un formulaire via API, notamment si le formulaire rempli par le contact a été réalisé sur un autre système mais que vous souhaitez que les données récoltées soient renvoyées vers ACTITO.
Il convient alors d'utiliser l'opération POST/entity/{e}/form{f}/interaction
Les paramètres pour cette opération seront :
-
l'entité sur laquelle le formulaire est enregistré
-
l'identifiant du formulaire (nom technique ou identifiant auto-généré)
-
les réponses aux questions du formulaire, sous forme de code JSON
-
les paramètres de collecte de données ("source", way" et "date") qui vous permettent de préciser comment ces informations ont été obtenues. Ces informations ne sont pas obligatoires mais constituent une bonne pratique dans le cadre du RGPD.
Le code qui constitue le corps de la requête devra être structuré de la façon suivante :
-
Le paramètre "AnswerGroup" est composé d'une liste d'attributs "Answers" qui correspondent aux paires de questions-valeurs présentes dans le formulaire.
-
"Question" est composé d'un attribut "name" qui est le nom technique de la question.
-
"Values" contient la (les) valeur(s) de la (des) réponse(s) à la question.
-
-
"Completed" doit être indiqué comme "true" si le questionnaire a été complété dans son entièreté. Il s'agit d'une question technique.
-
"Test" doit être indiqué comme "false" à moins qu'il s'agisse d'une participation de test.
-
"Profile" correspond à l'identifiant technique du profil (profileId). Il doit être précisé pour lier la participation à un profil dans les cas où le formulaire ne possède pas de question basée sur un attribut unique ni de règle d'enrichissement qui permettrait de lier la participation au profil.
Exemple de requête incluant du code JSON et de réponse : (Téléchargez cet exemple)
Curl callcurl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"AnswerGroup\": [{
\"Answers\": [{
\"Question\": {
\"name\": \"source\"
}, \"Values\": [
\"Register\"
] }] }, { \"Answers\": [{
\"Question\": {
\"name\": \"language\"
}, \"Values\": [
\"EN\" ] }] }, { \"Answers\": [{
\"Question\": {
\"name\": \"where\"
}, \"Values\": [
\"FR\" ] }] }, { \"Answers\": [{
\"Question\": {
\"name\": \"AddressEmail\"
}, \"Values\": [
\"jane.doe@actito.be\"
] }] }, { \"Answers\": [{
\"Question\": {
\"name\": \"subscriptions\"
}, \"Values\": [
\"Offer\", \"Info\" ] }] } ], \"ParticipationMoment\": \"2019-02-26 16:04:54\",
\"Completed\": true,
\"Profile\": \"147471\",
\"Test\": false
}" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/form/demodocform/interaction?source=API&way=testprofile&date=20%2F03%2F2019"
Response body
{ "interactionId": 2516
}La réponse à la requête contiendra simplement l'identifiant technique auto-généré correspondant à l'interaction (c'est à dire à la participation).
La participation sera dès lors enregistrée. Elle sera accessible via l'interface ACTITO comme toute participation standard à un formulaire et les règles d'enrichissement de base de données seront appliquées.