Zum Inhalt springen
Wissensdatenbank

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.

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_file und finalize_upload einen base_version_id: die version_id der 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 lautet overlap.
  • 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 warnings zurü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), einem overlap, 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_file heftet 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.

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 }


Ruft einen Fragebogen anhand seiner ID ab.

Parameter Typ Erforderlich Standard Beschreibung
questionnaire_id string Ja — UUID des Fragebogens

Rückgabe: Fragebogenobjekt oder { error }.


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.


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.


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.


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.


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.


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
}

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 }


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.


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.


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.


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.

  1. 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 }

  2. Laden Sie die rohen QML-Bytes direkt nach upload_url hoch (ein HTTP-PUT, außerhalb des MCP-Tool-Aufrufs).

  3. finalize_upload(artifact_id, base_version_id) – speichert den hochgeladenen Inhalt genau so, wie save_qml_file ihn auf dieser Basis speichern würde: übernommen, mit einem neueren Speichervorgang zusammengeführt oder abgelehnt. base_version_id ist erforderlich und bedeutet dasselbe wie bei save_qml_file. Ein Wiederholen mit derselben artifact_id ist sicher: Nach einem Abschluss, der gespeichert oder mit overlap geantwortet hat, liefert eine Wiederholung die erste Antwort und schreibt nichts, gleich welche Basis sie nennt.

    Rückgabe: dieselbe Antwortstruktur wie bei save_qml_file

    Ein overlap verbraucht 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_unknown und head_kept_moving behalten das Handle, sodass ein korrigierter Aufruf denselben Upload speichert.


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": "..."
}

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
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

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 }.


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.


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.


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.


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.

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.

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.

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

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 }.


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"}

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.

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}"}