Ir al contenido
DevLab

Sesiones, inscripciones e interrupciones

Cómo se abre, se cierra, se abandona y se reinicia una captura, cómo responden los relojes de las posiciones y cómo se ofrecen las microintervenciones.

En esta página
  1. De la inscripción a los resultados
  2. Capturas abandonadas y reiniciadas
  3. Cuando una posición no está disponible
  4. Interrupciones y microintervenciones
  1. Crea el usuario (POST /users) e inscríbelo en un protocolo (POST /user-protocols). Una inscripción aún no tiene captura, y la misma persona puede inscribirse en el mismo protocolo más de una vez.
  2. Pregunta qué posición toca (GET /user-protocols/{userProtocolId}). Su protocol.interpreted dice si el protocolo se interpreta: con false, como en Measurement, las capturas solo dan indicadores, el stream anuncia results.ready en lugar de constellation.complete y POST /analyze responde 409 PROTOCOL_NOT_ANALYSED. GET /catalog/protocols y GET /catalog/protocol_group también lo traen. Hoy solo el Engine del entorno de pruebas devuelve interpreted.
  3. Envía el primer lote de esa posición: Engine abre una sesión para ella. No hay id de sesión que guardar: la identifica el par userProtocolId + protocolMechanicId.
  4. Cuando cada step tiene sus lotes y su Final, la sesión se completa y aparecen sus resultados.

Cada posición tiene como mucho una sesión abierta y una completada. Para medir otra vez la misma posición, vuelve a inscribir.

  • Una sesión que no recibe ningún lote durante unos minutos se abandona (el umbral es un ajuste del entorno), y el stream en vivo lo avisa con session.abandoned.
  • Un lote que llega tarde responde entonces 409 SESSION_ABANDONED. Reinicia desde step: 1 con kpnfile.order: 1. El mensaje te dice el umbral del entorno donde se capturó este ejemplo:
JSON
{
"status": 409,
"body": {
"code": 409,
"reason": "SESSION_ABANDONED",
"message": "Session abandoned after 300s of inactivity. This mechanic must be restarted from the beginning.",
"restartRequired": true,
"expected": {
"step": 1,
"kpnfile": {
"order": 1,
"status": "Partial"
}
}
}
}
  • Cada intento lleva su captureId. Un lote de reinicio (step: 1, kpnfile.order: 1) con un captureId nuevo cierra el intento que estaba abierto y empieza este; cualquier otro lote con un captureId distinto del del intento abierto responde 409 SESSION_ABANDONED: es un lote tardío de un intento que ya sustituiste.
  • Una posición que ya tiene una captura completada responde 409 POSITION_ALREADY_COMPLETED a cualquier lote nuevo:
JSON
{
"status": 409,
"body": {
"code": 409,
"reason": "POSITION_ALREADY_COMPLETED",
"message": "This mechanic already has a completed session."
}
}
  • Para abandonar una captura a propósito: POST /user-protocols/{userProtocolId}/{protocolMechanicId}/cancel. Es idempotente: sin nada abierto responde 200 con cancelled: false y reason: "no_open_session". Con ?captureId= cierra la captura abierta solo si es esa; si hay otra abierta, no toca nada y responde 200 con cancelled: false y reason: "other_capture_open". Sin captureId, cierra lo que esté abierto; con un token de captura (POST /token/capture), sin captureId se usa el del token, así que solo puede cerrar esa captura. cancelled: false con reason: null quiere decir que la captura se cerró sola en ese mismo momento (caducó o terminó): ya no queda nada que cancelar. Hoy solo el Engine del entorno de pruebas acepta captureId.
  • Mientras otro intento retiene la posición (una captura en curso o una grabación pendiente de enviar), uno nuevo responde 409 POSITION_RESERVED. Grabar ahora y enviar los frames después (captureId, deferred y capturedAt en POST …/context) se describe en la referencia de la API. El aviso de fin de una grabación que ya se canceló, o que se rechazó por fuera de orden (recordingEndedAt sin capturedAt), responde 409 CAPTURE_CANCELLED: no reserva nada, así que no reintentes.
  • GET /user-protocols/{userProtocolId}/{protocolMechanicId}/sessions lista los intentos de una posición, del más antiguo al más reciente, con su status y su captureId. deferred: true marca una grabación retenida para procesarse después, y receivingPackets: true un intento que ya recibió al menos un lote: un intento diferido con receivingPackets: false es una reserva que aún espera sus frames. Son los mismos dos campos que el holder de un 409 POSITION_RESERVED. Hoy solo el Engine del entorno de pruebas los devuelve.

Engine declara los relojes de las posiciones (ver Protocolos) y los comprueba al abrir una sesión, nunca a mitad de ella. Que un fallo rechace la captura o solo quede registrado depende del entorno; cuando la rechaza, la respuesta es un 409:

reason Qué hacer
MECHANIC_NOT_YET_AVAILABLE Reintenta en earliestAt
MECHANIC_EXPIRED Esa ventana se cerró para siempre: sigue con goTo
MUST_START_AT_FIRST_POSITION Empieza por la posición de goTo

rule nombra el reloj (date_window, time_of_day, spacing, start_order, start_weekday): úsalo en los logs, no para decidir qué hacer. spacing también puede venir de la separación mínima que Engine mantiene entre dos capturas del mismo protocolo, aunque la posición no declare ninguna.

¿Cuándo se abre una posición? En GET /user-protocols/{userProtocolId} cada sesión pendiente lleva un window. Con hasTiming: true y un reloj de franja horaria o de separación, from y to pueden llegar null, y no hay un earliestAt como el del 409. Los datos para calcularlo sí llegan: window.prevCaptureAt (cuándo empezó la captura anterior) y window.requiredGapSeconds (la separación que pide Engine). La posición se abre en prevCaptureAt más requiredGapSeconds; si alguno es null, no hay separación que esperar.

Sin calcularlo. En el Engine del entorno de pruebas, nextSessions de GET /user-protocols/{userProtocolId}/health y de GET /users/{externalId}/status da a cada sesión pendiente un window.earliestAt: la misma hora que el earliestAt del 409 MECHANIC_NOT_YET_AVAILABLE, y null si se puede capturar ya o ya no se podrá. En las mismas respuestas, lastCompletedAt dice cuándo empezó la última captura completada (cuándo se grabó, en una grabación), no cuándo acabó.

¿Sin datos o aún procesando? GET /results/{userProtocolId}/{protocolMechanicId} devuelve lo mismo en los dos casos: 200 con rawResults y aggResults vacíos, porque la posición aún no tiene sesión o su captura no se ha completado. Para distinguirlos, lee GET …/sessions de la posición: sessions: [] significa que no se ha enviado nada; un intento con su status significa que va en camino. GET /users/{externalId}/status da el estado del protocolo entero (capturing, awaiting_processing…).

Tras una captura completada, un contexto puede ofrecer una microintervención: una mecánica corta, como un ejercicio de respiración, que no es una posición del protocolo. La oferta es una interrupción, anclada a la captura que la disparó.

  1. Te enteras por el stream en vivo (interruption.offered) o con GET /user-protocols/{userProtocolId}/interruptions?status=offered.
  2. GET /interruptions/{interruptionId} devuelve qué mostrar: steps e instrucciones, con la misma forma que una posición.
  3. Captúrala con POST /interruptions/{interruptionId}/process-kpn-emo. Una oferta que no se empieza caduca.
  4. GET /results/interruption/{interruptionId} devuelve los resultados de la captura que disparó la oferta, en origen (la API escribe esta clave en español), y los de la microintervención, en micro (null si no se hizo).
  5. Para abandonar una microintervención en curso: POST /interruptions/{interruptionId}/cancel. Es idempotente: si no hay nada abierto responde 200 con cancelled: false.

De una oferta, apóyate en interruptionId, origin y message. observedValues, trigger y kpnWindow son internos: no te apoyes en ellos. Que un contexto ofrezca microintervenciones depende de los contextos de tu organización.