Tovább a tartalomhoz
Tudástár

Kérdőív- és QML-eszközök – MCP-eszközreferencia

A kérdőíveszközök a QML életciklusát kezelik: új verziók mentését, a Z3 formális elemzésével végzett validációt, egy verzió közzétételét egy kampányhoz, a projektek közötti áthelyezést és a közzététel visszavonását. Az életciklusnak megkötései vannak – például a közzététel nem vonható vissza, amíg aktív kampányok hivatkoznak a kérdőívre.

Egy kérdőív QML-kódja az Askalot adatbázisában csak bővíthető verzióláncként él. Minden mentés új verziót ad hozzá, és a kérdőív aktuális verzióját (head) erre állítja; a korábbi verziókat a rendszer soha nem írja felül és nem törli.

A qml_name a kérdőív állandó címe, projects/{project_id}/questionnaires/{questionnaire_id}.qml alakban. Útvonalnak tűnik, és úgy is olvasható, de egy kérdőívet azonosít – nincs böngészhető könyvtár és nincs előkészítendő fájl. A list_qml_files a létező címeket adja vissza.

Ebből három szabály következik, és ezek magyarázzák az alábbi viselkedés nagy részét:

  • A mentés megnevezi azt a verziót, amelyből írták. A mentést egy pillanattal korábban kiolvasott tartalomból állítja össze, és közben valaki más is menthetett. Ezért a save_qml_file és a finalize_upload egy base_version_id paramétert vár: annak az olvasási vagy mentési válasznak a version_id értékét, amelyből a tartalma származik. Ha az aktuális verzió még mindig ez, a tartalma lesz az új aktuális verzió. Ha az aktuális verzió elmozdult, és a két módosítás különböző sorokat érint, a kettő összefésülése lesz az aktuális verzió. Ha mindkettő ugyanazokat a sorokat módosította, a rendszer semmit sem ír ki, a válasz pedig overlap.
  • A mentést a validáció soha nem akadályozza. Egy vázlatnak, egy beillesztett blokknak vagy egy félkész logikának is tárolhatónak kell lennie, ezért a mentés a létrejövő verzión feljegyzi a formális validáció ítéletét, a problémákat pedig warnings formájában adja vissza. Azon túl, hogy a cím nem olyan kérdőívre mutat, amelybe írhat, vagy hogy a bemeneti séma elutasítja a hívást, a rendszer csak a következő esetekben utasít el egy mentést: az alap nem a kérdőív egyik verziója (base_version_unknown), overlap, az aktuális verzió minden próbálkozás előtt elmozdult (head_kept_moving), a kérdőívet a mentés futása közben egy másik projektbe helyezték át (questionnaire_moved), lezárt szervezet (org_sealed), valamint 32 KB-nál nagyobb közvetlen tartalom.
  • A közzététel viszont elutasíthat. A publish_qml_file egy verziót rögzít egy kampányhoz, és ez az a pillanat, amikor a mérőeszköz eljut egy válaszadóhoz – ezért ez az egyetlen kapu, amely elutasítja a hibás kérdőívtervet. A rögzített verzió ezután az adott kampány teljes élettartama alatt megváltoztathatatlan.

Az összes kérdőív listázása, opcionálisan név szerint szűrve.

Paraméter Típus Kötelező Alapértelmezés Leírás
name string Nem — Kis- és nagybetűt nem megkülönböztető részszöveg-szűrő
limit integer Nem 100 A visszaadott találatok legnagyobb száma

Visszatérési érték: { items: [...], count, limit }


Kérdőív lekérdezése azonosító alapján.

Paraméter Típus Kötelező Alapértelmezés Leírás
questionnaire_id string Igen — A kérdőív UUID-ja

Visszatérési érték: a kérdőívobjektum vagy { error }.


Új kérdőív létrehozása QML-tartalomból vagy a sablonkönyvtár egyik sablonjából. A kérdőív és a QML-kódjának 1. verziója együtt jön létre, így kérdőív soha nem létezik tartalom nélkül.

Paraméter Típus Kötelező Alapértelmezés Leírás
name string content esetén a sablon neve Megjelenített név
content string A content / template egyike — A QML YAML, amelyet a rendszer 1. verzióként tárol
template string A content / template egyike — Egy sablon slugja a list_questionnaire_templates eredményéből; az 1. verzió bájtra pontosan a sablon language nyelvű QML-kódja
project_id string Igen — A szülőprojekt azonosítója
description string Nem — Szabad szöveges leírás
language string Nem "en"; template esetén az Öné Nyelvkód. template esetén az a nyelv, amelyen a sablont másolni kell: a könyvtár languages értékeinek egyike. Ha elhagyja, a saját nyelve (az Ön beállítása, ennek hiányában a szervezete alapértelmezése), ha a könyvtár kínálja, különben en
estimated_duration integer Nem — A kitöltés várható ideje percben

A content vagy a template paramétert adja meg, soha ne mindkettőt: ha mindkettőt vagy egyiket sem adja meg, a rendszer elutasítja a hívást, és semmit sem ír. Ismeretlen template slugra a válasz „nem található”, a könyvtár által nem kínált language értéket pedig a rendszer a kínált nyelvek felsorolásával utasítja el.

A sablonmásolat azon a nyelven készül, amelyen kiolvasták, és a könyvtár által kínált minden más nyelv az 1. verzió fordításaként érkezik vele, így a válaszadóknak fordítási lépés nélkül kínálhatók ezek a nyelvek.

Visszatérési érték: a létrehozott kérdőívobjektum, valamint az 1. verzió version_id és version_number értéke. A version_id az a base_version_id, amelyet e tartalom első mentésekor kell megadni.

A létrehozást a formális validáció nem akadályozza – a content szerkezetileg hibás is lehet. content esetén a rendszer az ítéletet az 1. verzióval együtt feljegyzi, de nem érvényesíti; helyességet csak a kampányhoz való közzététel követel meg. template esetén a validáció a létrehozás után néhány másodperccel a háttérben fut, ahogy egy mentés után is: addig a logic_validated értéke false.


A kérdőívsablon-könyvtár listázása: kész kérdőívek (kurzusértékelések, ügyfél-visszajelzések, eseményregisztráció, betegfelvétel és mások), kategóriákba csoportosítva. Egy slugot a create_questionnaire eszköznek template paraméterként adhat át.

Paraméter Típus Kötelező Alapértelmezés Leírás
language string Nem az Öné A könyvtár nyelve, amelyen a sablonokat listázni kell. Ha elhagyja, a saját nyelve (az Ön beállítása, ennek hiányában a szervezete alapértelmezése), ha a könyvtár kínálja, különben en. A könyvtár által nem kínált nyelvet a rendszer a kínált nyelvek felsorolásával utasítja el
category string Nem — Egy kategória slugja; az ismeretlent a rendszer a kategóriák listájával utasítja el
query string Nem — Szavak, amelyeknek mind elő kell fordulniuk egy sablon nevében vagy leírásában, kis- és nagybetűtől függetlenül
limit integer Nem 50 Oldalméret, 1 és 100 között
cursor string Nem — Az előző oldal next_cursor értéke

Visszatérési érték: { data: [{ slug, name, category, subcategory, description }], categories: [{ slug, name }], language, language_fallback, languages, total, next_cursor, has_more }. A nevek, leírások és kategóriák language nyelvűek; a languages a könyvtár által kínált összes nyelvet felsorolja, az en nyelvvel kezdve. A language_fallback értéke true, ha nem neveztek meg language értéket, és a könyvtár még nem kínálja az Ön nyelvét, így a válasz angol nyelvű: ezt közölje a felhasználóval. A total az összes illeszkedő sablont számolja; kövesse a next_cursor értéket, amíg a has_more igaz. QML-törzs nem szerepel a listában: hozza létre a kérdőívet egy slugból, majd olvassa ki a get_qml_content eszközzel.


Kérdőív logikai törlése (soft delete).

Paraméter Típus Kötelező Alapértelmezés Leírás
questionnaire_id string Igen — A kérdőív UUID-ja

Visszatérési érték: { success: true, questionnaire_id } vagy hiba.

A logikai törlés egy biztonsági másolatot tartalmazó sort szúr be; a restore_questionnaire (lásd alább) rövid ideig visszaállíthatja a kérdőívet.


Kérdőív átnevezése. Tisztán metaadat-módosítás – a kérdőív címe és QML-verziólánca változatlan marad, így a rá hivatkozó kampányok továbbra is működnek.

Paraméter Típus Kötelező Alapértelmezés Leírás
questionnaire_id string Igen — A kérdőív UUID-ja
name string Igen — Az új megjelenített név (legfeljebb 255 bájt)

Visszatérési érték: a frissített kérdőívobjektum.


Nemrég logikailag törölt kérdőív visszaállítása és a hivatkozásainak újrakapcsolása. A QML-verzióláncát a törlés nem érintette, így a visszaállított kérdőív pontosan azzal a verzióval tér vissza, amellyel rendelkezett.

Paraméter Típus Kötelező Alapértelmezés Leírás
questionnaire_id string Igen — A kérdőív UUID-ja

Visszatérési érték: a visszaállított kérdőívobjektum, vagy hiba, ha a visszaállítási időszak lejárt.


A szervezet QML-kérdőíveinek listázása. Nem igényel paramétert. Az egyes bejegyzések qml_name értéke bármely más QML-eszköznek átadható.

Visszatérési érték:

{
"items": [
{
"name": "3f9c2b10-....qml",
"qml_name": "projects/abc123/questionnaires/3f9c2b10-....qml",
"tier": "project",
"project_id": "abc123"
}
],
"count": 1
}

Gyors összefoglaló egy kérdőív aktuális verziójáról – az elemek száma és a metaadatok, a teljes tartalom nélkül.

Paraméter Típus Kötelező Alapértelmezés Leírás
qml_name string Igen — A kérdőív címe a list_qml_files eredményéből

Visszatérési érték: { success, qml_name, items_count, metadata }


Egy kérdőív aktuális verziójának egy elemét úgy jeleníti meg, ahogy a válaszadó látja. Az MCP Appseket megjelenítő gazdaalkalmazás (például a Claude) egy írásvédett panelt nyit meg az elem valódi vezérlőivel; minden más gazdaalkalmazás ugyanezt az elemet JSON-szövegként kapja meg.

Paraméter Típus Kötelező Alapértelmezés Leírás
qml_name string Igen — A kérdőív címe a list_qml_files eredményéből
item_id string Igen — Az elem id azonosítója

Visszatérési érték: az elem megjelenített mezői (id, kind, title, input, valamint questions, rows vagy columns, ha az elemnek vannak ilyenjei), a szövegében lévő jelölőkód megtisztításával. Az ismeretlen elem vagy cím eszközhibát eredményez.


Egy kérdőív aktuális verziójának nyers YAML-kódját adja vissza.

Paraméter Típus Kötelező Alapértelmezés Leírás
qml_name string Igen — A kérdőív címe

Visszatérési érték: { success, qml_name, content, size_bytes, version_id, version_number } legfeljebb 32 KB-os tartalom esetén. A version_id megnevezi, melyik verzió a content; adja át base_version_id paraméterként, amikor az ebből a válaszból írt tartalmat menti.

32 KB fölött a tartalom nem kerül közvetlenül a válaszba – ehelyett a válasz { success, qml_name, download_url, size_bytes, version_id, version_number, note }, ahol a download_url egy rövid életű (a lejáratáig újra felhasználható) link, amelyet közvetlenül HTTPS-en tölthet le (további hitelesítés nélkül). A link a version_id verziót szolgálja ki akkor is, ha azóta egy mentés elmozdította az aktuális verziót, így a bájtjai pontosan az a verzió, amelyet mentéskor base_version_id paraméterként megnevez. Ha a link lejárt, hívja meg újra a get_qml_content eszközt.


QML-tartalom mentése egy meglévő kérdőívbe, egy Ön által megnevezett verzióhoz képest. A mentést a hibás YAML vagy a sémasértés soha nem akadályozza – a rendszer a félkész, még nem érvényes piszkozatot is elmenti, a problémákat pedig a rendszer warnings listaként adja vissza az írás elutasítása helyett.

Paraméter Típus Kötelező Alapértelmezés Leírás
qml_name string Igen — Egy meglévő kérdőív címe
content string Igen — QML YAML-tartalom, legfeljebb 32 KB
base_version_id string Igen — Az a verzió, amelyből a tartalmat írták: az ehhez a kérdőívhez kapott legutóbbi get_qml_content, create_questionnaire vagy mentési válasz version_id értéke
project_id string Nem — Ha megadja, egyeznie kell a kérdőív projektjével; az eltérést a rendszer elutasítja, nem hagyja figyelmen kívül

Előbb olvasson, aztán mentsen. Hívja meg a get_qml_content eszközt, alkalmazza a módosítását a visszaadott tartalomra, és mentse a version_id értékével mint base_version_id. Mentés után a következő mentés azt a version_id értéket nevezi meg, amelyet az a mentés visszaadott, soha nem egy korábbit.

Visszatérési érték: { success, qml_name, questionnaire_id, version_id, version_number, created, merged, content_changed, bytes_written, logic_validated, content?, content_note?, warnings? }.

Mi történt A válaszban
Az alap még mindig az aktuális verzió volt created: true, merged: false. Az Ön tartalma az új aktuális verzió
Valaki közben mentett, más sorokon created: true, merged: true, content_changed: true. Az aktuális verzió mindkét módosítást tartalmazza, és a content hordozza: ez váltja fel az Ön példányát. A benne lévő, nem Ön által írt sorok a másik szerzőéi
Az Ön tartalma már az aktuális verzió created: false. A rendszer semmit sem ír ki
Az Ön tartalma megegyezik az alapjával, és az aktuális verzió elmozdult created: false, content_changed: true, az aktuális verzió content tartalmával

A content csak akkor szerepel, ha a tárolt tartalom 32 KB alatti; különben a content_note jelzi, hogy hívja meg a get_qml_content eszközt. A warnings hibátlan mentésnél hiányzik, a mentett, de nem tökéletes piszkozatnál pedig az elemzési, illetve sémaproblémák listája.

A semmit sem író mentés válasza { success: false, error, detail }:

error Jelentés Teendő
overlap Valaki közben mentett, és ugyanazokat a sorokat módosította. Hordozza a head_version_id, head_version_number és conflict_count mezőket Hívja meg a get_qml_content eszközt, alkalmazza a módosítását a visszaadott tartalomra, és mentse annak version_id értékével. Ne küldje el ugyanazt a tartalmat újra az újabb azonosítóval: ez felülírná a másik mentést
base_version_unknown A base_version_id üres, nem verzióazonosító, vagy nem ennek a kérdőívnek egy verziója Hívja meg a get_qml_content eszközt, és mentse a visszaadott version_id értékkel
head_kept_moving A kérdőívet mindhárom próbálkozás előtt újra mentették Olvassa ki újra, és próbálkozzon ismét
org_sealed A szervezet le van zárva Semmi sem írható
questionnaire_moved A kérdőívet a mentés futása közben egy másik projektbe helyezték át Kérje le a list_qml_files eszközzel az aktuális címét, olvassa ki a get_qml_content eszközzel, és mentse újra

A formális validáció a mentés után néhány másodperccel a háttérben fut azon a verzión, amely akkor az aktuális (az Öné vagy az összefésült), a rendszer pedig ezen a verzión jegyzi fel az ítéletét, így egy verzió helyessége később, további szerkesztések után is megállapítható marad. Addig a mentési válasz logic_validated értéke null, és a logic_validation_note ezt jelzi, a get_questionnaire pedig logic_validated: false értéket ad; az ítéletet akkor adja vissza, amikor megérkezik, a validate_qml_file pedig kérésre jelenti. Az a mentés, amely elrontja a korábban hibátlan kérdőívet, nem akadályozza az írást, de a kérdőívet nem validált állapotba váltja; a kampányhoz való közzétételét a rendszer a javításig elutasítja.

A rendszer elutasítja azt a címet, amely mögött nincs kérdőív – előbb hívja meg a create_questionnaire eszközt.

A 32 KB-nál nagyobb tartalmat a rendszer elutasítja a {"error": "content_too_large_for_inline_save"} válasszal, és semmit sem ír. A tartalom méretre vágása helyett használja a request_upload_url / finalize_upload párost (lásd alább).


Kétlépéses mechanizmus olyan QML-tartalom mentéséhez, amely túl nagy a save_qml_file 32 KB-os közvetlen korlátjához. Maga a tartalom soha nem jelenik meg eszközhívásban – kér egy feltöltési azonosítót, a bájtokat közvetlenül HTTPS-en tölti fel, majd véglegesít.

  1. request_upload_url(qml_name, project_id?) – rövid életű, egyszer használható, méretkorlátos feltöltési azonosítót hoz létre.

    Visszatérési érték: { upload_url, artifact_id, max_size_bytes, expires_in }

  2. Töltse fel a nyers QML-bájtokat közvetlenül az upload_url címre (egy HTTP PUT kéréssel, az MCP-eszközhíváson kívül).

  3. finalize_upload(artifact_id, base_version_id) – a feltöltött tartalmat pontosan úgy menti, ahogy a save_qml_file mentené az adott alapra: a rendszer létrehozza, összefésüli egy újabb mentéssel, vagy elutasítja. A base_version_id kötelező, és ugyanazt jelenti, mint a save_qml_file esetén. Ugyanazzal az artifact_id értékkel biztonságosan újrapróbálható: egy mentést végző vagy overlap választ adó véglegesítés után az újrapróbálás az első választ adja vissza, és semmit sem ír, bármilyen alapot nevez is meg.

    Visszatérési érték: ugyanaz a válaszszerkezet, mint a save_qml_file esetén

    Az overlap elhasználja a feltöltési azonosítót, mert a feltöltött bájtokat a régi verzióhoz képest írták: olvassa ki újra, alkalmazza ismét a módosítását, és töltse fel az eredményt egy új azonosítón keresztül. A base_version_unknown és a head_kept_moving megtartja az azonosítót, így egy javított hívás ugyanazt a feltöltést menti.


Z3 SMT formális validáció futtatása egy kérdőív aktuális verzióján. Minden elemre vonatkozóan elemzi az elérhetőséget, a konzisztenciát és az utófeltételek teljesíthetőségét.

Paraméter Típus Kötelező Alapértelmezés Leírás
qml_name string Igen — A kérdőív címe

Visszatérési érték:

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

Előfeltétel-állapotok (elérhető-e az elem?):

Állapot Jelentés
REACHABLE Az elem legalább egy kitöltési úton elérhető
NEVER Az elem elérhetetlen – halott kód
UNKNOWN Az elemzés nem tudta megállapítani az elérhetőséget

Utófeltétel-állapotok (teljesíthetők-e az elem feltételei?):

Állapot Jelentés
TAUTOLOGICAL A feltétel mindig igaz (redundáns)
CONTINGENT A feltétel a válaszoktól függ (normál)
INFEASIBLE A feltétel soha nem teljesíthető
UNKNOWN Az elemzés nem tudta megállapítani
Típus Súlyosság Leírás
unreachable_item error Az előfeltétel NEVER – halott elem
code_answered_item warning Egy codeBlock minden olyan kitöltésben, ahol a feltétele teljesül, még azelőtt eltárolja az elem válaszát, hogy a kitöltés elérné az elemet, így azt soha nem kérdezik meg. Ha az elemet fel kell tenni, helyezze a codeBlockot az elem után
infeasible_postcondition error Az utófeltétel soha nem teljesíthető
globally_false_postcondition error Az utófeltétel mindig hamis
tautological_postcondition warning Az utófeltétel mindig igaz (redundáns)
comment_titled_as_question warning Egy csak megjelenítésre szolgáló Comment címe kérésként van megfogalmazva, így megválaszolására szolgáló mező nélkül jelenik meg
roster_subject_not_answerable warning Egy Roster subjectFrom mezője olyan elemet nevez meg, amely soha nem szolgáltathat alanyt (hiányzik, a blokkon kívül van, vagy Comment)
none_unsafe_reference warning Egy feltétel olyan elemen végez rendezést vagy számítást, amelyet nem minden odavezető úton kérdeznek meg – az elem kimenete None, és a predikátum kivételt dob. A None értékkel való egyenlőségvizsgálat biztonságos, a validátor nem jelöli meg
inexact_condition warning Egy feltétel olyan elemet olvas, amely megválaszolatlan lehet egy olyan helyen, ahol a validátor nem tudja eldönteni, hogy a None olvasása meghiúsítja-e (egy not alatt, egy or utolsó előtti operandusában, vagy bárhol egy utófeltételben). Az ellentmondást továbbra is jelenti, de a feltétel mindig igaz voltát nem bizonyítja. Először vizsgálja meg, van-e válasz: előfeltételben q.outcome is not None and (…), utófeltételben q.outcome is None or (…)
uninitialized_read warning Egy feltétel vagy codeBlock olyan változót olvas, amelyet a válaszadó bármilyen értékadás lefutása előtt elérhet – a változó később, csak az egyik ágon, vagy olyan elemtől kap értéket, amelyet a saját feltétele átugorhat. Az olvasás kivételt dob: az előfeltétel átugorja az elemet, míg az utófeltétel ellenőrzés nélkül elfogadja a választ, a codeBlock pedig félúton leáll – mindkettő kizárja a kitöltést az adatkészletekből. Adjon alapértéket a codeInit blokkban, adjon értéket mindkét ágon, vagy lássa el az olvasót ugyanazzal a feltétellel, mint az értékadást
self_assignment warning Egy codeBlock-utasítás önmagának ad értéket (q.outcome = q.outcome) – semmit sem változtat, de származtatásnak tűnik
mandated_answer_postcondition warning Egy utófeltétel egy választó vezérlőnek csak egyetlen válaszát engedi meg, így a bármely más választ adó válaszadó nem tud továbblépni, és azt a választ a rendszer soha nem rögzíti. Ehelyett a válasz alapján ágaztassa el a kérdőívet
combinable_none_option warning Egy Checkbox „Egyik sem” típusú opciója együtt jelölhető azokkal az opciókkal, amelyeket kizár, és egyetlen utófeltétel sem tiltja ezt a kombinációt
questionnaire_level_condition warning Gyökérszintű precondition/postcondition kulcs. A rendszer a feltételeket csak elem- és blokkszinten értékeli ki, így ez soha nem fut le
language_not_judged warning A kérdőív nyelve a támogatott nyelveken kívül esik, így a szóalapú ellenőrzések nem futottak le: a comment_titled_as_question megfogalmazásra vonatkozó része (a Comment címében lévő ? jelet a validátor továbbra is ellenőrzi) és a combinable_none_option. Ezeket kézzel ellenőrizze
file_not_found error A cím mögött nincs kérdőív
validation_error error Kivétel az elemzés vagy a feldolgozás során

Tervezésiminőség-értékelőlap (D2–D8 dimenziók) számítása egy kérdőív aktuális verziójára. Akkor használja, miután a validate_qml_file nulla hibát jelentett – a validáció a logikai helyességet bizonyítja; ez a tervezés minőségét osztályozza (a mérőeszköz gazdaságossága, a minőségkapuk sűrűsége, az ellenőrzési lefedettség, a szerkezeti összetettség, a sorrend koherenciája, az utak változatossága és a teher kiegyensúlyozottsága). A minőségkapuk sűrűségét a kérdőív numerikus bevitelein méri a rendszer – azokon a válaszokon, amelyeket a válaszadó begépel vagy csúszkával ad meg, és ahol az utófeltétel olyan érvényességi határt ad hozzá, amelyet maga a vezérlő nem. A választó elemek kimaradnak ebből az arányból, mert a címkekészletük már rögzíti a választ; az egyik választást egy másikhoz kötő utófeltételt a rendszer külön, konzisztenciakapuként jelenti. Determinisztikus és tájékoztató jellegű: az osztályzatok soha nem befolyásolják az is_valid értéket vagy a közzétételt.

Paraméter Típus Kötelező Alapértelmezés Leírás
qml_name string Igen — A kérdőív címe

Visszatérési érték:

{
"dimensions": {
"instrument_economy": {
"id": "D2",
"grade": "strong",
"metrics": { },
"offenders": [{"item_id": "...", "detail": "..."}],
"truncated": false
}
},
"item_count": 12,
"notes": []
}

Az egyes dimenziók grade értéke strong, adequate, weak vagy not_applicable. Ismeretlen cím vagy sikertelen elemzés esetén a válasz { error }.


Kérdőív közzététele egy kampányhoz – a terepmunka kapuja, és ebben a referenciában az egyetlen eszköz, amely elutasítja a hibás kérdőívtervet.

Paraméter Típus Kötelező Alapértelmezés Leírás
questionnaire_id string Igen — A terepre viendő kérdőív UUID-ja
campaign_id string Igen — Annak a kampánynak az UUID-ja, amelyhez rögzíteni kell

A rendszer formálisan validálja a kérdőív aktuális verzióját, az ítéletet ezen a verzión jegyzi fel, és csak hibátlan ítélet esetén rögzíti a verziót a kampányhoz.

Visszatérési érték: { success, questionnaire_id, campaign_id, qml_version_id, logic_validated }

Elutasításkor: { error, issues } – az issues felsorolja a javítandó, hiba súlyosságú problémákat. A rendszer semmit sem rögzít, így a kampány továbbra is azt viszi terepre, amit addig.

A kampánynak már erre a kérdőívre kell hivatkoznia; ha egy másikat visz terepre, előbb kösse át az update_campaign_questionnaire eszközzel.


Kérdőív áthelyezése egy másik projektbe. A kérdőív azonosítója változatlan marad, és a verzióláncát sem érinti az áthelyezés, így a rá hivatkozó kampányok – a korábbi verzióhoz rögzítetteket is beleértve – továbbra is működnek. Az áthelyezés nem szerkesztés.

Paraméter Típus Kötelező Alapértelmezés Leírás
questionnaire_id string Igen — A kérdőív UUID-ja
target_project_id string Igen — A célprojekt UUID-ja

Visszatérési érték: { success, questionnaire_id, qml_name } – a qml_name az új cím.


Kérdőív visszavonása a projektjéből logikai törléssel. A QML-verziólánca megmarad – egy befejezett kampány még rögzítve lehet valamelyik verzióhoz, így a közzététel visszavonása eltávolítja a kérdőívet az Ön munkaanyagai közül anélkül, hogy kitörölné azt, amit terepre vittek. Nem hajtható végre, amíg a kérdőívnek aktív kampányai vannak.

Paraméter Típus Kötelező Alapértelmezés Leírás
questionnaire_id string Igen — A kérdőív UUID-ja

Visszatérési érték: { success, questionnaire_id } vagy hiba.


A fordítás egy adott kérdőívverzió mellett álló lefordított szöveg, nyelvenként egy. Csak a válaszadók számára látható szöveget cseréli le; az azonosítók, az opciókódok, a feltételek és a Z3-ítélet a forrásé marad. A válaszadóknak csak a teljes fordítást kínálja fel a rendszer. Fogalmak, befagyasztás és a válaszadói nyelvválasztó: Kérdőív fordítása.

Minden fordítási eszköz megnevezi a questionnaire_id értéket, a version_id értéket (azt a version_id értéket, amelyet a get_qml_content vagy egy mentés visszaadott), és – a lista kivételével – a locale értéket (en, es, fr, de vagy hu, soha nem a kérdőív saját forrásnyelve). Mindegyik először átviszi az előző verzió fordításait a megnevezett verzióra, így egy újonnan mentett verzió már tartalmaz minden olyan szöveget, amelynek a forrása nem változott.

A szövegkulcsok egy-egy, a válaszadó számára látható szöveget neveznek meg: questionnaire/title, block:<id>/title, item:<id>/title, item:<id>/labels/<code> (opciócímkék, kód szerint), item:<id>/rows/<n> és /columns/<n> (mátrix), item:<id>/questions/<n> (kérdéscsoport), item:<id>/left, /right, /on, /off, /placeholder, valamint .../postcondition/<n>/hint (a válasz elutasításakor megjelenő üzenet). Egy verzió pontos kulcsait a get_qml_translation source_texts mezőjéből olvashatja ki.

Egy verzió összes fordítása, nyelvenként.

Paraméter Típus Kötelező Alapértelmezés Leírás
questionnaire_id string Igen — A kérdőív UUID-ja
version_id string Igen — A kérdőív egyik verziója

Visszatérési érték: { questionnaire_id, version_id, source_language, translations: [{ locale, started, withdrawn, complete, untranslated, frozen, human_edited, updated_at }] }, a forrásnyelv kivételével minden támogatott nyelvhez egy bejegyzéssel, így a lista azokat a nyelveket is megnevezi, amelyeket még senki sem kezdett el (started: false, üresen hagyott untranslated mezővel: minden kulcs lefordítatlan, és a get_qml_translation felsorolja őket), valamint azokat, amelyek fordítását törölték (withdrawn: true). Az untranslated a még hiányzó szövegkulcsokat sorolja fel; a frozen azt jelenti, hogy egy kitöltést ezen a nyelven válaszoltak meg, így nem menthető és nem törölhető; a human_edited azt, hogy egy ember szerkesztette a szerkesztőben.

Egy nyelv fordítása az általa fordított forrással együtt.

Paraméter Típus Kötelező Alapértelmezés Leírás
questionnaire_id string Igen — A kérdőív UUID-ja
version_id string Igen — A kérdőív egyik verziója
locale string Igen — A célnyelv

Visszatérési érték: az adott nyelv listamezői, valamint a texts (kulcs → lefordított szöveg), a source_language és a source_texts (minden fordítható kulcs → a forrásszövege, dokumentumsorrendben). A még fordítás nélküli nyelv üres texts mezőt és updated_at: null értéket ad vissza.

Egy nyelv lefordított szövegének mentése. A mentés részleges: a rendszer a texts tartalmát ráfésüli a tárolt fordításra, és minden kihagyott kulcs megtartja a tárolt szövegét, így a hiánypótlás csak az untranslated listában szereplő kulcsokat küldi el.

Paraméter Típus Kötelező Alapértelmezés Leírás
questionnaire_id string Igen — A kérdőív UUID-ja
version_id string Igen — A kérdőív egyik verziója
locale string Igen — A célnyelv
texts object Igen — Szövegkulcs → lefordított szöveg
base_updated_at string | null Igen — Az olvasáskor kapott updated_at; null, ha az olvasás nem talált tárolt fordítást

Visszatérési érték: a tárolt fordítás (texts, complete, untranslated, frozen, human_edited, updated_at). A következő mentés az ebben kapott updated_at értéket nevezi meg. Az MCP-n vagy API-n keresztüli mentést a rendszer ügynök által írtként rögzíti, és soha nem jelöli meg a fordítást human_edited értékkel.

Elutasítás Jelentés Teendő
Érvénytelen kulcsok (hibás kérés, kulcsonként egy sor) Egy kulcs olyan elemet, blokkot vagy opciókódot nevez meg, amely a forrásból hiányzik, tartományon kívüli indexet, részlegesen elküldött pozicionális listát (rows, columns, questions, utófeltétel-tippek), nem szöveges értéket, vagy jelölőkódot, például <script> elemet tartalmaz Javítsa ki pontosan a megnevezett kulcsokat, majd mentse újra
translation_conflict (409) A fordítás az olvasás óta megváltozott, általában egy kutató szerkesztése miatt Olvassa ki újra a get_qml_translation eszközzel, alkalmazza ismét a módosítását, és mentse az új updated_at értékkel
translation_frozen (409) Ezen a verzión már megválaszoltak egy kitöltést ezen a nyelven Ne próbálkozzon újra. Mentsen új kérdőívverziót, fordítsa le azt, és állítsa át rá a kampányt
Forrásnyelv (hibás kérés) A nyelv a kérdőív saját nyelve Magát a QML-t szerkessze, vagy fordítson egy másik nyelvre
Nem található A verzió nem ennek a kérdőívnek egy verziója Olvassa ki a kérdőívet a get_qml_content eszközzel, és a visszaadott version_id értéket nevezze meg

Egy verzió egy nyelvi fordításának törlése. A befagyasztott fordítás törlését a rendszer elutasítja (translation_frozen), a fordítás nélküli nyelvre pedig a válasz „nem található”.

Paraméter Típus Kötelező Alapértelmezés Leírás
questionnaire_id string Igen — A kérdőív UUID-ja
version_id string Igen — A kérdőív egyik verziója
locale string Igen — A törlendő nyelv

Visszatérési érték: { questionnaire_id, version_id, locale, deleted: true }.


Helyzet Válasz
Közzététel visszavonása aktív kampányok mellett {"error": "Cannot unpublish: questionnaire has active campaign {campaign_id}"}
Hibás verzió közzététele {"error": "...", "issues": [...]} – a rendszer semmit sem rögzít
Közzététel olyan kampányhoz, amely egy másik kérdőívet visz terepre {"error": "Campaign {id} fields questionnaire {other}, not {id}. Use update_campaign_questionnaire to rebind it first."}
Már a célprojektben van {"error": "Questionnaire is already in this project"}

Minden eszköz kizárólag az Ön saját szervezetén belül keresi a kérdőíveket. Egy másik szervezethez tartozó cím megkülönböztethetetlen egy nem létezőtől, és a kérdőív saját projektjétől eltérő project_id értéket a rendszer elutasítja, nem hagyja csendben figyelmen kívül.

Helyzet Válasz
A kérdőív nem található {"error": "Questionnaire {id} not found"}
A szervezeti környezet nincs beállítva {"error": "Organization context not set"}
A cím mögött nincs kérdőív {"error": "QML document '{name}' not found for this organization"}
A mentés nem nevez meg használható alapot {"success": false, "error": "base_version_unknown", "detail": "..."}
A mentés ütközik egy újabb mentéssel {"success": false, "error": "overlap", "head_version_id": "...", "head_version_number": n, "conflict_count": n}
QML-elemzési hiba {"error": "Failed to parse QML: {details}"}