Modal de vista previa de inserción

La vista previa de inserción (insertion preview) es un modal interno del SDK que permite al médico revisar, curar y editar un informe generado antes de que se devuelva a tu aplicación. Cuando está activo, un informe entrante abre una vista previa donde cada campo puede seleccionarse, editarse o completarse; luego el médico hace clic en Aplicar y tu app recibe el payload curado a través del callback onReportApply. Esta página explica cómo activarlo, desactivarlo y usarlo.

El mismo modal se reutiliza para curar acciones clínicas (extras) — peticiones, citas, pruebas, derivaciones — por un canal paralelo. Ahí el gate es showInsertionPreview y la presencia de templateExtras (en lugar de template), y al Aplicar los items van a handleExtras. Ver Acciones clínicas (Extras).

Cómo encaja en el flujo

Grabación → Detener

Cuando el médico detiene la grabación, un auto-review en segundo plano borronea un informe. El borrador no se muestra todavía — espera, igual que el botón Generar.

El usuario hace clic en Generar (o Regenerar)

El modal nunca se abre solo desde el auto-review en segundo plano. Espeja el botón Generar y espera un clic del usuario. Todo resultado iniciado por el usuario —incluso tras una generación automática fallida— abre el modal.

Curar en el modal

La vista previa se abre con los campos del informe. El médico puede seleccionar, editar o completar cada uno. Los campos obligatorios bloquean Aplicar hasta que se completen.

Aplicar → onReportApply(curado)

Al hacer clic en Aplicar, tu app recibe el payload curado —solo los campos que el médico dejó o editó— vía onReportApply. Tu app lo inserta en el EHR/HIS.

Si la función está desactivada, un informe entrante pasa directo a tu callback handleReport (comportamiento legacy) — el modal no se renderiza.

El modal tiene dos canales independientes: uno para informes y otro para acciones clínicas (extras). Cada uno se activa solo cuando se cumplen sus dos condiciones. Ambos comparten el mismo flag de backend, pero cada uno tiene su propio esquema:

Canal	Flag de backend	Esquema requerido	Se cura al Aplicar por
Informes	`showInsertionPreview: true`	`template` (o la deprecada `toolsargs`)	`onReportApply`
Extras	`showInsertionPreview: true`	`templateExtras`	`handleExtras`

informes activos = showInsertionPreview (backend, por API key)  Y  template presente
extras activos   = showInsertionPreview (backend, por API key)  Y  templateExtras presente

El flag showInsertionPreview es por API key y común a ambos canales. Los esquemas son independientes: puedes activar el modal solo para informes (template), solo para extras (templateExtras), o para los dos.

Activar el flag de backend

El flag es por API key y vive en tus ajustes de perfil de Omniloy (showInsertionPreview). No puedes activarlo desde el frontend — contacta a support@omniloy.com para que lo activen para tu key. Hasta que sea true, el SDK ignora el modal por completo y cae en handleReport.

Pasar un template

El template es el JSON Schema que describe la estructura del informe (el mismo esquema usado para generarlo). Debe estar presente para que el modal se abra. Consulta Esquemas de datos clínicos. El modal está apagado por defecto — solo aparece cuando se cumplen ambas condiciones de activación de arriba. No hay un interruptor “off” especial: hacer que cualquiera de las condiciones sea falsa lo desactiva. Tienes dos palancas independientes:

Palanca	Cómo	Efecto
Flag de backend	Deja `showInsertionPreview` en `false` para tu API key (el default), o pide a Omniloy que lo ponga en `false`.	Interruptor autoritativo, por API key. La generación de informes sigue funcionando; los informes van directo a `handleReport`.
Sin `template`	No pases la prop `template` (ni la deprecada `toolsargs`).	Opt-out del lado del cliente. Ojo: el template también habilita la generación de informes — sin él, los botones Generar/Regenerar también quedan ocultos. Usa esto solo si tampoco quieres la generación de informes.

Cuando está desactivado, los informes generados se entregan a tu callback handleReport como antes — sin modal, sin paso de curación. Este es el comportamiento legacy.

Mantén handleReport cableado incluso cuando actives el modal. Es el camino de fallback: si el flag de backend está apagado (o quitas el template), tu integración sigue recibiendo informes sin cambiar una línea de código.

Errores comunes al activarlo/desactivarlo

No existe ninguna prop ni atributo HTML que active/desactive la función

En algún código de demo aparece un atributo show-insertion-preview — es un no-op: el SDK nunca lo lee. Las únicas palancas de activación/desactivación son el flag de backend showInsertionPreview y la presencia de template.

Un template vacío igual cuenta como presente

El gate solo verifica que template sea truthy, así que pasar {} (o un objeto sin properties) puede abrir un modal sin campos. Pasa un JSON Schema real, u omite template por completo.

Usarlo

import { Omniscribe } from '@omniloy/sofia-sdk/react';
import '@omniloy/sofia-sdk/react/index.css';

<Omniscribe
  apikey={API_KEY}
  userid={USER_ID}
  patientid={PATIENT_ID}
  // Requerido para que el modal se renderice (JSON Schema del informe):
  template={REPORT_TEMPLATE}

  // Se llama cuando el médico hace clic en Aplicar — recibe el payload curado:
  onReportApply={(curated) => {
    // curated: Record<string, unknown> — solo los campos que el médico dejó/editó
    myEhr.insertNote(curated);
  }}

  // Fallback: se usa cuando el modal está desactivado (flag off / sin template):
  handleReport={(report) => {
    myEhr.insertNote(report);
  }}

  // Opcional: acota tu CSS al modal (vive en el shadow DOM del SDK):
  insertionPreviewClassNames={{
    panel: 'my-preview-panel',
    applyButton: 'my-apply-btn',
  }}
/>

<sofia-sdk id="sofia" apikey="your-api-key" userid="doctor-123" patientid="patient-456"></sofia-sdk>

<script>
  const el = document.querySelector('#sofia');

  // Props JSON
  el.template = REPORT_TEMPLATE;
  el.insertionPreviewClassNames = { panel: 'my-preview-panel' };

  // Props de función (asigna como propiedades JS, nunca como atributos HTML)
  el.onReportApply = (curated) => myEhr.insertNote(curated);
  el.handleReport = (report) => myEhr.insertNote(report); // fallback
</script>

En el web component, template e insertionPreviewClassNames son props JSON y onReportApply/handleReport son props de función — asígnalas como propiedades JS del elemento, no como atributos HTML. Las funciones no pueden ir como atributos HTML, y el atributo template se elimina del DOM tras leerse (es un dato sensible).

Referencia de props

Prop	Tipo	Propósito
`template`	JSON Schema (`object`)	Requerido para activar. Describe la estructura del informe y las reglas por campo. También impulsa la generación de informes.
`onReportApply`	`(curated: CuratedReport) => void`	Se dispara cuando el médico hace clic en Aplicar. Recibe solo los campos que el médico dejó/editó.
`handleReport`	`(report: object) => void`	Entrega de fallback cuando el modal está desactivado. Mantenlo cableado.
`insertionPreviewClassNames`	`InsertionPreviewClassNames`	Overrides de class-name para las clases internas del modal.
`toolsargs`	JSON Schema (`object`)	Alias deprecado de `template`. Prefiere `template`.

Claves de InsertionPreviewClassNames (todas opcionales): backdrop, panel, header, body, footer, group, row, gapRow, applyButton, cancelButton.

El modal se renderiza dentro del shadow DOM del SDK, así que el CSS global de la página no lo alcanza. Usa insertionPreviewClassNames para adjuntar tus propias clases y luego estilarlas.

Los tipos CuratedReport e InsertionPreviewClassNames son estructurales (Record<string, unknown> y un mapa plano de strings de class-name opcionales) — tipa tus handlers contra esas formas directamente.

Seleccionar / deseleccionar campos — solo los campos tildados terminan en el payload curado.
Editar valores inline (texto, prosa, número, booleano, fecha, enum, multi-enum y arrays de objetos).
Completar huecos — los campos vacíos que el template espera se muestran como gaps.
Editar con voz — dictar para refinar campos mientras el modal permanece abierto.
Aplicar — emite onReportApply(curated). Deshabilitado mientras haya algún gap obligatorio sin completar.
Cancelar — cierra sin emitir.

Esquema del template

El template es un objeto JSON Schema estándar. Además de las palabras clave estándar, el modal entiende:

required (estándar) — el agente debería producir el campo cuando pueda.
mandatory (palabra clave personalizada) — más fuerte que required: el médico debe revisarlo/completarlo antes de permitir Aplicar. Los campos obligatorios vacíos se muestran como gaps bloqueantes y deshabilitan Aplicar.
Los tipos de campo se infieren del esquema: string, prose (texto largo), number, boolean, date (vía pattern), enum, multi-enum (array de enums) y array-of-objects (con oneOf + discriminator opcional para variantes por fila).

{
  "type": "object",
  "required": ["chief_complaint"],
  "properties": {
    "chief_complaint": { "type": "string" },
    "diagnosis":       { "type": "string", "mandatory": true },
    "follow_up_date":  { "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$" },
    "medications": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string" },
          "dose": { "type": "number" },
          "unit": { "type": "string", "enum": ["mg", "g", "mcg"] }
        }
      }
    }
  }
}

mandatory es una pista no estándar que el SDK lee para condicionar Aplicar ("diagnosis" arriba bloquea Aplicar hasta completarse). Además, instruye a tu prompt de generación a no inventar valores obligatorios — se espera que el médico los confirme.

Checklist rápido

El flag de backend showInsertionPreview está en true para tu API key (contacta a soporte para activarlo). Es común a ambos canales.
Para informes: pasas un template (JSON Schema), con onReportApply cableado para el payload curado y handleReport como fallback.
Para extras: pasas un templateExtras (JSON Schema), con handleExtras cableado para recibir los items curados. Ver Acciones clínicas (Extras).
(Opcional) insertionPreviewClassNames seteado para estilos del lado del host.

Si el modal no aparece al hacer clic en Generar, verifica ambas condiciones de activación. Con debug={true} el SDK loguea el estado del gate: [InsertionPreview] gate { backend, templatePresent, isEnabled }.

Próximos pasos

Esquemas de datos clínicos — diseña el template y usa la palabra clave mandatory
Pre-cargar desde tu EMR — alimenta contenido ya escrito en la generación con updateTemplate
Propiedades opcionales — referencia completa de callbacks

Instalación y Configuración

Integración por Framework

Funcionalidades

Soporte

Cómo encaja en el flujo

Activar el flag de backend

Pasar un template

Errores comunes al activarlo/desactivarlo

Usarlo

Referencia de props

Esquema del template

Checklist rápido

Próximos pasos

​Cómo encaja en el flujo

​Activar el modal

​Activar el flag de backend

​Pasar un template

​Desactivar el modal (opt-out)

​Errores comunes al activarlo/desactivarlo

​Usarlo

​Referencia de props

​Qué puede hacer el médico en el modal

​Esquema del template

​Checklist rápido

​Próximos pasos

Cómo encaja en el flujo

Activar el modal

Activar el flag de backend

Pasar un template

Desactivar el modal (opt-out)

Errores comunes al activarlo/desactivarlo

Usarlo

Referencia de props

Qué puede hacer el médico en el modal

Esquema del template

Checklist rápido

Próximos pasos