Herramientas de cuestionarios y QML — Referencia de herramientas MCP
Las herramientas de cuestionarios gestionan el ciclo de vida de QML: guardar nuevas versiones, validar con el análisis formal de Z3, publicar una versión en una campaña, trasladar entre proyectos y retirar la publicación. El ciclo de vida impone restricciones; por ejemplo, la retirada se bloquea si alguna campaña activa hace referencia al cuestionario.
Cómo se almacena el QML
Sección titulada «Cómo se almacena el QML»El QML de un cuestionario reside en la base de datos de Askalot como una cadena de versiones a la que solo se añade (append-only). Cada guardado añade una nueva versión y mueve a ella la cabeza (head) del cuestionario; las versiones anteriores nunca se sobrescriben ni se eliminan.
qml_name es la dirección estable del cuestionario, con la forma projects/{project_id}/questionnaires/{questionnaire_id}.qml. Parece una ruta y se lee como tal, pero identifica un cuestionario: no hay ningún directorio que explorar ni ningún archivo que preparar. list_qml_files devuelve las direcciones que existen.
De ello se derivan tres reglas, que explican la mayor parte del comportamiento descrito a continuación:
- Un guardado nombra la versión a partir de la que se escribió. Usted compone un guardado a partir del contenido que leyó hace un momento, y puede que otra persona haya guardado desde entonces. Por eso
save_qml_fileyfinalize_uploadrecibenbase_version_id, elversion_idde la respuesta de lectura o de guardado de la que procede su contenido. Si la cabeza sigue siendo esa versión, su contenido pasa a ser la nueva cabeza. Si se movió y los dos cambios afectan a líneas distintas, la combinación de ambos pasa a ser la cabeza. Si ambos cambiaron las mismas líneas, no se escribe nada y la respuesta esoverlap. - Guardar nunca se bloquea por la validación. Un borrador, un bloque pegado o una lógica a medio terminar deben poder almacenarse, así que un guardado registra el veredicto de la validación formal en la versión que se guarda y devuelve los problemas como
warnings. Aparte de una dirección que no corresponde a ningún cuestionario en el que usted pueda escribir y de una llamada que el esquema de entrada rechaza, un guardado solo se rechaza por: una base que no es una versión del cuestionario (base_version_unknown), unoverlap, una cabeza que se movió antes de cada intento (head_kept_moving), un cuestionario trasladado a otro proyecto mientras se ejecutaba el guardado (questionnaire_moved), una organización sellada (org_sealed) y un contenido de más de 32 KB enviado dentro de la propia llamada. - Publicar sí rechaza.
publish_qml_filefija una versión en una campaña, que es el momento en que el instrumento llega a un encuestado; por eso es la única vía que rechaza un diseño no sólido. La versión fijada es inmutable durante toda la vida de esa campaña.
list_questionnaires
Sección titulada «list_questionnaires»Lista todos los cuestionarios, opcionalmente filtrados por nombre.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
name |
string |
No | — | Filtro por subcadena, sin distinguir mayúsculas y minúsculas |
limit |
integer |
No | 100 |
Número máximo de resultados que se devuelven |
Devuelve: { items: [...], count, limit }
get_questionnaire
Sección titulada «get_questionnaire»Obtiene un cuestionario por su ID.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | UUID del cuestionario |
Devuelve: el objeto del cuestionario o { error }.
create_questionnaire
Sección titulada «create_questionnaire»Crea un cuestionario nuevo a partir de contenido QML o de una plantilla de la biblioteca. El cuestionario y la versión 1 de su QML se crean a la vez, de modo que un cuestionario nunca existe sin contenido.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
name |
string |
Con content |
el nombre de la plantilla | Nombre visible |
content |
string |
Uno de content / template |
— | El YAML de QML, guardado como versión 1 |
template |
string |
Uno de content / template |
— | Un slug de plantilla de list_questionnaire_templates; la versión 1 es el QML de esa plantilla en language, byte a byte |
project_id |
string |
Sí | — | ID del proyecto padre |
description |
string |
No | — | Descripción en texto libre |
language |
string |
No | "en"; con template, el suyo |
Código de idioma. Con template, el idioma en el que se copia la plantilla: uno de los languages de la biblioteca. Si se omite, su propio idioma (su configuración o, en su defecto, el predeterminado de su organización) cuando la biblioteca lo ofrece; si no, en |
estimated_duration |
integer |
No | — | Tiempo previsto para completarlo, en minutos |
Indique content o template, nunca ambos: si se indican los dos o ninguno, la llamada se rechaza y no se escribe nada. Un slug de template desconocido se responde como no encontrado, y un language que la biblioteca no ofrece se rechaza indicando los que sí ofrece.
Una copia de plantilla se escribe en el idioma en el que se leyó, y cada uno de los demás idiomas que ofrece la biblioteca la acompaña como traducción de la versión 1, de modo que pueden ofrecerse esos idiomas a los encuestados sin un paso de traducción.
Devuelve: el objeto del cuestionario creado, más version_id y version_number de la versión 1. version_id es el base_version_id para un primer guardado de ese contenido.
La creación no depende de la validación formal: content puede estar estructuralmente roto. A partir de content, el veredicto se registra con la versión 1, sin imponerse; lo que exige solidez es publicar en una campaña. A partir de una template, la validación se ejecuta en segundo plano unos segundos después de la creación, igual que tras un guardado: hasta entonces logic_validated vale false.
list_questionnaire_templates
Sección titulada «list_questionnaire_templates»Lista la biblioteca de plantillas de cuestionarios: cuestionarios ya preparados (evaluaciones de cursos, opinión de clientes, inscripción a eventos, admisión de pacientes y más), agrupados en categorías. Pase un slug a create_questionnaire como template.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
language |
string |
No | el suyo | El idioma de la biblioteca en el que se listan las plantillas. Si se omite, su propio idioma (su configuración o, en su defecto, el predeterminado de su organización) cuando la biblioteca lo ofrece; si no, en. Un idioma que la biblioteca no ofrece se rechaza indicando los que sí ofrece |
category |
string |
No | — | Un slug de categoría; uno desconocido se rechaza con la lista de categorías |
query |
string |
No | — | Palabras que deben aparecer todas en el nombre o la descripción de una plantilla, sin distinguir mayúsculas y minúsculas |
limit |
integer |
No | 50 |
Tamaño de página, de 1 a 100 |
cursor |
string |
No | — | El next_cursor de la página anterior |
Devuelve: { data: [{ slug, name, category, subcategory, description }], categories: [{ slug, name }], language, language_fallback, languages, total, next_cursor, has_more }. Los nombres, las descripciones y las categorías están en language; languages lista todos los idiomas que ofrece la biblioteca, con en en primer lugar. language_fallback es true cuando no se indicó ningún language y la biblioteca aún no ofrece el suyo, de modo que la respuesta está en inglés: comuníqueselo al usuario. total cuenta todas las plantillas coincidentes; siga next_cursor mientras has_more sea true. No se lista ningún cuerpo QML: cree a partir de un slug y luego lea el cuestionario con get_qml_content.
delete_questionnaire
Sección titulada «delete_questionnaire»Elimina lógicamente un cuestionario.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | UUID del cuestionario |
Devuelve: { success: true, questionnaire_id } o un error.
La eliminación lógica inserta un registro de copia de seguridad; restore_questionnaire (más abajo) puede recuperar el cuestionario durante un breve período.
rename_questionnaire
Sección titulada «rename_questionnaire»Cambia el nombre de un cuestionario. Es una simple actualización de metadatos: la dirección del cuestionario y su cadena de versiones QML no cambian, de modo que las campañas que hacen referencia a él siguen funcionando.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | UUID del cuestionario |
name |
string |
Sí | — | Nuevo nombre visible (máx. 255 bytes) |
Devuelve: el objeto del cuestionario actualizado.
restore_questionnaire
Sección titulada «restore_questionnaire»Restaura un cuestionario eliminado lógicamente hace poco y vuelve a vincular sus referencias. La eliminación nunca tocó su cadena de versiones QML, así que el cuestionario restaurado vuelve exactamente con la versión que tenía.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | UUID del cuestionario |
Devuelve: el objeto del cuestionario restaurado, o un error si ha vencido el plazo de restauración.
list_qml_files
Sección titulada «list_qml_files»Lista los cuestionarios QML de la organización. No requiere parámetros. El qml_name de cada entrada puede pasarse a cualquier otra herramienta QML.
Devuelve:
{ "items": [ { "name": "3f9c2b10-....qml", "qml_name": "projects/abc123/questionnaires/3f9c2b10-....qml", "tier": "project", "project_id": "abc123" } ], "count": 1}inspect_qml_file
Sección titulada «inspect_qml_file»Obtiene un resumen rápido de la versión actual de un cuestionario: número de ítems y metadatos, sin el contenido completo.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
qml_name |
string |
Sí | — | Dirección del cuestionario obtenida de list_qml_files |
Devuelve: { success, qml_name, items_count, metadata }
preview_qml_item
Sección titulada «preview_qml_item»Muestra un ítem de la versión actual de un cuestionario tal como lo ve un encuestado. Un host que renderiza MCP Apps (como Claude) abre un panel de solo lectura con los controles reales del ítem; cualquier otro host recibe el mismo ítem como texto JSON.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
qml_name |
string |
Sí | — | Dirección del cuestionario obtenida de list_qml_files |
item_id |
string |
Sí | — | El id del ítem |
Devuelve: los campos renderizados del ítem (id, kind, title, input y questions, rows o columns cuando el ítem los tiene), con cualquier marcado de su texto saneado. Un ítem o una dirección desconocidos producen un error de la herramienta.
get_qml_content
Sección titulada «get_qml_content»Recupera el YAML sin procesar de la versión actual de un cuestionario.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
qml_name |
string |
Sí | — | Dirección del cuestionario |
Devuelve: { success, qml_name, content, size_bytes, version_id, version_number } para contenido de hasta 32 KB. version_id nombra la versión que es content; páselo como base_version_id cuando guarde contenido escrito a partir de esta respuesta.
Por encima de 32 KB, el contenido no se incluye en la propia respuesta: la respuesta es { success, qml_name, download_url, size_bytes, version_id, version_number, note }, donde download_url es un enlace de corta duración (reutilizable hasta que caduque) que se descarga directamente por HTTPS (sin necesidad de más autenticación). El enlace sirve version_id aunque un guardado haya movido la cabeza desde que lo solicitó, de modo que sus bytes son la versión que usted indica como base_version_id al guardar. Vuelva a llamar a get_qml_content si el enlace ha caducado.
save_qml_file
Sección titulada «save_qml_file»Guarda contenido QML en un cuestionario existente, escrito a partir de una versión que usted indica. Guardar nunca se bloquea por un YAML roto o por infracciones del esquema: un borrador en curso, todavía no válido, se guarda igualmente, y los problemas se devuelven como una lista warnings en lugar de rechazar la escritura.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
qml_name |
string |
Sí | — | Dirección de un cuestionario existente |
content |
string |
Sí | — | Contenido YAML de QML, de hasta 32 KB |
base_version_id |
string |
Sí | — | La versión a partir de la que se escribió el contenido: el version_id de su respuesta más reciente de get_qml_content, create_questionnaire o de guardado para este cuestionario |
project_id |
string |
No | — | Si se indica, debe coincidir con el proyecto del cuestionario; una discrepancia se rechaza en lugar de ignorarse |
Primero lea, luego guarde. Llame a get_qml_content, aplique su cambio al contenido que devuelve y guarde con su version_id como base_version_id. Tras un guardado, el siguiente guardado indica el version_id que devolvió ese guardado, nunca uno anterior.
Devuelve: { success, qml_name, questionnaire_id, version_id, version_number, created, merged, content_changed, bytes_written, logic_validated, content?, content_note?, warnings? }.
| Qué ocurrió | En la respuesta |
|---|---|
| La base seguía siendo la cabeza | created: true, merged: false. Su contenido es la nueva cabeza |
| Alguien guardó entretanto, en otras líneas | created: true, merged: true, content_changed: true. La cabeza contiene ambos cambios y content la incluye: sustituye a su copia. Las líneas que usted no escribió son del otro autor |
| Su contenido ya es la cabeza | created: false. No se escribe nada |
| Su contenido es igual a su base y la cabeza se movió | created: false, content_changed: true, con el content de la cabeza |
content se incluye solo cuando el contenido guardado ocupa menos de 32 KB; en caso contrario, content_note indica que se llame a get_qml_content. warnings no aparece en un guardado limpio, o es una lista de problemas de análisis o de esquema en un borrador guardado pero imperfecto.
Un guardado que no escribe nada responde { success: false, error, detail }:
error |
Significado | Qué hacer |
|---|---|---|
overlap |
Alguien guardó entretanto y cambió las mismas líneas. Incluye head_version_id, head_version_number, conflict_count |
Llame a get_qml_content, aplique su cambio a lo que devuelve y guarde con su version_id. No vuelva a enviar el mismo contenido con el id más reciente: eso reemplazaría el otro guardado |
base_version_unknown |
base_version_id está en blanco, no es un id de versión o no es una versión de este cuestionario |
Llame a get_qml_content y guarde con el version_id que devuelve |
head_kept_moving |
El cuestionario se volvió a guardar antes de cada uno de los tres intentos | Vuelva a leer y reintente |
org_sealed |
La organización está sellada | No puede escribirse nada |
questionnaire_moved |
El cuestionario se trasladó a otro proyecto mientras se ejecutaba el guardado | Llame a list_qml_files para obtener su dirección actual, léalo con get_qml_content y vuelva a guardar |
La validación formal se ejecuta en segundo plano, unos segundos después del guardado, sobre la versión que sea entonces la cabeza (la suya o la combinación), y su veredicto se registra en esa versión, de modo que la solidez de una versión sigue pudiendo consultarse más tarde, incluso tras nuevas ediciones. Hasta entonces, el logic_validated de la respuesta de guardado es null y logic_validation_note lo indica, y get_questionnaire da logic_validated: false; responde con el veredicto en cuanto llega, y validate_qml_file lo devuelve cuando se le solicita. Un guardado que introduce una regresión pasa el cuestionario a no validado sin bloquear la escritura; su publicación en una campaña se rechaza hasta que se corrija.
Se rechaza una dirección que no corresponde a ningún cuestionario: llame primero a create_questionnaire.
El contenido de más de 32 KB se rechaza con {"error": "content_too_large_for_inline_save"} y no se escribe nada. Use request_upload_url / finalize_upload (más abajo) en lugar de recortar el contenido para que quepa.
request_upload_url / finalize_upload
Sección titulada «request_upload_url / finalize_upload»Un mecanismo en dos pasos para guardar contenido QML demasiado grande para el límite de 32 KB que save_qml_file admite dentro de la propia llamada. El contenido nunca aparece en una llamada a herramienta: usted solicita un identificador de subida, sube los bytes directamente por HTTPS y luego finaliza.
-
request_upload_url(qml_name, project_id?): genera un identificador de subida de corta duración, de un solo uso y con tamaño limitado.Devuelve:
{ upload_url, artifact_id, max_size_bytes, expires_in } -
Suba los bytes QML sin procesar directamente a
upload_url(unPUTHTTP, fuera de la llamada a la herramienta MCP). -
finalize_upload(artifact_id, base_version_id): guarda el contenido subido exactamente como lo guardaríasave_qml_filesobre esa base: guardado, combinado con un guardado más reciente o rechazado.base_version_ides obligatorio y significa lo mismo que ensave_qml_file. Puede reintentarse sin riesgo con el mismoartifact_id: tras una finalización que guardó, o que respondióoverlap, un reintento devuelve la primera respuesta y no escribe nada, sea cual sea la base que indique.Devuelve: la misma estructura que
save_qml_fileUn
overlapconsume el identificador, porque los bytes subidos se escribieron a partir de la versión antigua: vuelva a leer, vuelva a aplicar su cambio y suba el resultado con un identificador nuevo.base_version_unknownyhead_kept_movingconservan el identificador, de modo que una llamada corregida guarda la misma carga.
validate_qml_file
Sección titulada «validate_qml_file»Ejecuta la validación formal SMT de Z3 sobre la versión actual de un cuestionario. Analiza la alcanzabilidad, la coherencia y la satisfacibilidad de las poscondiciones de cada ítem.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
qml_name |
string |
Sí | — | Dirección del cuestionario |
Devuelve:
{ "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": "..."}Referencia de clasificaciones
Sección titulada «Referencia de clasificaciones»Estados de precondición (¿puede alcanzarse el ítem?):
| Estado | Significado |
|---|---|
REACHABLE |
El ítem puede alcanzarse en al menos una ruta del flujo |
NEVER |
El ítem es inalcanzable: código muerto |
UNKNOWN |
El análisis no pudo determinar la alcanzabilidad |
Estados de poscondición (¿pueden satisfacerse las condiciones del ítem?):
| Estado | Significado |
|---|---|
TAUTOLOGICAL |
La condición siempre es verdadera (redundante) |
CONTINGENT |
La condición depende de las respuestas (normal) |
INFEASIBLE |
La condición nunca puede satisfacerse |
UNKNOWN |
El análisis no pudo determinarlo |
Tipos de problemas
Sección titulada «Tipos de problemas»| Tipo | Gravedad | Descripción |
|---|---|---|
unreachable_item |
error | La precondición es NEVER: ítem muerto |
code_answered_item |
warning | Un codeBlock guarda la respuesta del ítem antes de que el recorrido llegue a él en todos los recorridos en los que se cumple su condición de acceso, de modo que nunca se pregunta. Mueva el codeBlock después del ítem si debe preguntarse |
infeasible_postcondition |
error | La poscondición nunca puede satisfacerse |
globally_false_postcondition |
error | La poscondición siempre es falsa |
tautological_postcondition |
warning | La poscondición siempre es verdadera (redundante) |
comment_titled_as_question |
warning | Un Comment solo de visualización tiene como título una petición, por lo que se muestra sin ningún campo para responderla |
roster_subject_not_answerable |
warning | El subjectFrom de un Roster nombra un ítem que nunca puede proporcionar un sujeto (inexistente, fuera del bloque o un Comment) |
none_unsafe_reference |
warning | Una condición hace una comparación de orden o un cálculo con un ítem que no se pregunta en todas las rutas que llegan a ella: el resultado de ese ítem es None y el predicado lanza una excepción. La igualdad con None es segura y no se señala |
inexact_condition |
warning | Una condición lee un ítem que puede quedar sin responder en un lugar donde el validador no puede saber si leer None la hace fallar (bajo not, en un operando de or que no sea el último, o en cualquier parte de una poscondición). Una contradicción se sigue informando, pero no se demuestra que la condición sea siempre verdadera. Compruebe primero que hay respuesta: q.outcome is not None and (…) en una precondición, q.outcome is None or (…) en una poscondición |
uninitialized_read |
warning | Una condición o un codeBlock lee una variable a la que un encuestado puede llegar antes de que se haya ejecutado ninguna asignación: se asigna más tarde, solo en una rama, o en un ítem que su propia condición de acceso puede omitir. La lectura lanza una excepción: una precondición omite el ítem, mientras que una poscondición acepta la respuesta sin comprobarla y un codeBlock se detiene a medias, y ambas cosas excluyen la encuesta de los conjuntos de datos. Asigne un valor predeterminado en codeInit, asigne en ambas ramas o condicione la lectura igual que la asignación |
self_assignment |
warning | Una sentencia de un codeBlock asigna un valor a sí mismo (q.outcome = q.outcome): no cambia nada, pero parece una derivación |
mandated_answer_postcondition |
warning | Una poscondición solo admite una respuesta de un control de elección, de modo que un encuestado que dé cualquier otra respuesta no puede avanzar y esa respuesta nunca se registra. En su lugar, bifurque el flujo según la respuesta |
combinable_none_option |
warning | Una opción de Checkbox del tipo “None of the above” («Ninguna de las anteriores») puede marcarse junto con las opciones que niega, y ninguna poscondición rechaza esa combinación |
questionnaire_level_condition |
warning | Una clave precondition/postcondition en el nivel raíz. Las condiciones solo se evalúan en el nivel de ítem y de bloque, así que esta nunca se ejecuta |
language_not_judged |
warning | El idioma del cuestionario está fuera de los idiomas admitidos, así que no se ejecutaron las comprobaciones basadas en palabras: la parte de redacción de comment_titled_as_question (un ? en el título de un Comment se sigue comprobando) y combinable_none_option. Revíselas a mano |
file_not_found |
error | La dirección no corresponde a ningún cuestionario |
validation_error |
error | Excepción durante el análisis sintáctico o el análisis |
qml_quality_report
Sección titulada «qml_quality_report»Calcula un cuadro de puntuación de calidad del diseño (dimensiones D2–D8) para la versión actual de un cuestionario. Úselo después de que validate_qml_file no devuelva ningún error: la validación demuestra la solidez lógica; esto evalúa la calidad del diseño (economía del instrumento, densidad de controles de calidad, cobertura de verificación, complejidad estructural, coherencia del orden, diversidad de rutas y equilibrio de la carga). La densidad de controles de calidad se mide sobre las entradas numéricas del cuestionario, las respuestas que un encuestado escribe o ajusta con un control deslizante, en las que una poscondición añade un límite de validez que el propio control no impone. Los ítems de elección se excluyen de esa tasa, porque su conjunto de etiquetas ya fija la respuesta; una poscondición que vincula una elección con otra se indica por separado como control de coherencia. Es determinista y orientativo: las notas nunca afectan a is_valid ni a la publicación.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
qml_name |
string |
Sí | — | Dirección del cuestionario |
Devuelve:
{ "dimensions": { "instrument_economy": { "id": "D2", "grade": "strong", "metrics": { }, "offenders": [{"item_id": "...", "detail": "..."}], "truncated": false } }, "item_count": 12, "notes": []}El grade de cada dimensión es strong, adequate, weak o not_applicable. Una dirección desconocida o un fallo del análisis devuelve { error }.
publish_qml_file
Sección titulada «publish_qml_file»Publica un cuestionario en una campaña: la vía al trabajo de campo y la única herramienta de esta referencia que rechaza un diseño no sólido.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | UUID del cuestionario que se lleva a campo |
campaign_id |
string |
Sí | — | UUID de la campaña en la que se fija |
La versión actual del cuestionario se valida formalmente, el veredicto se registra en esa versión y solo un veredicto limpio la fija en la campaña.
Devuelve: { success, questionnaire_id, campaign_id, qml_version_id, logic_validated }
En caso de rechazo: { error, issues }; issues lista los problemas de gravedad error que hay que corregir. No se fija nada, así que la campaña sigue en campo con lo que tuviera.
La campaña ya debe hacer referencia a este cuestionario; si lleva a campo otro distinto, vuelva a vincularla primero con update_campaign_questionnaire.
move_qml_to_project
Sección titulada «move_qml_to_project»Traslada un cuestionario a otro proyecto. El ID del cuestionario no cambia y su cadena de versiones queda intacta, de modo que las campañas que hacen referencia a él —incluidas las fijadas en una versión anterior— siguen funcionando. Un traslado no es una edición.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | UUID del cuestionario |
target_project_id |
string |
Sí | — | UUID del proyecto de destino |
Devuelve: { success, questionnaire_id, qml_name }; qml_name es la nueva dirección.
unpublish_qml_file
Sección titulada «unpublish_qml_file»Retira un cuestionario de su proyecto eliminándolo lógicamente. Su cadena de versiones QML se conserva —una campaña completada puede seguir fijada en una de esas versiones—, de modo que la retirada saca el cuestionario de su conjunto de trabajo sin borrar lo que se llevó a campo. Se bloquea si el cuestionario tiene campañas activas.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | UUID del cuestionario |
Devuelve: { success, questionnaire_id } o un error.
Traducciones
Sección titulada «Traducciones»Una traducción es texto traducido junto a una versión de un cuestionario, una por idioma. Solo sustituye el texto visible para el encuestado; los ids, los códigos de opción, las condiciones y el veredicto de Z3 siguen siendo los del original. Solo se ofrece a los encuestados una traducción completa. Conceptos, congelación y el selector del encuestado: Traducir un cuestionario.
Cada herramienta de traducción indica questionnaire_id, version_id (el version_id que respondió get_qml_content o un guardado) y, salvo la de listado, locale (en, es, fr, de o hu, nunca el idioma de origen del propio cuestionario). Cada una traslada primero las traducciones de la versión anterior a la versión indicada, de modo que una versión recién guardada ya contiene cada texto cuyo original no cambió.
Las claves de texto nombran un texto visible para el encuestado: questionnaire/title, block:<id>/title, item:<id>/title, item:<id>/labels/<code> (etiquetas de opción, por código), item:<id>/rows/<n> y /columns/<n> (matriz), item:<id>/questions/<n> (grupo de preguntas), item:<id>/left, /right, /on, /off, /placeholder y .../postcondition/<n>/hint (el mensaje que se muestra cuando se rechaza una respuesta). Consulte las claves exactas de una versión en source_texts de get_qml_translation.
list_qml_translations
Sección titulada «list_qml_translations»Todas las traducciones de una versión, por idioma.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | UUID del cuestionario |
version_id |
string |
Sí | — | Una versión de ese cuestionario |
Devuelve: { questionnaire_id, version_id, source_language, translations: [{ locale, started, withdrawn, complete, untranslated, frozen, human_edited, updated_at }] }, con una entrada por cada idioma admitido excepto el de origen, de modo que la lista también nombra los idiomas que nadie ha empezado (started: false, con untranslated vacío: lo están todas las claves, y get_qml_translation las lista) y aquellos cuya traducción se eliminó (withdrawn: true). untranslated lista las claves de texto que aún faltan; frozen significa que se respondió una encuesta en ese idioma, por lo que no admite guardados ni eliminaciones; human_edited significa que una persona la editó en el editor.
get_qml_translation
Sección titulada «get_qml_translation»La traducción de un idioma, con el original que traduce.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | UUID del cuestionario |
version_id |
string |
Sí | — | Una versión de ese cuestionario |
locale |
string |
Sí | — | Idioma de destino |
Devuelve: los campos del listado para ese idioma más texts (clave → texto traducido), source_language y source_texts (cada clave traducible → su texto original, en el orden del documento). Un idioma que aún no tiene traducción responde con texts vacío y updated_at: null.
save_qml_translation
Sección titulada «save_qml_translation»Guarda texto traducido para un idioma. El guardado es parcial: texts se combina sobre la traducción guardada, y cada clave que usted omita conserva su texto guardado, de modo que para completar huecos basta con enviar las claves que figuran en untranslated.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | UUID del cuestionario |
version_id |
string |
Sí | — | Una versión de ese cuestionario |
locale |
string |
Sí | — | Idioma de destino |
texts |
object |
Sí | — | Clave de texto → texto traducido |
base_updated_at |
string | null |
Sí | — | El updated_at que respondió su lectura; null cuando no respondió ninguna traducción guardada |
Devuelve: la traducción guardada (texts, complete, untranslated, frozen, human_edited, updated_at). Un guardado posterior indica el updated_at que respondió este. Un guardado por MCP o por la API se registra como escrito por un agente y nunca marca la traducción como human_edited.
| Rechazo | Significado | Qué hacer |
|---|---|---|
| Claves no válidas (solicitud incorrecta, una línea por clave) | Una clave nombra un ítem, un bloque o un código de opción que el original no tiene, un índice fuera de rango, una lista posicional (rows, columns, questions, indicaciones de poscondición) enviada en parte, un valor que no es texto, o marcado como <script> |
Corrija exactamente las claves indicadas y vuelva a guardar |
translation_conflict (409) |
La traducción cambió desde que la leyó, normalmente por una edición de un investigador | Vuelva a leer con get_qml_translation, vuelva a aplicar su cambio y guarde con el nuevo updated_at |
translation_frozen (409) |
Se ha respondido una encuesta en este idioma con esta versión | No reintente. Guarde una nueva versión del cuestionario, tradúzcala allí y pase la campaña a ella |
| Idioma de origen (solicitud incorrecta) | El idioma es el del propio cuestionario | Edite el propio QML o traduzca a otro idioma |
| No encontrado | La versión no es una versión de este cuestionario | Lea el cuestionario con get_qml_content e indique el version_id que responde |
delete_qml_translation
Sección titulada «delete_qml_translation»Elimina la traducción de un idioma para una versión. Una traducción congelada se rechaza (translation_frozen), y un idioma sin traducción devuelve un error de no encontrado.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | UUID del cuestionario |
version_id |
string |
Sí | — | Una versión de ese cuestionario |
locale |
string |
Sí | — | Idioma que se elimina |
Devuelve: { questionnaire_id, version_id, locale, deleted: true }.
Gestión de errores
Sección titulada «Gestión de errores»Restricciones del ciclo de vida de QML
Sección titulada «Restricciones del ciclo de vida de QML»| Situación | Respuesta |
|---|---|
| Retirar con campañas activas | {"error": "Cannot unpublish: questionnaire has active campaign {campaign_id}"} |
| Publicar una versión no sólida | {"error": "...", "issues": [...]}: no se fija nada |
| Publicar en una campaña que lleva a campo otro cuestionario | {"error": "Campaign {id} fields questionnaire {other}, not {id}. Use update_campaign_questionnaire to rebind it first."} |
| Ya está en el proyecto de destino | {"error": "Questionnaire is already in this project"} |
Todas las herramientas resuelven los cuestionarios solo dentro de su propia organización. Una dirección que pertenece a otra organización es indistinguible de una que no existe, y un project_id que no coincide con el proyecto del propio cuestionario se rechaza en lugar de ignorarse en silencio.
Errores comunes
Sección titulada «Errores comunes»| Situación | Respuesta |
|---|---|
| Cuestionario no encontrado | {"error": "Questionnaire {id} not found"} |
| Contexto de organización no establecido | {"error": "Organization context not set"} |
| La dirección no corresponde a ningún cuestionario | {"error": "QML document '{name}' not found for this organization"} |
| El guardado no indica ninguna base utilizable | {"success": false, "error": "base_version_unknown", "detail": "..."} |
| El guardado se solapa con un guardado más reciente | {"success": false, "error": "overlap", "head_version_id": "...", "head_version_number": n, "conflict_count": n} |
| Error de análisis de QML | {"error": "Failed to parse QML: {details}"} |