Clinical Actions (Extras)

Extract the actions that come out of a visit —petitions, appointments, tests, referrals— and deliver them to your HIS by category

Extras are a second output channel alongside the report. Where handleReport hands you the clinical note, extras hand you the actions that come out of the visit —petitions, appointments, tests, referrals— ready for your HIS to execute.

Your schema defines the system. You declare the categories in the templateExtras prop and the SDK shows one button per category. On click, SofIA extracts only that category from the transcript and hands you the items exactly as they came out of your schema, with no field renaming or transformation. You decide the shape of each item in the schema.

Extras and reports are independent channels. Use template + handleReport, templateExtras + handleExtras, or both at once.

The two props

Property	Type	How to set
templateExtras	object (JSON Schema)	el.templateExtras JS property. As a web-component attribute: template-extras
handleExtras	function	JS property only (el.handleExtras = fn)

Both follow the same convention as handleReport: camelCase JS property, kebab-case HTML attribute. In React the prop is templateExtras; on the web component you assign el.templateExtras or the template-extras attribute (which is scrubbed from the DOM after it is read, being sensitive data). handleExtras is a callback: JS property only, no HTML attribute.

handleExtras: (extras: Extra[]) => void   //  Extra = Record<string, unknown>

Called when a category button is clicked —and, if the insertion preview modal is active, after Apply—. Receives the array of items for that category, with no normalization layer in between.

From schema to buttons

The top-level properties of templateExtras are the categories. Each one renders a button:

{
  "type": "object",
  "properties": {
    "peticiones":   { "type": "array", "items": { /* { type, description } */ } },
    "citas":        { "type": "array", "items": { /* ... */ } },
    "pruebas":      { "type": "array", "items": { /* ... */ } },
    "derivaciones": { "type": "array", "items": { /* ... */ } }
  }
}

The first two categories render inline; the rest sit behind a three-dots menu (…). Each button’s label is translated when the key exists in the active language; otherwise the capitalized property name is shown, so any category you define renders. Built-in translations ship for peticiones (Petitions), citas (Appointments), pruebas (Tests), and derivaciones (Referrals).

The flow

1. The buttons appear

   When templateExtras is set, a transcript exists, and handleExtras is wired. They do not depend on the report contents.

2. The doctor clicks a category

   The SDK extracts that category on demand: it builds a sub-schema with that single property and sends it to the extraction API. Only one category runs at a time; the button shows “Generating…” meanwhile.

3. Review or direct delivery

   With the insertion preview modal active, the items open in the modal for the doctor to review and curate. Otherwise, they pass straight to handleExtras.

The modal is the same one that curates reports, on a parallel channel: it activates when the showInsertionPreview flag (per API key) is true and templateExtras is present. With the gate on, handleExtras receives the items on Apply; with the gate off, it receives them directly. Extraction never touches the clinical note.

PII is anonymized before it leaves and restored in the response, like everywhere else in the SDK (patient data). Items are extracted in the session language.

Your schema defines the fields

The SDK delivers the items exactly as they came out of your templateExtras, mapping and renaming nothing. With a schema whose items are { type, description }, you receive:

handleExtras([
  { type: '3', description: 'Solicitar TAC con contraste.' },
  { type: '1', description: 'Solicitar analítica completa.' },
  { type: '2', description: 'Revisión dentro de un mes.' },
]);

Read the field you defined (here type) to route each action to its endpoint. If you need a different shape, change the schema —don’t add a conversion layer in your integration.

Using it

React

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

const EXTRAS_TEMPLATE = {
  type: 'object',
  properties: {
    peticiones: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          type: { type: 'string', description: 'Petition type code' },
          description: { type: 'string', description: 'Petition text' },
        },
      },
    },
    citas: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          type: { type: 'string' },
          description: { type: 'string' },
        },
      },
    },
  },
};

<Omniscribe
  apikey={API_KEY}
  userid={USER_ID}
  patientid={PATIENT_ID}
  templateExtras={EXTRAS_TEMPLATE}
  handleExtras={(extras) => {
    extras.forEach((item) => myHis.dispatchAction(item.type, item.description));
  }}
/>

For large schemas, assign the prop as a JS property (templateExtras in React, el.templateExtras on the web component) rather than an inline HTML attribute, to avoid JSON escaping issues.

Props reference

Prop	Type	Purpose
templateExtras	JSON Schema (object)	Defines the categories (one property, one button). Required to enable extras. On the web component the attribute is template-extras.
handleExtras	(extras: Extra[]) => void	Receives the items of the clicked category, untransformed. Extra = Record<string, unknown>.

The buttons appear only when all three line up: templateExtras with at least one category, a transcript in progress, and handleExtras wired.

Next steps

• Insertion preview modal — let the doctor curate the items before they reach your app
• Clinical data schemas — how to design the JSON Schema
• Optional properties — full callbacks reference