Fragebogen- und QML-Tools — MCP-Tool-Referenz
Die Fragebogen-Tools verwalten den Lebenszyklus von QML: neue Versionen speichern, mit der formalen Z3-Analyse validieren, eine Version in einer Kampagne veröffentlichen, zwischen Projekten verschieben und zurückziehen. Dabei gelten feste Regeln – so ist das Zurückziehen gesperrt, solange aktive Kampagnen auf den Fragebogen verweisen.
Wie QML gespeichert wird
Abschnitt betitelt „Wie QML gespeichert wird“Das QML eines Fragebogens liegt in der Datenbank von Askalot als nur anfügbare Versionskette (append-only). Jeder Speichervorgang fügt eine neue Version hinzu und setzt den Head des Fragebogens auf sie; frühere Versionen werden nie überschrieben oder gelöscht.
qml_name ist die stabile Adresse des Fragebogens, in der Form projects/{project_id}/questionnaires/{questionnaire_id}.qml. Sie sieht aus wie ein Pfad und liest sich wie einer, bezeichnet aber einen Fragebogen – es gibt kein Verzeichnis zum Durchsuchen und keine Datei zum Bereitstellen. list_qml_files liefert die vorhandenen Adressen.
Daraus folgen drei Regeln, die den Großteil des nachfolgend beschriebenen Verhaltens erklären:
- Ein Speichervorgang nennt die Version, von der aus er geschrieben wurde. Was Sie speichern, beruht auf Inhalt, den Sie kurz zuvor gelesen haben, und inzwischen hat womöglich jemand anderes gespeichert. Deshalb erwarten
save_qml_fileundfinalize_uploadeinenbase_version_id: dieversion_idder Lese- oder Speicherantwort, aus der Ihr Inhalt stammt. Ist der Head noch diese Version, wird Ihr Inhalt zum neuen Head. Hat er sich bewegt und betreffen die beiden Änderungen unterschiedliche Zeilen, wird die Zusammenführung beider zum Head. Haben beide dieselben Zeilen geändert, wird nichts geschrieben, und die Antwort lautetoverlap. - Die Validierung verhindert das Speichern nie. Ein Entwurf, ein eingefügter Block oder halb fertige Logik müssen speicherbar sein. Ein Speichervorgang hält daher das Urteil der formalen Validierung an der entstehenden Version fest und gibt etwaige Probleme als
warningszurück. Abgesehen von einer Adresse, die auf keinen für Sie beschreibbaren Fragebogen verweist, und einem Aufruf, den das Eingabeschema zurückweist, wird ein Speichervorgang nur abgelehnt bei: einer Basis, die keine Version des Fragebogens ist (base_version_unknown), einemoverlap, einem Head, der sich vor jedem Versuch bewegt hat (head_kept_moving), einem Fragebogen, der während der Speicherung in ein anderes Projekt verschoben wurde (questionnaire_moved), einer versiegelten Organisation (org_sealed) und Inline-Inhalt über 32 KB. - Das Veröffentlichen kann dagegen abgelehnt werden.
publish_qml_fileheftet eine Version an eine Kampagne – der Moment, in dem das Instrument eine befragte Person erreicht. Daher ist dies die eine Schranke, die ein logisch fehlerhaftes Design zurückweist. Die angeheftete Version ist danach für die gesamte Laufzeit dieser Kampagne unveränderlich.
list_questionnaires
Abschnitt betitelt „list_questionnaires“Listet alle Fragebögen auf, optional nach Namen gefiltert.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
name |
string |
Nein | — | Teilzeichenfolgen-Filter ohne Berücksichtigung der Groß- und Kleinschreibung |
limit |
integer |
Nein | 100 |
Maximale Anzahl an Ergebnissen |
Rückgabe: { items: [...], count, limit }
get_questionnaire
Abschnitt betitelt „get_questionnaire“Ruft einen Fragebogen anhand seiner ID ab.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | UUID des Fragebogens |
Rückgabe: Fragebogenobjekt oder { error }.
create_questionnaire
Abschnitt betitelt „create_questionnaire“Legt einen neuen Fragebogen aus QML-Inhalt oder aus einer Vorlage der Bibliothek an. Der Fragebogen und Version 1 seines QML entstehen gemeinsam, sodass ein Fragebogen nie ohne Inhalt existiert.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
name |
string |
Mit content |
der Name der Vorlage | Anzeigename |
content |
string |
Eines von content / template |
— | Das QML-YAML, gespeichert als Version 1 |
template |
string |
Eines von content / template |
— | Ein Vorlagen-Slug aus list_questionnaire_templates; Version 1 ist das QML dieser Vorlage in language, Byte für Byte |
project_id |
string |
Ja | — | ID des übergeordneten Projekts |
description |
string |
Nein | — | Freitextbeschreibung |
language |
string |
Nein | "en"; mit template Ihre eigene |
Sprachcode. Mit template die Sprache, in der die Vorlage kopiert wird: eine der languages der Bibliothek. Ohne Angabe Ihre eigene Sprache (Ihre Einstellung, sonst der Standard Ihrer Organisation), sofern die Bibliothek sie anbietet, sonst en |
estimated_duration |
integer |
Nein | — | Voraussichtliche Bearbeitungszeit in Minuten |
Geben Sie content oder template an, nie beides: Beides oder keines von beiden wird abgelehnt, und es wird nichts geschrieben. Ein unbekannter template-Slug führt zur Antwort „nicht gefunden“, und eine language, die die Bibliothek nicht anbietet, wird unter Nennung der angebotenen Sprachen abgelehnt.
Eine Vorlagenkopie wird in der Sprache geschrieben, in der sie gelesen wurde, und jede andere Sprache, die die Bibliothek anbietet, kommt als Übersetzung von Version 1 mit. So können Befragten diese Sprachen ohne eigenen Übersetzungsschritt angeboten werden.
Rückgabe: Das angelegte Fragebogenobjekt sowie version_id und version_number von Version 1. version_id ist der base_version_id für eine erste Speicherung dieses Inhalts.
Das Anlegen hängt nicht von der formalen Validierung ab – content darf strukturell fehlerhaft sein. Bei content wird das Urteil mit Version 1 festgehalten, aber nicht durchgesetzt; erst das Veröffentlichen in einer Kampagne verlangt Korrektheit. Bei einem template läuft die Validierung wenige Sekunden nach dem Anlegen im Hintergrund, wie nach einem Speichervorgang: Bis dahin lautet logic_validated false.
list_questionnaire_templates
Abschnitt betitelt „list_questionnaire_templates“Listet die Vorlagenbibliothek für Fragebögen auf: fertige Fragebögen (Lehrveranstaltungsevaluationen, Kundenfeedback, Veranstaltungsanmeldungen, Patientenaufnahme und mehr), gruppiert in Kategorien. Übergeben Sie einen Slug als template an create_questionnaire.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
language |
string |
Nein | Ihre eigene | Die Bibliothekssprache, in der die Vorlagen aufgelistet werden. Ohne Angabe Ihre eigene Sprache (Ihre Einstellung, sonst der Standard Ihrer Organisation), sofern die Bibliothek sie anbietet, sonst en. Eine Sprache, die die Bibliothek nicht anbietet, wird unter Nennung der angebotenen abgelehnt |
category |
string |
Nein | — | Ein Kategorie-Slug; ein unbekannter wird mit der Liste der Kategorien abgelehnt |
query |
string |
Nein | — | Wörter, die alle im Namen oder in der Beschreibung einer Vorlage vorkommen müssen, unabhängig von Groß- und Kleinschreibung |
limit |
integer |
Nein | 50 |
Seitengröße, 1 bis 100 |
cursor |
string |
Nein | — | Der next_cursor der vorherigen Seite |
Rückgabe: { data: [{ slug, name, category, subcategory, description }], categories: [{ slug, name }], language, language_fallback, languages, total, next_cursor, has_more }. Namen, Beschreibungen und Kategorien sind in language; languages listet jede Sprache, die die Bibliothek anbietet, en zuerst. language_fallback ist true, wenn keine language angegeben wurde und die Bibliothek Ihre Sprache noch nicht anbietet, sodass die Antwort auf Englisch ist: Teilen Sie das dem Benutzer mit. total zählt jede passende Vorlage; folgen Sie next_cursor, solange has_more wahr ist. Es wird kein QML-Inhalt aufgelistet: Legen Sie den Fragebogen aus einem Slug an und lesen Sie ihn dann mit get_qml_content.
delete_questionnaire
Abschnitt betitelt „delete_questionnaire“Löscht einen Fragebogen vorläufig (Soft Delete).
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | UUID des Fragebogens |
Rückgabe: { success: true, questionnaire_id } oder ein Fehler.
Das vorläufige Löschen legt eine Sicherungszeile an; mit restore_questionnaire (siehe unten) lässt sich der Fragebogen für kurze Zeit zurückholen.
rename_questionnaire
Abschnitt betitelt „rename_questionnaire“Benennt einen Fragebogen um. Eine reine Änderung der Metadaten – Adresse und QML-Versionskette des Fragebogens bleiben unverändert, sodass Kampagnen, die auf ihn verweisen, weiter funktionieren.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | UUID des Fragebogens |
name |
string |
Ja | — | Neuer Anzeigename (max. 255 Byte) |
Rückgabe: Das aktualisierte Fragebogenobjekt.
restore_questionnaire
Abschnitt betitelt „restore_questionnaire“Stellt einen kürzlich vorläufig gelöschten Fragebogen wieder her und verknüpft seine Verweise neu. Seine QML-Versionskette wurde beim Löschen nie angetastet, daher kehrt der wiederhergestellte Fragebogen genau mit der Version zurück, die er hatte.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | UUID des Fragebogens |
Rückgabe: Das wiederhergestellte Fragebogenobjekt oder ein Fehler, wenn das Wiederherstellungsfenster abgelaufen ist.
list_qml_files
Abschnitt betitelt „list_qml_files“Listet die QML-Fragebögen der Organisation auf. Keine Parameter erforderlich. Den qml_name jedes Eintrags können Sie an jedes andere QML-Tool übergeben.
Rückgabe:
{ "items": [ { "name": "3f9c2b10-....qml", "qml_name": "projects/abc123/questionnaires/3f9c2b10-....qml", "tier": "project", "project_id": "abc123" } ], "count": 1}inspect_qml_file
Abschnitt betitelt „inspect_qml_file“Liefert eine kurze Zusammenfassung der aktuellen Version eines Fragebogens – Anzahl der Elemente und Metadaten ohne den vollständigen Inhalt.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
qml_name |
string |
Ja | — | Adresse des Fragebogens aus list_qml_files |
Rückgabe: { success, qml_name, items_count, metadata }
preview_qml_item
Abschnitt betitelt „preview_qml_item“Zeigt ein Element der aktuellen Version eines Fragebogens so, wie eine befragte Person es sieht. Ein Host, der MCP Apps darstellt (etwa Claude), öffnet ein schreibgeschütztes Panel mit den echten Steuerelementen des Elements; jeder andere Host erhält dasselbe Element als JSON-Text.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
qml_name |
string |
Ja | — | Adresse des Fragebogens aus list_qml_files |
item_id |
string |
Ja | — | Die id des Elements |
Rückgabe: die dargestellten Felder des Elements (id, kind, title, input sowie questions, rows oder columns, sofern das Element sie hat), wobei jedes Markup im Text bereinigt ist. Ein unbekanntes Element oder eine unbekannte Adresse ist ein Tool-Fehler.
get_qml_content
Abschnitt betitelt „get_qml_content“Ruft das rohe YAML der aktuellen Version eines Fragebogens ab.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
qml_name |
string |
Ja | — | Adresse des Fragebogens |
Rückgabe: { success, qml_name, content, size_bytes, version_id, version_number } für Inhalt bis 32 KB. version_id nennt die Version, die content darstellt; übergeben Sie sie als base_version_id, wenn Sie Inhalt speichern, der auf dieser Antwort beruht.
Über 32 KB wird der Inhalt nicht direkt eingebettet – die Antwort lautet dann { success, qml_name, download_url, size_bytes, version_id, version_number, note }, wobei download_url ein kurzlebiger Link ist (bis zum Ablauf wiederverwendbar), den Sie direkt per HTTPS abrufen (ohne weitere Authentifizierung). Der Link liefert version_id, auch wenn ein Speichervorgang den Head inzwischen weiterbewegt hat; seine Bytes sind also die Version, die Sie beim Speichern als base_version_id angeben. Rufen Sie get_qml_content erneut auf, wenn der Link abgelaufen ist.
save_qml_file
Abschnitt betitelt „save_qml_file“Speichert QML-Inhalt in einem bestehenden Fragebogen, geschrieben auf Basis einer von Ihnen genannten Version. Fehlerhaftes YAML oder Schemaverstöße verhindern das Speichern nie – ein noch unfertiger, noch nicht gültiger Entwurf wird trotzdem gespeichert, und Probleme kommen als warnings-Liste zurück, statt den Schreibvorgang abzulehnen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
qml_name |
string |
Ja | — | Adresse eines bestehenden Fragebogens |
content |
string |
Ja | — | QML-YAML-Inhalt, bis 32 KB |
base_version_id |
string |
Ja | — | Die Version, von der aus der Inhalt geschrieben wurde: die version_id Ihrer letzten Antwort von get_qml_content, create_questionnaire oder einer Speicherung für diesen Fragebogen |
project_id |
string |
Nein | — | Muss, sofern angegeben, mit dem Projekt des Fragebogens übereinstimmen; eine Abweichung wird abgelehnt statt ignoriert |
Erst lesen, dann speichern. Rufen Sie get_qml_content auf, wenden Sie Ihre Änderung auf den zurückgegebenen Inhalt an und speichern Sie mit dessen version_id als base_version_id. Nach einem Speichervorgang nennt der nächste Speichervorgang die version_id, die dieser zurückgegeben hat, nie eine frühere.
Rückgabe: { success, qml_name, questionnaire_id, version_id, version_number, created, merged, content_changed, bytes_written, logic_validated, content?, content_note?, warnings? }.
| Was geschehen ist | In der Antwort |
|---|---|
| Die Basis war noch der Head | created: true, merged: false. Ihr Inhalt ist der neue Head |
| Jemand hat dazwischen gespeichert, in anderen Zeilen | created: true, merged: true, content_changed: true. Der Head enthält beide Änderungen, und content enthält ihn: Er ersetzt Ihre Kopie. Zeilen darin, die Sie nicht geschrieben haben, stammen von der anderen Person |
| Ihr Inhalt ist bereits der Head | created: false. Es wird nichts geschrieben |
| Ihr Inhalt entspricht seiner Basis, und der Head hat sich bewegt | created: false, content_changed: true, mit dem content des Heads |
content ist nur enthalten, wenn der gespeicherte Inhalt unter 32 KB liegt; andernfalls weist content_note darauf hin, get_qml_content aufzurufen. warnings fehlt bei einem sauberen Speichervorgang oder ist bei einem gespeicherten, aber unvollkommenen Entwurf eine Liste von Parse- und Schemaproblemen.
Eine Speicherung, die nichts schreibt, antwortet mit { success: false, error, detail }:
error |
Bedeutung | Vorgehen |
|---|---|---|
overlap |
Jemand hat dazwischen gespeichert und dieselben Zeilen geändert. Enthält head_version_id, head_version_number, conflict_count |
Rufen Sie get_qml_content auf, wenden Sie Ihre Änderung auf das Ergebnis an und speichern Sie mit dessen version_id. Senden Sie nicht denselben Inhalt erneut unter der neueren ID: Das würde die andere Speicherung ersetzen |
base_version_unknown |
base_version_id ist leer, keine Versions-ID oder keine Version dieses Fragebogens |
Rufen Sie get_qml_content auf und speichern Sie mit der zurückgegebenen version_id |
head_kept_moving |
Der Fragebogen wurde vor jedem von drei Versuchen erneut gespeichert | Erneut lesen und wiederholen |
org_sealed |
Die Organisation ist versiegelt | Es kann nichts geschrieben werden |
questionnaire_moved |
Der Fragebogen wurde während der Speicherung in ein anderes Projekt verschoben | Rufen Sie list_qml_files für seine aktuelle Adresse auf, lesen Sie ihn mit get_qml_content und speichern Sie erneut |
Die formale Validierung läuft wenige Sekunden nach der Speicherung im Hintergrund auf der Version, die dann der Head ist (Ihre oder die Zusammenführung), und ihr Urteil wird an dieser Version festgehalten. So bleibt die Korrektheit einer Version auch nach weiteren Änderungen später abrufbar. Bis dahin ist logic_validated in der Speicherantwort null, logic_validation_note weist darauf hin, und get_questionnaire liest logic_validated: false; sobald das Urteil vorliegt, liefert das Tool dieses, und validate_qml_file meldet es auf Anfrage. Ein Speichervorgang, der etwas verschlechtert, setzt den Fragebogen auf nicht validiert, ohne den Schreibvorgang zu blockieren; das Veröffentlichen in einer Kampagne wird abgelehnt, bis der Fehler behoben ist.
Eine Adresse, hinter der kein Fragebogen steht, wird abgelehnt – rufen Sie zuerst create_questionnaire auf.
Inhalt über 32 KB wird abgelehnt, mit {"error": "content_too_large_for_inline_save"}, und es wird nichts geschrieben. Verwenden Sie stattdessen request_upload_url / finalize_upload (siehe unten), statt den Inhalt passend zu kürzen.
request_upload_url / finalize_upload
Abschnitt betitelt „request_upload_url / finalize_upload“Ein zweistufiges Verfahren, um QML-Inhalt zu speichern, der für das 32-KB-Inline-Limit von save_qml_file zu groß ist. Der Inhalt selbst erscheint nie in einem Tool-Aufruf – Sie fordern ein Handle an, laden die Bytes direkt per HTTPS hoch und schließen dann ab.
-
request_upload_url(qml_name, project_id?)– erzeugt ein kurzlebiges, einmal verwendbares, größenbegrenztes Upload-Handle.Rückgabe:
{ upload_url, artifact_id, max_size_bytes, expires_in } -
Laden Sie die rohen QML-Bytes direkt nach
upload_urlhoch (ein HTTP-PUT, außerhalb des MCP-Tool-Aufrufs). -
finalize_upload(artifact_id, base_version_id)– speichert den hochgeladenen Inhalt genau so, wiesave_qml_fileihn auf dieser Basis speichern würde: übernommen, mit einem neueren Speichervorgang zusammengeführt oder abgelehnt.base_version_idist erforderlich und bedeutet dasselbe wie beisave_qml_file. Ein Wiederholen mit derselbenartifact_idist sicher: Nach einem Abschluss, der gespeichert oder mitoverlapgeantwortet hat, liefert eine Wiederholung die erste Antwort und schreibt nichts, gleich welche Basis sie nennt.Rückgabe: dieselbe Antwortstruktur wie bei
save_qml_fileEin
overlapverbraucht das Handle, weil die hochgeladenen Bytes auf Basis der alten Version geschrieben wurden: Lesen Sie erneut, wenden Sie Ihre Änderung erneut an und laden Sie das Ergebnis über ein neues Handle hoch.base_version_unknownundhead_kept_movingbehalten das Handle, sodass ein korrigierter Aufruf denselben Upload speichert.
validate_qml_file
Abschnitt betitelt „validate_qml_file“Führt die formale Z3-SMT-Validierung für die aktuelle Version eines Fragebogens aus. Analysiert für jedes Element Erreichbarkeit, Konsistenz und Erfüllbarkeit der Nachbedingungen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
qml_name |
string |
Ja | — | Adresse des Fragebogens |
Rückgabe:
{ "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": "..."}Referenz der Klassifikationen
Abschnitt betitelt „Referenz der Klassifikationen“Status der Vorbedingungen (kann das Element erreicht werden?):
| Status | Bedeutung |
|---|---|
REACHABLE |
Das Element ist auf mindestens einem Ablaufpfad erreichbar |
NEVER |
Das Element ist unerreichbar – toter Code |
UNKNOWN |
Die Analyse konnte die Erreichbarkeit nicht bestimmen |
Status der Nachbedingungen (sind die Bedingungen des Elements erfüllbar?):
| Status | Bedeutung |
|---|---|
TAUTOLOGICAL |
Die Bedingung ist immer wahr (redundant) |
CONTINGENT |
Die Bedingung hängt von den Antworten ab (normal) |
INFEASIBLE |
Die Bedingung kann nie erfüllt werden |
UNKNOWN |
Die Analyse konnte es nicht bestimmen |
Problemtypen
Abschnitt betitelt „Problemtypen“| Typ | Schweregrad | Beschreibung |
|---|---|---|
unreachable_item |
error | Die Vorbedingung ist NEVER – totes Element |
code_answered_item |
warning | Ein codeBlock speichert die Antwort des Elements, bevor der Durchlauf es erreicht, und zwar bei jedem Durchlauf, in dem seine Bedingung gilt – die Frage wird also nie gestellt. Verschieben Sie den codeBlock hinter das Element, wenn sie gestellt werden soll |
infeasible_postcondition |
error | Die Nachbedingung kann nie erfüllt werden |
globally_false_postcondition |
error | Die Nachbedingung ist immer falsch |
tautological_postcondition |
warning | Die Nachbedingung ist immer wahr (redundant) |
comment_titled_as_question |
warning | Ein reiner Anzeige-Comment ist als Aufforderung betitelt und wird daher ohne Feld zum Beantworten dargestellt |
roster_subject_not_answerable |
warning | subjectFrom eines Rosters nennt ein Element, das nie ein Subjekt liefern kann (fehlend, außerhalb des Blocks oder ein Comment) |
none_unsafe_reference |
warning | Eine Bedingung vergleicht der Größe nach oder rechnet mit einem Element, das nicht auf jedem dorthin führenden Pfad gestellt wird – dessen Ergebnis ist None, und das Prädikat löst einen Fehler aus. Ein Gleichheitsvergleich mit None ist sicher und wird nicht gemeldet |
inexact_condition |
warning | Eine Bedingung liest ein Element, das an einer Stelle unbeantwortet sein kann, an der der Validator nicht erkennen kann, ob das Lesen von None sie scheitern lässt (unter not, in einem or-Operanden vor dem letzten oder irgendwo in einer Nachbedingung). Ein Widerspruch wird weiterhin gemeldet, aber es ist nicht bewiesen, dass die Bedingung immer wahr ist. Prüfen Sie zuerst auf eine Antwort: q.outcome is not None and (…) in einer Vorbedingung, q.outcome is None or (…) in einer Nachbedingung |
uninitialized_read |
warning | Eine Bedingung oder ein codeBlock liest eine Variable, die eine befragte Person erreichen kann, bevor eine Zuweisung gelaufen ist – sie wird später zugewiesen, nur in einem Zweig oder von einem Element, das seine eigene Bedingung überspringen kann. Das Lesen löst einen Fehler aus: Eine Vorbedingung überspringt das Element; eine Nachbedingung akzeptiert die Antwort ungeprüft, und ein codeBlock bricht mittendrin ab – die beiden letzten Fälle schließen die Umfrage aus Datensätzen aus. Weisen Sie in codeInit einen Standardwert zu, weisen Sie in beiden Zweigen zu oder stellen Sie die lesende Stelle unter dieselbe Bedingung wie die Zuweisung |
self_assignment |
warning | Eine Anweisung in einem codeBlock weist einem Wert sich selbst zu (q.outcome = q.outcome) – sie ändert nichts, liest sich aber wie eine Ableitung |
mandated_answer_postcondition |
warning | Eine Nachbedingung lässt bei einem Auswahl-Steuerelement nur eine Antwort zu, sodass eine befragte Person mit jeder anderen Antwort nicht weiterkommt und diese Antwort nie erfasst wird. Verzweigen Sie stattdessen anhand der Antwort |
combinable_none_option |
warning | Eine Checkbox-Option im Stil von „Nichts davon“ lässt sich zusammen mit den Optionen ankreuzen, die sie ausschließt, und keine Nachbedingung verweigert diese Kombination |
questionnaire_level_condition |
warning | Ein precondition-/postcondition-Schlüssel auf Wurzelebene. Bedingungen werden nur auf Element- und Blockebene ausgewertet, diese läuft also nie |
language_not_judged |
warning | Die Sprache des Fragebogens liegt außerhalb der unterstützten Sprachen, daher liefen die wortbasierten Prüfungen nicht: der Formulierungsteil von comment_titled_as_question (ein ? im Titel eines Comment wird weiterhin geprüft) und combinable_none_option. Prüfen Sie diese von Hand |
file_not_found |
error | Hinter der Adresse steht kein Fragebogen |
validation_error |
error | Ausnahme beim Parsen oder bei der Analyse |
qml_quality_report
Abschnitt betitelt „qml_quality_report“Berechnet eine Scorecard der Designqualität (Dimensionen D2–D8) für die aktuelle Version eines Fragebogens. Verwenden Sie sie, nachdem validate_qml_file null Fehler gemeldet hat – die Validierung beweist logische Korrektheit, dieser Bericht bewertet die Designqualität (Instrumentenökonomie, Dichte der Qualitätsprüfungen, Verifikationsabdeckung, strukturelle Komplexität, Kohärenz der Reihenfolge, Pfadvielfalt und Belastungsbalance). Die Dichte der Qualitätsprüfungen wird über die numerischen Eingaben des Fragebogens gemessen – die Antworten, die eine befragte Person eintippt oder per Schieberegler einstellt und bei denen eine Nachbedingung eine Gültigkeitsgrenze hinzufügt, die das Steuerelement selbst nicht setzt. Auswahlelemente sind von dieser Quote ausgenommen, weil ihre Beschriftungsmenge die Antwort bereits festlegt; eine Nachbedingung, die eine Auswahl an eine andere bindet, wird gesondert als Konsistenzprüfung gemeldet. Deterministisch und beratend: Die Bewertungen beeinflussen nie is_valid oder das Veröffentlichen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
qml_name |
string |
Ja | — | Adresse des Fragebogens |
Rückgabe:
{ "dimensions": { "instrument_economy": { "id": "D2", "grade": "strong", "metrics": { }, "offenders": [{"item_id": "...", "detail": "..."}], "truncated": false } }, "item_count": 12, "notes": []}Der grade jeder Dimension ist strong, adequate, weak oder not_applicable. Eine unbekannte Adresse oder ein Analysefehler liefert { error }.
publish_qml_file
Abschnitt betitelt „publish_qml_file“Veröffentlicht einen Fragebogen in einer Kampagne – der Zugang zur Feldphase und das einzige Tool in dieser Referenz, das ein logisch fehlerhaftes Design ablehnt.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | UUID des Fragebogens, der ins Feld geht |
campaign_id |
string |
Ja | — | UUID der Kampagne, an die er angeheftet wird |
Die aktuelle Version des Fragebogens wird formal validiert, das Urteil wird an dieser Version festgehalten, und nur ein einwandfreies Urteil heftet sie an die Kampagne.
Rückgabe: { success, questionnaire_id, campaign_id, qml_version_id, logic_validated }
Bei Ablehnung: { error, issues } – issues listet die zu behebenden Probleme mit Schweregrad error. Es wird nichts angeheftet, die Kampagne erhebt also weiter mit dem, was sie hatte.
Die Kampagne muss bereits auf diesen Fragebogen verweisen; erhebt sie mit einem anderen, binden Sie sie zuerst mit update_campaign_questionnaire neu.
move_qml_to_project
Abschnitt betitelt „move_qml_to_project“Verschiebt einen Fragebogen in ein anderes Projekt. Die ID des Fragebogens bleibt stabil und seine Versionskette unberührt, sodass Kampagnen, die auf ihn verweisen – auch solche, die an eine frühere Version angeheftet sind –, weiter funktionieren. Ein Verschieben ist keine Bearbeitung.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | UUID des Fragebogens |
target_project_id |
string |
Ja | — | UUID des Zielprojekts |
Rückgabe: { success, questionnaire_id, qml_name } – qml_name ist die neue Adresse.
unpublish_qml_file
Abschnitt betitelt „unpublish_qml_file“Zieht einen Fragebogen aus seinem Projekt zurück, indem er vorläufig gelöscht wird. Seine QML-Versionskette wird beibehalten – eine abgeschlossene Kampagne kann noch an eine dieser Versionen angeheftet sein. Das Zurückziehen entfernt den Fragebogen daher aus Ihrem Arbeitsbestand, ohne zu löschen, was im Feld war. Gesperrt, wenn der Fragebogen aktive Kampagnen hat.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | UUID des Fragebogens |
Rückgabe: { success, questionnaire_id } oder ein Fehler.
Übersetzungen
Abschnitt betitelt „Übersetzungen“Eine Übersetzung ist übersetzter Text neben einer Version eines Fragebogens, je Sprache eine. Sie ersetzt nur den für Befragte sichtbaren Text; IDs, Optionscodes, Bedingungen und das Z3-Urteil bleiben die der Quelle. Befragten wird nur eine vollständige Übersetzung angeboten. Konzepte, Einfrieren und die Sprachauswahl für Befragte: Einen Fragebogen übersetzen.
Jedes Übersetzungs-Tool nennt questionnaire_id, version_id (die version_id, die get_qml_content oder ein Speichervorgang zurückgegeben hat) und, außer beim Auflisten, locale (en, es, fr, de oder hu, nie die eigene Quellsprache des Fragebogens). Jedes Tool überträgt zuerst die Übersetzungen der vorherigen Version auf die genannte Version, sodass eine neu gespeicherte Version bereits jeden Text enthält, dessen Quelle sich nicht geändert hat.
Textschlüssel benennen jeweils einen für Befragte sichtbaren Text: questionnaire/title, block:<id>/title, item:<id>/title, item:<id>/labels/<code> (Optionsbeschriftungen, nach Code), item:<id>/rows/<n> und /columns/<n> (Matrix), item:<id>/questions/<n> (Fragegruppe), item:<id>/left, /right, /on, /off, /placeholder sowie .../postcondition/<n>/hint (die Meldung, die bei einer abgelehnten Antwort erscheint). Die genauen Schlüssel einer Version lesen Sie aus source_texts von get_qml_translation.
list_qml_translations
Abschnitt betitelt „list_qml_translations“Alle Übersetzungen einer Version, je Locale.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | UUID des Fragebogens |
version_id |
string |
Ja | — | Eine Version dieses Fragebogens |
Rückgabe: { questionnaire_id, version_id, source_language, translations: [{ locale, started, withdrawn, complete, untranslated, frozen, human_edited, updated_at }] }, ein Eintrag für jede unterstützte Sprache außer der Quelle. Die Liste nennt also auch die Sprachen, mit denen niemand begonnen hat (started: false, wobei untranslated leer bleibt: Das gilt für jeden Schlüssel, und get_qml_translation listet sie), sowie diejenigen, deren Übersetzung gelöscht wurde (withdrawn: true). untranslated listet die noch fehlenden Textschlüssel; frozen bedeutet, dass eine Umfrage in dieser Sprache beantwortet wurde, sodass sie weder Speichern noch Löschen zulässt; human_edited bedeutet, dass eine Person sie im Editor bearbeitet hat.
get_qml_translation
Abschnitt betitelt „get_qml_translation“Die Übersetzung einer Locale, zusammen mit der Quelle, die sie übersetzt.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | UUID des Fragebogens |
version_id |
string |
Ja | — | Eine Version dieses Fragebogens |
locale |
string |
Ja | — | Zielsprache |
Rückgabe: die Listenfelder für diese Locale sowie texts (Schlüssel → übersetzter Text), source_language und source_texts (jeder übersetzbare Schlüssel → sein Quelltext, in Dokumentreihenfolge). Eine Locale ohne Übersetzung liefert leere texts und updated_at: null.
save_qml_translation
Abschnitt betitelt „save_qml_translation“Speichert übersetzten Text für eine Locale. Der Speichervorgang ist partiell: texts wird über die gespeicherte Übersetzung gelegt, und jeder Schlüssel, den Sie weglassen, behält seinen gespeicherten Text. Zum Auffüllen von Lücken senden Sie also nur die in untranslated aufgeführten Schlüssel.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | UUID des Fragebogens |
version_id |
string |
Ja | — | Eine Version dieses Fragebogens |
locale |
string |
Ja | — | Zielsprache |
texts |
object |
Ja | — | Textschlüssel → übersetzter Text |
base_updated_at |
string | null |
Ja | — | Das updated_at, das Ihr Lesevorgang geliefert hat; null, wenn er keine gespeicherte Übersetzung geliefert hat |
Rückgabe: die gespeicherte Übersetzung (texts, complete, untranslated, frozen, human_edited, updated_at). Ein weiterer Speichervorgang nennt das updated_at, das diese geliefert hat. Ein Speichervorgang über MCP oder die API wird als von einem Agenten geschrieben verbucht und markiert die Übersetzung nie als human_edited.
| Ablehnung | Bedeutung | Vorgehen |
|---|---|---|
| Ungültige Schlüssel (Bad Request, eine Zeile je Schlüssel) | Ein Schlüssel nennt ein Element, einen Block oder einen Optionscode, den die Quelle nicht hat, einen Index außerhalb des Bereichs, eine nur teilweise gesendete Positionsliste (rows, columns, questions, Hinweise der Nachbedingungen), einen Wert, der kein Text ist, oder Markup wie <script> |
Korrigieren Sie genau die genannten Schlüssel und speichern Sie erneut |
translation_conflict (409) |
Die Übersetzung hat sich seit Ihrem Lesen geändert, meist durch eine Bearbeitung von Forschenden | Lesen Sie erneut mit get_qml_translation, wenden Sie Ihre Änderung erneut an und speichern Sie mit dem neuen updated_at |
translation_frozen (409) |
In dieser Sprache wurde auf dieser Version eine Umfrage beantwortet | Nicht wiederholen. Speichern Sie eine neue Fragebogenversion, übersetzen Sie sie dort und stellen Sie die Kampagne auf sie um |
| Quellsprache (Bad Request) | Die Locale ist die eigene Sprache des Fragebogens | Bearbeiten Sie das QML selbst oder übersetzen Sie in eine andere Sprache |
| Nicht gefunden | Die Version ist keine Version dieses Fragebogens | Lesen Sie den Fragebogen mit get_qml_content und nennen Sie die zurückgegebene version_id |
delete_qml_translation
Abschnitt betitelt „delete_qml_translation“Löscht die Übersetzung einer Locale für eine Version. Eine eingefrorene Übersetzung wird abgelehnt (translation_frozen), und eine Locale ohne Übersetzung führt zur Antwort „nicht gefunden“.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | UUID des Fragebogens |
version_id |
string |
Ja | — | Eine Version dieses Fragebogens |
locale |
string |
Ja | — | Zu löschende Sprache |
Rückgabe: { questionnaire_id, version_id, locale, deleted: true }.
Fehlerbehandlung
Abschnitt betitelt „Fehlerbehandlung“Einschränkungen im QML-Lebenszyklus
Abschnitt betitelt „Einschränkungen im QML-Lebenszyklus“| Situation | Antwort |
|---|---|
| Zurückziehen bei aktiven Kampagnen | {"error": "Cannot unpublish: questionnaire has active campaign {campaign_id}"} |
| Eine logisch fehlerhafte Version veröffentlichen | {"error": "...", "issues": [...]} – es wird nichts angeheftet |
| In einer Kampagne veröffentlichen, die einen anderen Fragebogen erhebt | {"error": "Campaign {id} fields questionnaire {other}, not {id}. Use update_campaign_questionnaire to rebind it first."} |
| Bereits im Zielprojekt | {"error": "Questionnaire is already in this project"} |
Geltungsbereich
Abschnitt betitelt „Geltungsbereich“Jedes Tool löst Fragebögen ausschließlich innerhalb Ihrer eigenen Organisation auf. Eine Adresse, die zu einer anderen Organisation gehört, ist nicht von einer nicht existierenden zu unterscheiden, und eine project_id, die nicht mit dem Projekt des Fragebogens übereinstimmt, wird abgelehnt statt stillschweigend ignoriert.
Häufige Fehler
Abschnitt betitelt „Häufige Fehler“| Situation | Antwort |
|---|---|
| Fragebogen nicht gefunden | {"error": "Questionnaire {id} not found"} |
| Organisationskontext nicht gesetzt | {"error": "Organization context not set"} |
| Hinter der Adresse steht kein Fragebogen | {"error": "QML document '{name}' not found for this organization"} |
| Speicherung nennt keine verwendbare Basis | {"success": false, "error": "base_version_unknown", "detail": "..."} |
| Speicherung überschneidet sich mit einer neueren | {"success": false, "error": "overlap", "head_version_id": "...", "head_version_number": n, "conflict_count": n} |
| QML-Parse-Fehler | {"error": "Failed to parse QML: {details}"} |