Outils de questionnaire et QML — référence des outils MCP
Les outils de questionnaire gèrent le cycle de vie du QML : sauvegarde de nouvelles versions, validation par l’analyse formelle Z3, publication d’une version sur une campagne, déplacement entre projets et dépublication. Ce cycle de vie impose des contraintes — par exemple, la dépublication est bloquée si des campagnes actives font référence au questionnaire.
Mode de stockage du QML
Section intitulée « Mode de stockage du QML »Le QML d’un questionnaire est stocké dans la base de données d’Askalot sous la forme d’une chaîne de versions en ajout seul. Chaque sauvegarde ajoute une nouvelle version et y déplace la tête du questionnaire ; les versions antérieures ne sont jamais écrasées ni supprimées.
qml_name est l’adresse stable du questionnaire, de la forme projects/{project_id}/questionnaires/{questionnaire_id}.qml. Elle ressemble à un chemin et se lit comme tel, mais elle identifie un questionnaire : il n’y a ni répertoire à parcourir ni fichier à préparer. list_qml_files renvoie les adresses existantes.
Trois règles en découlent, et elles expliquent l’essentiel du comportement décrit ci-dessous :
- Une sauvegarde nomme la version à partir de laquelle elle a été écrite. Vous composez une sauvegarde à partir d’un contenu lu un instant plus tôt, et quelqu’un d’autre a pu enregistrer entre-temps.
save_qml_fileetfinalize_uploadprennent doncbase_version_id, leversion_idde la réponse de lecture ou de sauvegarde dont provient votre contenu. Si la tête est toujours cette version, votre contenu devient la nouvelle tête. Si elle a bougé et que les deux modifications portent sur des lignes différentes, la fusion des deux devient la tête. Si les deux ont modifié les mêmes lignes, rien n’est écrit et la réponse estoverlap. - La sauvegarde n’est jamais bloquée par la validation. Une ébauche, un bloc collé ou une logique inachevée doivent pouvoir être stockés : une sauvegarde consigne donc le verdict de la validation formelle sur la version enregistrée et renvoie les éventuels problèmes sous forme de
warnings. Hormis une adresse qui ne correspond à aucun questionnaire dans lequel vous pouvez écrire et un appel que le schéma d’entrée rejette, une sauvegarde n’est refusée que dans les cas suivants : une base qui n’est pas une version du questionnaire (base_version_unknown), unoverlap, une tête qui a bougé avant chaque tentative (head_kept_moving), un questionnaire déplacé vers un autre projet pendant la sauvegarde (questionnaire_moved), une organisation scellée (org_sealed) et un contenu transmis directement dans l’appel de plus de 32 Ko. - La publication, elle, peut refuser.
publish_qml_fileépingle une version sur une campagne, c’est-à-dire le moment où l’instrument parvient à un répondant : c’est donc le seul point de contrôle qui rejette une conception incohérente. La version épinglée est ensuite immuable pendant toute la durée de vie de cette campagne.
list_questionnaires
Section intitulée « list_questionnaires »Liste tous les questionnaires, avec un filtre facultatif par nom.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
name |
string |
Non | — | Filtre par sous-chaîne, insensible à la casse |
limit |
integer |
Non | 100 |
Nombre maximal de résultats renvoyés |
Renvoie : { items: [...], count, limit }
get_questionnaire
Section intitulée « get_questionnaire »Récupère un questionnaire par son identifiant.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
questionnaire_id |
string |
Oui | — | UUID du questionnaire |
Renvoie : l’objet questionnaire ou { error }.
create_questionnaire
Section intitulée « create_questionnaire »Crée un nouveau questionnaire à partir de contenu QML ou d’un modèle de la bibliothèque. Le questionnaire et la version 1 de son QML sont créés ensemble : un questionnaire n’existe donc jamais sans contenu.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
name |
string |
Avec content |
le nom du modèle | Nom affiché |
content |
string |
content ou template |
— | Le YAML QML, enregistré comme version 1 |
template |
string |
content ou template |
— | Un identifiant (slug) de modèle issu de list_questionnaire_templates ; la version 1 est le QML de ce modèle dans la langue language, octet pour octet |
project_id |
string |
Oui | — | Identifiant du projet parent |
description |
string |
Non | — | Description en texte libre |
language |
string |
Non | "en" ; avec template, la vôtre |
Code de langue. Avec template, la langue dans laquelle copier le modèle : l’une des languages de la bibliothèque. S’il est omis, votre propre langue (votre réglage, sinon la langue par défaut de votre organisation) si la bibliothèque la propose, sinon en |
estimated_duration |
integer |
Non | — | Durée de remplissage prévue, en minutes |
Indiquez content ou template, jamais les deux : fournir les deux, ou aucun des deux, est refusé, et rien n’est écrit. Un identifiant template inconnu reçoit une réponse « introuvable », et une language que la bibliothèque ne propose pas est refusée avec la liste des langues proposées.
La copie d’un modèle est écrite dans la langue dans laquelle il a été lu, et chacune des autres langues proposées par la bibliothèque l’accompagne sous forme de traduction de la version 1 : ces langues peuvent ainsi être proposées aux répondants sans étape de traduction.
Renvoie : l’objet questionnaire créé, avec le version_id et le version_number de la version 1. Ce version_id est le base_version_id à utiliser pour une première sauvegarde de ce contenu.
La création n’est pas conditionnée à la validation formelle : content peut être structurellement défectueux. À partir de content, le verdict est consigné avec la version 1, sans être imposé ; c’est la publication sur une campagne qui exige la cohérence. À partir d’un template, la validation s’exécute en arrière-plan quelques secondes après la création, comme après une sauvegarde : d’ici là, logic_validated vaut false.
list_questionnaire_templates
Section intitulée « list_questionnaire_templates »Liste la bibliothèque de modèles de questionnaires : des questionnaires prêts à l’emploi (évaluations de cours, retours clients, inscriptions à un événement, accueil des patients, etc.), regroupés par catégories. Transmettez un identifiant à create_questionnaire comme template.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
language |
string |
Non | la vôtre | Langue de la bibliothèque dans laquelle lister les modèles. S’il est omis, votre propre langue (votre réglage, sinon la langue par défaut de votre organisation) si la bibliothèque la propose, sinon en. Une langue que la bibliothèque ne propose pas est refusée avec la liste des langues proposées |
category |
string |
Non | — | Identifiant de catégorie ; une catégorie inconnue est refusée avec la liste des catégories |
query |
string |
Non | — | Mots qui doivent tous figurer dans le nom ou la description d’un modèle, sans tenir compte de la casse |
limit |
integer |
Non | 50 |
Taille de page, de 1 à 100 |
cursor |
string |
Non | — | Le next_cursor de la page précédente |
Renvoie : { data: [{ slug, name, category, subcategory, description }], categories: [{ slug, name }], language, language_fallback, languages, total, next_cursor, has_more }. Les noms, descriptions et catégories sont dans la langue language ; languages liste toutes les langues proposées par la bibliothèque, en en premier. language_fallback vaut true lorsqu’aucune language n’a été indiquée et que la bibliothèque ne propose pas encore la vôtre : la réponse est alors en anglais, et il faut le signaler à l’utilisateur. total compte tous les modèles correspondants ; suivez next_cursor tant que has_more est vrai. Aucun corps QML n’est listé : créez le questionnaire à partir d’un identifiant, puis lisez-le avec get_qml_content.
delete_questionnaire
Section intitulée « delete_questionnaire »Supprime logiquement un questionnaire.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
questionnaire_id |
string |
Oui | — | UUID du questionnaire |
Renvoie : { success: true, questionnaire_id } ou une erreur.
La suppression logique insère une ligne de sauvegarde ; restore_questionnaire (ci-dessous) peut rétablir le questionnaire pendant un court délai.
rename_questionnaire
Section intitulée « rename_questionnaire »Renomme un questionnaire. Il s’agit d’une simple mise à jour des métadonnées : l’adresse du questionnaire et sa chaîne de versions QML ne changent pas, et les campagnes qui y font référence continuent donc de fonctionner.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
questionnaire_id |
string |
Oui | — | UUID du questionnaire |
name |
string |
Oui | — | Nouveau nom affiché (255 octets au maximum) |
Renvoie : l’objet questionnaire mis à jour.
restore_questionnaire
Section intitulée « restore_questionnaire »Restaure un questionnaire récemment supprimé logiquement et rétablit ses références. La suppression n’a jamais touché à sa chaîne de versions QML : le questionnaire restauré revient donc exactement à la version qu’il avait.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
questionnaire_id |
string |
Oui | — | UUID du questionnaire |
Renvoie : l’objet questionnaire restauré, ou une erreur si le délai de restauration est écoulé.
list_qml_files
Section intitulée « list_qml_files »Liste les questionnaires QML de l’organisation. Aucun paramètre n’est requis. Le qml_name de chaque entrée peut être transmis à n’importe quel autre outil QML.
Renvoie :
{ "items": [ { "name": "3f9c2b10-....qml", "qml_name": "projects/abc123/questionnaires/3f9c2b10-....qml", "tier": "project", "project_id": "abc123" } ], "count": 1}inspect_qml_file
Section intitulée « inspect_qml_file »Obtient un résumé rapide de la version actuelle d’un questionnaire — nombre d’items et métadonnées, sans le contenu complet.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
qml_name |
string |
Oui | — | Adresse du questionnaire issue de list_qml_files |
Renvoie : { success, qml_name, items_count, metadata }
preview_qml_item
Section intitulée « preview_qml_item »Affiche un item de la version actuelle d’un questionnaire tel qu’un répondant le voit. Un hôte qui affiche les MCP Apps (comme Claude) ouvre un panneau en lecture seule avec les vrais contrôles de l’item ; tout autre hôte reçoit le même item sous forme de texte JSON.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
qml_name |
string |
Oui | — | Adresse du questionnaire issue de list_qml_files |
item_id |
string |
Oui | — | L’id de l’item |
Renvoie : les champs affichés de l’item (id, kind, title, input, ainsi que questions, rows ou columns lorsque l’item en possède), le balisage éventuel de son texte étant assaini. Un item ou une adresse inconnus produisent une erreur d’outil.
get_qml_content
Section intitulée « get_qml_content »Récupère le YAML brut de la version actuelle d’un questionnaire.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
qml_name |
string |
Oui | — | Adresse du questionnaire |
Renvoie : { success, qml_name, content, size_bytes, version_id, version_number } pour un contenu de 32 Ko au plus. version_id désigne la version que constitue content ; transmettez-le comme base_version_id lorsque vous enregistrez un contenu écrit à partir de cette réponse.
Au-delà de 32 Ko, le contenu n’est pas inclus dans la réponse, qui prend alors la forme { success, qml_name, download_url, size_bytes, version_id, version_number, note }, où download_url est un lien de courte durée (réutilisable jusqu’à son expiration) que vous récupérez directement en HTTPS (sans autre authentification). Le lien sert version_id, même si une sauvegarde a déplacé la tête depuis votre demande : ses octets correspondent donc bien à la version que vous indiquez comme base_version_id lors de la sauvegarde. Rappelez get_qml_content si le lien a expiré.
save_qml_file
Section intitulée « save_qml_file »Enregistre du contenu QML dans un questionnaire existant, écrit à partir d’une version que vous nommez. La sauvegarde n’est jamais bloquée par un YAML défectueux ou des violations du schéma : un brouillon en cours, pas encore valide, est tout de même enregistré, et les problèmes sont renvoyés dans une liste warnings au lieu de faire rejeter l’écriture.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
qml_name |
string |
Oui | — | Adresse d’un questionnaire existant |
content |
string |
Oui | — | Contenu YAML QML, jusqu’à 32 Ko |
base_version_id |
string |
Oui | — | La version à partir de laquelle le contenu a été écrit : le version_id de votre réponse la plus récente de get_qml_content, de create_questionnaire ou de sauvegarde pour ce questionnaire |
project_id |
string |
Non | — | S’il est indiqué, il doit correspondre au projet du questionnaire ; une discordance est refusée plutôt qu’ignorée |
Lisez d’abord, puis enregistrez. Appelez get_qml_content, appliquez votre modification au contenu renvoyé, et enregistrez avec son version_id comme base_version_id. Après une sauvegarde, la sauvegarde suivante nomme le version_id que celui-ci a renvoyé, jamais un plus ancien.
Renvoie : { success, qml_name, questionnaire_id, version_id, version_number, created, merged, content_changed, bytes_written, logic_validated, content?, content_note?, warnings? }.
| Ce qui s’est passé | Dans la réponse |
|---|---|
| La base était encore la tête | created: true, merged: false. Votre contenu devient la nouvelle tête |
| Quelqu’un a enregistré entre-temps, sur d’autres lignes | created: true, merged: true, content_changed: true. La tête contient les deux modifications, et content la transmet : elle remplace votre copie. Les lignes que vous n’avez pas écrites sont celles de l’autre auteur |
| Votre contenu est déjà la tête | created: false. Rien n’est écrit |
| Votre contenu est identique à sa base et la tête a bougé | created: false, content_changed: true, avec le content de la tête |
content n’est inclus que lorsque le contenu enregistré fait moins de 32 Ko ; sinon, content_note indique d’appeler get_qml_content. warnings est absent lors d’une sauvegarde sans problème ; c’est une liste de problèmes d’analyse ou de schéma pour un brouillon enregistré mais imparfait.
Une sauvegarde qui n’écrit rien répond { success: false, error, detail } :
error |
Signification | Que faire |
|---|---|---|
overlap |
Quelqu’un a enregistré entre-temps et modifié les mêmes lignes. Porte head_version_id, head_version_number, conflict_count |
Appelez get_qml_content, appliquez votre modification à ce qu’il renvoie, et enregistrez avec son version_id. Ne renvoyez pas le même contenu sous l’identifiant plus récent : cela écraserait l’autre sauvegarde |
base_version_unknown |
base_version_id est vide, n’est pas un identifiant de version, ou n’est pas une version de ce questionnaire |
Appelez get_qml_content et enregistrez avec le version_id qu’il renvoie |
head_kept_moving |
Le questionnaire a été enregistré de nouveau avant chacune des trois tentatives | Relisez et réessayez |
org_sealed |
L’organisation est scellée | Aucune écriture n’est possible |
questionnaire_moved |
Le questionnaire a été déplacé vers un autre projet pendant la sauvegarde | Appelez list_qml_files pour obtenir son adresse actuelle, lisez-le avec get_qml_content et enregistrez de nouveau |
La validation formelle s’exécute en arrière-plan, quelques secondes après la sauvegarde, sur la version qui est alors la tête (la vôtre, ou la fusion), et son verdict est consigné sur cette version : la cohérence d’une version reste ainsi vérifiable plus tard, même après d’autres modifications. D’ici là, logic_validated vaut null dans la réponse de sauvegarde et logic_validation_note le signale, et get_questionnaire indique logic_validated: false ; il renvoie le verdict dès qu’il est disponible, et validate_qml_file le fournit à la demande. Une sauvegarde qui introduit une régression fait passer le questionnaire à l’état non validé sans bloquer l’écriture ; sa publication sur une campagne est refusée jusqu’à sa correction.
Une adresse qui ne correspond à aucun questionnaire est refusée — appelez d’abord create_questionnaire.
Un contenu de plus de 32 Ko est refusé avec {"error": "content_too_large_for_inline_save"}, et rien n’est écrit. Utilisez request_upload_url / finalize_upload (ci-dessous) plutôt que de tronquer le contenu.
request_upload_url / finalize_upload
Section intitulée « request_upload_url / finalize_upload »Une procédure en deux temps pour enregistrer un contenu QML trop volumineux pour la limite de 32 Ko qu’impose save_qml_file au contenu transmis directement dans l’appel. Le contenu lui-même n’apparaît jamais dans un appel d’outil : vous demandez un identifiant de téléversement, téléversez les octets directement en HTTPS, puis finalisez.
-
request_upload_url(qml_name, project_id?)— crée un identifiant de téléversement de courte durée, à usage unique et limité en taille.Renvoie :
{ upload_url, artifact_id, max_size_bytes, expires_in } -
Téléversez les octets QML bruts directement vers
upload_url(une requête HTTPPUT, en dehors de l’appel d’outil MCP). -
finalize_upload(artifact_id, base_version_id)— enregistre le contenu téléversé exactement commesave_qml_filel’enregistrerait sur cette base : accepté, fusionné avec une sauvegarde plus récente, ou refusé.base_version_idest obligatoire et a le même sens que poursave_qml_file. Peut être réessayé sans risque avec le mêmeartifact_id: après une finalisation qui a enregistré, ou qui a réponduoverlap, une nouvelle tentative renvoie la première réponse et n’écrit rien, quelle que soit la base indiquée.Renvoie : la même enveloppe que
save_qml_fileUn
overlapconsomme l’identifiant de téléversement, car les octets téléversés ont été écrits à partir de l’ancienne version : relisez, réappliquez votre modification et téléversez le résultat via un nouvel identifiant.base_version_unknownethead_kept_movingconservent l’identifiant : un appel corrigé enregistre le même téléversement.
validate_qml_file
Section intitulée « validate_qml_file »Exécute la validation formelle SMT Z3 sur la version actuelle d’un questionnaire. Analyse l’accessibilité, la cohérence et la satisfaisabilité des postconditions pour chaque item.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
qml_name |
string |
Oui | — | Adresse du questionnaire |
Renvoie :
{ "is_valid": true, "item_count": 12, "block_count": 3, "item_classifications": { "q_age": { "precondition": "REACHABLE", "postcondition": "CONTINGENT" } }, "statistics": { "preconditions": {"REACHABLE": 11, "NEVER": 1}, "postconditions": {"CONTINGENT": 8, "TAUTOLOGICAL": 3, "INFEASIBLE": 1} }, "issues": [ { "item_id": "q_unreachable", "severity": "error", "type": "unreachable_item", "message": "Item is unreachable", "suggestion": "Check preconditions" } ], "validation_report": "..."}Référence des classifications
Section intitulée « Référence des classifications »États des préconditions (l’item peut-il être atteint ?) :
| État | Signification |
|---|---|
REACHABLE |
L’item peut être atteint par au moins un chemin du parcours |
NEVER |
L’item est inaccessible — code mort |
UNKNOWN |
L’analyse n’a pas pu déterminer l’accessibilité |
États des postconditions (les conditions de l’item sont-elles satisfaisables ?) :
| État | Signification |
|---|---|
TAUTOLOGICAL |
La condition est toujours vraie (redondante) |
CONTINGENT |
La condition dépend des réponses (cas normal) |
INFEASIBLE |
La condition ne peut jamais être satisfaite |
UNKNOWN |
L’analyse n’a pas pu conclure |
Types de problèmes
Section intitulée « Types de problèmes »| Type | Gravité | Description |
|---|---|---|
unreachable_item |
error | La précondition vaut NEVER — item mort |
code_answered_item |
warning | Un codeBlock enregistre la réponse de l’item avant que le parcours ne l’atteigne, sur chaque parcours où sa condition d’accès est vraie : l’item n’est donc jamais posé. Déplacez le codeBlock après l’item si celui-ci doit être posé |
infeasible_postcondition |
error | La postcondition ne peut jamais être satisfaite |
globally_false_postcondition |
error | La postcondition est toujours fausse |
tautological_postcondition |
warning | La postcondition est toujours vraie (redondante) |
comment_titled_as_question |
warning | Un Comment, purement informatif, a pour titre une demande : il s’affiche sans champ permettant d’y répondre |
roster_subject_not_answerable |
warning | Le subjectFrom d’un Roster nomme un item qui ne peut jamais fournir de sujet (absent, hors du bloc, ou un Comment) |
none_unsafe_reference |
warning | Une condition compare ou calcule sur un item qui n’est pas posé sur chaque chemin qui y mène — le résultat de cet item vaut None et le prédicat lève une exception. L’égalité avec None est sûre et n’est pas signalée |
inexact_condition |
warning | Une condition lit un item qui peut rester sans réponse, à un endroit où le validateur ne peut pas déterminer si la lecture de None la fait échouer (sous not, dans un opérande de or autre que le dernier, ou n’importe où dans une postcondition). Une contradiction est tout de même signalée, mais la condition n’est pas prouvée toujours vraie. Testez d’abord l’existence d’une réponse : q.outcome is not None and (…) dans une précondition, q.outcome is None or (…) dans une postcondition |
uninitialized_read |
warning | Une condition ou un codeBlock lit une variable qu’un répondant peut atteindre avant toute affectation — elle est affectée plus tard, sur une seule branche, ou par un item que sa propre condition d’accès peut faire sauter. La lecture lève une exception : une précondition fait sauter l’item, tandis qu’une postcondition accepte la réponse sans la vérifier et qu’un codeBlock s’arrête en cours de route — deux cas qui excluent l’enquête des jeux de données. Affectez une valeur par défaut dans codeInit, affectez sur les deux branches, ou soumettez la lecture à la même condition que l’affectation |
self_assignment |
warning | Une instruction de codeBlock affecte une valeur à elle-même (q.outcome = q.outcome) — elle ne change rien mais se lit comme une dérivation |
mandated_answer_postcondition |
warning | Une postcondition n’admet qu’une seule réponse d’un contrôle à choix : un répondant qui donne une autre réponse ne peut pas avancer, et cette réponse n’est jamais enregistrée. Orientez plutôt le parcours selon la réponse |
combinable_none_option |
warning | Une option de Checkbox du type « Aucune de ces réponses » peut être cochée en même temps que les options qu’elle exclut, et aucune postcondition ne refuse cette combinaison |
questionnaire_level_condition |
warning | Une clé precondition/postcondition au niveau racine. Les conditions ne sont évaluées qu’au niveau des items et des blocs : celle-ci ne s’exécute donc jamais |
language_not_judged |
warning | La langue du questionnaire ne fait pas partie des langues prises en charge : les contrôles fondés sur les mots n’ont donc pas été exécutés, à savoir la partie formulation de comment_titled_as_question (un ? dans le titre d’un Comment reste vérifié) et combinable_none_option. Vérifiez-les vous-même |
file_not_found |
error | L’adresse ne correspond à aucun questionnaire |
validation_error |
error | Exception lors de l’analyse syntaxique ou de l’analyse formelle |
qml_quality_report
Section intitulée « qml_quality_report »Calcule une grille d’évaluation de la qualité de conception (dimensions D2–D8) pour la version actuelle d’un questionnaire. Utilisez-la après que validate_qml_file a signalé zéro erreur : la validation prouve la cohérence logique ; cette grille évalue la qualité de conception (économie de l’instrument, densité des contrôles de qualité, couverture de vérification, complexité structurelle, cohérence de l’ordre, diversité des parcours et équilibre de la charge). La densité des contrôles de qualité se mesure sur les saisies numériques du questionnaire — les réponses qu’un répondant tape ou règle avec un curseur, là où une postcondition ajoute une borne de validité que le contrôle lui-même n’impose pas. Les items à choix sont exclus de ce taux, car leur jeu de libellés fixe déjà la réponse ; une postcondition qui lie un choix à un autre est signalée à part, comme contrôle de cohérence. Déterministe et indicative : les notes n’affectent jamais is_valid ni la publication.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
qml_name |
string |
Oui | — | Adresse du questionnaire |
Renvoie :
{ "dimensions": { "instrument_economy": { "id": "D2", "grade": "strong", "metrics": { }, "offenders": [{"item_id": "...", "detail": "..."}], "truncated": false } }, "item_count": 12, "notes": []}La grade de chaque dimension vaut strong, adequate, weak ou not_applicable. Une adresse inconnue ou un échec de l’analyse renvoie { error }.
publish_qml_file
Section intitulée « publish_qml_file »Publie un questionnaire sur une campagne — la porte d’entrée du terrain, et le seul outil de cette référence qui refuse une conception incohérente.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
questionnaire_id |
string |
Oui | — | UUID du questionnaire à mettre sur le terrain |
campaign_id |
string |
Oui | — | UUID de la campagne sur laquelle l’épingler |
La version actuelle du questionnaire est validée formellement, le verdict est consigné sur cette version, et seul un verdict sans erreur l’épingle sur la campagne.
Renvoie : { success, questionnaire_id, campaign_id, qml_version_id, logic_validated }
En cas de refus : { error, issues } — issues liste les problèmes de gravité « erreur » à corriger. Rien n’est épinglé : la campagne continue de diffuser ce qu’elle diffusait.
La campagne doit déjà faire référence à ce questionnaire ; si elle en diffuse un autre, rattachez-la d’abord avec update_campaign_questionnaire.
move_qml_to_project
Section intitulée « move_qml_to_project »Déplace un questionnaire vers un autre projet. L’identifiant du questionnaire reste stable et sa chaîne de versions n’est pas modifiée : les campagnes qui y font référence — y compris celles épinglées sur une version antérieure — continuent de fonctionner. Un déplacement n’est pas une modification.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
questionnaire_id |
string |
Oui | — | UUID du questionnaire |
target_project_id |
string |
Oui | — | UUID du projet de destination |
Renvoie : { success, questionnaire_id, qml_name } — qml_name est la nouvelle adresse.
unpublish_qml_file
Section intitulée « unpublish_qml_file »Retire un questionnaire de son projet en le supprimant logiquement. Sa chaîne de versions QML est conservée — une campagne terminée peut encore être épinglée sur l’une de ces versions : la dépublication retire donc le questionnaire de votre espace de travail sans effacer ce qui a été diffusé sur le terrain. Bloqué si le questionnaire a des campagnes actives.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
questionnaire_id |
string |
Oui | — | UUID du questionnaire |
Renvoie : { success, questionnaire_id } ou une erreur.
Traductions
Section intitulée « Traductions »Une traduction est un texte traduit associé à une version de questionnaire, une par langue. Elle ne remplace que le texte visible par les répondants ; les identifiants, les codes d’option, les conditions et le verdict Z3 restent ceux de la source. Seule une traduction complète est proposée aux répondants. Notions, gel et sélecteur de langue du répondant : Traduire un questionnaire.
Chaque outil de traduction nomme questionnaire_id, version_id (le version_id renvoyé par get_qml_content ou par une sauvegarde) et, sauf pour la liste, locale (en, es, fr, de ou hu, jamais la langue source du questionnaire lui-même). Chacun reporte d’abord les traductions de la version précédente sur la version nommée : une version nouvellement enregistrée contient donc déjà tous les textes dont la source n’a pas changé.
Les clés de texte désignent chacune un texte visible par les répondants : questionnaire/title, block:<id>/title, item:<id>/title, item:<id>/labels/<code> (libellés d’option, par code), item:<id>/rows/<n> et /columns/<n> (matrice), item:<id>/questions/<n> (groupe de questions), item:<id>/left, /right, /on, /off, /placeholder, et .../postcondition/<n>/hint (le message affiché lorsqu’une réponse est refusée). Lisez les clés exactes d’une version dans les source_texts de get_qml_translation.
list_qml_translations
Section intitulée « list_qml_translations »Toutes les traductions d’une version, par langue.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
questionnaire_id |
string |
Oui | — | UUID du questionnaire |
version_id |
string |
Oui | — | Une version de ce questionnaire |
Renvoie : { questionnaire_id, version_id, source_language, translations: [{ locale, started, withdrawn, complete, untranslated, frozen, human_edited, updated_at }] }, avec une entrée pour chaque langue prise en charge sauf la langue source : la liste nomme donc aussi les langues que personne n’a commencées (started: false, avec untranslated laissé vide : toutes les clés le sont, et get_qml_translation les liste) et celles dont la traduction a été supprimée (withdrawn: true). untranslated liste les clés de texte encore manquantes ; frozen signifie qu’une enquête a reçu des réponses dans cette langue, de sorte que la traduction n’accepte plus ni sauvegarde ni suppression ; human_edited signifie qu’une personne l’a modifiée dans l’éditeur.
get_qml_translation
Section intitulée « get_qml_translation »La traduction d’une langue, avec la source qu’elle traduit.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
questionnaire_id |
string |
Oui | — | UUID du questionnaire |
version_id |
string |
Oui | — | Une version de ce questionnaire |
locale |
string |
Oui | — | Langue cible |
Renvoie : les champs de la liste pour cette langue, plus texts (clé → texte traduit), source_language et source_texts (chaque clé traduisible → son texte source, dans l’ordre du document). Une langue encore dépourvue de traduction renvoie des texts vides et updated_at: null.
save_qml_translation
Section intitulée « save_qml_translation »Enregistre le texte traduit d’une langue. La sauvegarde est partielle : texts est fusionné avec la traduction enregistrée, et chaque clé que vous omettez conserve son texte enregistré ; pour combler les manques, il suffit donc d’envoyer les clés listées dans untranslated.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
questionnaire_id |
string |
Oui | — | UUID du questionnaire |
version_id |
string |
Oui | — | Une version de ce questionnaire |
locale |
string |
Oui | — | Langue cible |
texts |
object |
Oui | — | Clé de texte → texte traduit |
base_updated_at |
string | null |
Oui | — | Le updated_at renvoyé par votre lecture ; null si elle n’a renvoyé aucune traduction enregistrée |
Renvoie : la traduction enregistrée (texts, complete, untranslated, frozen, human_edited, updated_at). Une sauvegarde suivante nomme le updated_at renvoyé par celui-ci. Une sauvegarde effectuée via MCP ou l’API est consignée comme écrit par un agent et ne marque jamais la traduction comme human_edited.
| Refus | Signification | Que faire |
|---|---|---|
| Clés invalides (requête incorrecte, une ligne par clé) | Une clé nomme un item, un bloc ou un code d’option absent de la source, un index hors limites, une liste positionnelle (rows, columns, questions, indications de postcondition) envoyée en partie, une valeur qui n’est pas du texte, ou du balisage tel que <script> |
Corrigez exactement les clés nommées, puis enregistrez de nouveau |
translation_conflict (409) |
La traduction a changé depuis votre lecture, généralement à la suite d’une modification par un chercheur | Relisez avec get_qml_translation, réappliquez votre modification et enregistrez avec le nouveau updated_at |
translation_frozen (409) |
Une enquête a reçu des réponses dans cette langue sur cette version | Ne réessayez pas. Enregistrez une nouvelle version du questionnaire, traduisez-la, puis faites passer la campagne sur cette version |
| Langue source (requête incorrecte) | La langue est celle du questionnaire lui-même | Modifiez directement le QML, ou traduisez dans une autre langue |
| Introuvable | La version n’est pas une version de ce questionnaire | Lisez le questionnaire avec get_qml_content et nommez le version_id qu’il renvoie |
delete_qml_translation
Section intitulée « delete_qml_translation »Supprime la traduction d’une version dans une langue. Une traduction gelée est refusée (translation_frozen), et une langue sans traduction est introuvable.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
questionnaire_id |
string |
Oui | — | UUID du questionnaire |
version_id |
string |
Oui | — | Une version de ce questionnaire |
locale |
string |
Oui | — | Langue à supprimer |
Renvoie : { questionnaire_id, version_id, locale, deleted: true }.
Gestion des erreurs
Section intitulée « Gestion des erreurs »Contraintes du cycle de vie QML
Section intitulée « Contraintes du cycle de vie QML »| Cas | Réponse |
|---|---|
| Dépublication avec des campagnes actives | {"error": "Cannot unpublish: questionnaire has active campaign {campaign_id}"} |
| Publication d’une version incohérente | {"error": "...", "issues": [...]} — rien n’est épinglé |
| Publication sur une campagne qui diffuse un autre questionnaire | {"error": "Campaign {id} fields questionnaire {other}, not {id}. Use update_campaign_questionnaire to rebind it first."} |
| Déjà dans le projet cible | {"error": "Questionnaire is already in this project"} |
Périmètre
Section intitulée « Périmètre »Chaque outil ne recherche les questionnaires qu’au sein de votre propre organisation. Une adresse appartenant à une autre organisation est indiscernable d’une adresse inexistante, et un project_id qui ne correspond pas au projet du questionnaire est refusé plutôt qu’ignoré en silence.
Erreurs courantes
Section intitulée « Erreurs courantes »| Cas | Réponse |
|---|---|
| Questionnaire introuvable | {"error": "Questionnaire {id} not found"} |
| Contexte d’organisation non défini | {"error": "Organization context not set"} |
| L’adresse ne correspond à aucun questionnaire | {"error": "QML document '{name}' not found for this organization"} |
| La sauvegarde ne nomme aucune base utilisable | {"success": false, "error": "base_version_unknown", "detail": "..."} |
| La sauvegarde chevauche une sauvegarde plus récente | {"success": false, "error": "overlap", "head_version_id": "...", "head_version_number": n, "conflict_count": n} |
| Erreur d’analyse du QML | {"error": "Failed to parse QML: {details}"} |