Insertion preview modal

Let the doctor review, curate, and edit a generated report inside the SDK before it reaches your application

The insertion preview is an in-SDK modal that lets the doctor review, curate, and edit a generated report before it is handed back to your application. When enabled, an arriving report opens a preview where each field can be selected, edited, or filled; the doctor then clicks Apply and your app receives the curated payload via the onReportApply callback.

This page explains how to enable, disable, and use it.

The same modal is reused to curate clinical actions (extras) — petitions, appointments, tests, referrals — through a parallel channel. There the gate is showInsertionPreview and the presence of templateExtras (instead of template), and on Apply the items go to handleExtras. See Clinical Actions (Extras).

How it fits into the flow

1. Recording → Stop

   After the doctor stops recording, a background auto-review drafts a report. The draft is not shown yet — it waits, exactly like the Generate button.

2. User clicks Generate (or Regenerate)

   The modal never opens on its own from the background auto-review. It mirrors the Generate button and waits for a user click. Every user-initiated result — including after a failed automatic generation — opens the modal.

3. Curate in the modal

   The insertion preview opens with the report fields. The doctor can select, edit, or fill each one. Mandatory fields block Apply until they are filled.

4. Apply → onReportApply(curated)

   On Apply, your app receives the curated payload — only the fields the doctor kept or edited — via onReportApply. Your app then inserts it into the EHR/HIS.

If the feature is disabled, an arriving report is passed straight through to your handleReport callback instead (legacy behavior) — the modal never renders.

Enabling the modal

The modal has two independent channels: one for reports and one for clinical actions (extras). Each is enabled only when its two conditions are true. Both share the same backend flag, but each has its own schema:

Channel	Backend flag	Required schema	Curated on Apply by
Reports	showInsertionPreview: true	template (or the deprecated toolsargs)	onReportApply
Extras	showInsertionPreview: true	templateExtras	handleExtras

reports enabled = showInsertionPreview (backend, per API key)  AND  template is present
extras enabled  = showInsertionPreview (backend, per API key)  AND  templateExtras is present

The showInsertionPreview flag is per API key and shared by both channels. The schemas are independent: you can enable the modal for reports only (template), extras only (templateExtras), or both.

Turn on the backend flag

The flag is per API key and lives in your Omniloy profile settings (showInsertionPreview). You cannot enable it from the frontend — contact [e-mail] to have it set for your key. Until it is true, the SDK ignores the modal entirely and falls back to handleReport.

Pass a template

The template is the JSON Schema that describes the report structure (the same schema used to generate the report). It must be present for the modal to open. See Clinical data schemas.

Disabling the modal (opting out)

The modal is off by default — it only appears when both enable conditions above are met. There is no special “off” switch: making either condition false disables it. You have two independent levers:

Lever	How	Effect
Backend flag	Leave showInsertionPreview as false for your API key (the default), or ask Omniloy to set it false.	Authoritative, per-API-key switch. Report generation still works; reports go straight to handleReport.
No template	Do not pass the template prop (nor the deprecated toolsargs).	Client-side opt-out. Caveat: the template also drives report generation — without it the Generate/Regenerate buttons are hidden too. Use this only if you don’t want report generation either.

When disabled, generated reports are delivered to your handleReport callback as before — no modal, no curation step. This is the legacy behavior.

Keep handleReport wired even when you enable the modal. It is the fallback path: if the backend flag is off (or you drop the template), your integration keeps receiving reports with zero code changes.

Common mistakes when enabling/disabling

There is no prop or HTML attribute that toggles the feature

A show-insertion-preview attribute appears in some demo code — it is a no-op: the SDK never reads it. The only enable/disable levers are the backend showInsertionPreview flag and the presence of template.

Omitting onReportApply does not disable the modal

If the feature is enabled, the modal still opens; on Apply it simply falls back to handleReport (and warns if neither is wired). To not show the modal, use one of the two levers above.

An empty template still counts as present

The gate only checks that template is truthy, so passing {} (or an object with no properties) can open a modal with no fields. Pass a real JSON Schema, or omit template entirely.

Using it

React

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

<Omniscribe
  apikey={API_KEY}
  userid={USER_ID}
  patientid={PATIENT_ID}
  // Required for the modal to render (JSON Schema of the report):
  template={REPORT_TEMPLATE}

  // Called when the doctor clicks Apply — receives the curated payload:
  onReportApply={(curated) => {
    // curated: Record<string, unknown> — only the fields the doctor kept/edited
    myEhr.insertNote(curated);
  }}

  // Fallback: used when the modal is disabled (backend flag off / no template):
  handleReport={(report) => {
    myEhr.insertNote(report);
  }}

  // Optional: scope your CSS to the modal (it lives in the SDK shadow DOM):
  insertionPreviewClassNames={{
    panel: 'my-preview-panel',
    applyButton: 'my-apply-btn',
  }}
/>

On the web component, template and insertionPreviewClassNames are JSON props and onReportApply/handleReport are function props — assign them as JS properties on the element, not as HTML attributes. Functions cannot be HTML attributes, and the template attribute is stripped from the DOM after it is read (it is sensitive data).

Props reference

Prop	Type	Purpose
template	JSON Schema (object)	Required to enable. Describes the report structure and per-field rules. Also drives report generation.
onReportApply	(curated: CuratedReport) => void	Fires when the doctor clicks Apply. Receives only the fields the doctor kept/edited.
handleReport	(report: object) => void	Fallback delivery when the modal is disabled. Keep it wired.
insertionPreviewClassNames	InsertionPreviewClassNames	Class-name overrides for the modal’s built-in classes.
toolsargs	JSON Schema (object)	Deprecated alias for template. Prefer template.

InsertionPreviewClassNames keys (all optional): backdrop, panel, header, body, footer, group, row, gapRow, applyButton, cancelButton.

The modal renders inside the SDK shadow DOM, so global page CSS won’t reach it. Use insertionPreviewClassNames to attach your own classes, then style them.

The CuratedReport and InsertionPreviewClassNames types are structural (Record<string, unknown> and a flat map of optional class-name strings) — type your handlers against those shapes directly.

What the doctor can do in the modal

• Select / deselect fields — only checked fields end up in the curated payload.
• Edit values inline (text, prose, number, boolean, date, enum, multi-enum, and arrays of objects).
• Fill gaps — empty fields the template expects are surfaced as gaps.
• Edit with voice — dictate to refine fields while the modal stays open.
• Apply — emits onReportApply(curated). Disabled while any mandatory gap is unfilled.
• Cancel — closes without emitting.

Template schema

The template is a standard JSON Schema object. Beyond the standard keywords, the modal understands:

• required (standard) — the agent should produce the field when it can.
• mandatory (custom keyword) — stronger than required: the doctor must review/fill it before Apply is allowed. Empty mandatory fields render as blocking gaps and disable Apply.
• Field kinds are inferred from the schema: string, prose (long text), number, boolean, date (via pattern), enum, multi-enum (array of enums), and array-of-objects (with optional oneOf + discriminator for per-row variants).

{
  "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 is a non-standard hint the SDK reads to gate Apply ("diagnosis" above blocks Apply until filled). Also instruct your generation prompt not to fabricate mandatory values — the doctor is expected to confirm them.

Quick checklist

• Backend flag showInsertionPreview is true for your API key (contact support to enable). Shared by both channels.
• For reports: you pass a template (JSON Schema), with onReportApply wired for the curated payload and handleReport as the fallback.
• For extras: you pass a templateExtras (JSON Schema), with handleExtras wired to receive the curated items. See Clinical Actions (Extras).
• (Optional) insertionPreviewClassNames set for host-side styling.

If the modal doesn’t appear on a Generate click, verify both enable conditions. With debug={true} the SDK logs the gate state: [InsertionPreview] gate { backend, templatePresent, isEnabled }.

Next steps

• Clinical data schemas — design the template and use the mandatory keyword
• Pre-fill from your EMR — feed existing form content into generation with updateTemplate
• Optional properties — full callback reference