> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  Extras and reports are independent channels. Use `template` + `handleReport`, `templateExtras` + `handleExtras`, or both at once.
</Info>

## 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.

```typescript theme={null}
handleExtras: (extras: Extra[]) => void   //  Extra = Record<string, unknown>
```

Called when a category button is clicked —and, if the [insertion preview modal](/sofia/en/sdk/insertion-preview) 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:

```jsonc theme={null}
{
  "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

<Steps>
  <Step title="The buttons appear">
    When `templateExtras` is set, a transcript exists, and `handleExtras` is wired. They do not depend on the report contents.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Review or direct delivery">
    With the [insertion preview modal](/sofia/en/sdk/insertion-preview) active, the items open in the modal for the doctor to review and curate. Otherwise, they pass straight to `handleExtras`.
  </Step>
</Steps>

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.

<Info>
  PII is anonymized before it leaves and restored in the response, like everywhere else in the SDK ([patient data](/sofia/en/sdk/patient-data)). Items are extracted in the session language.
</Info>

## 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:

```typescript theme={null}
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

<CodeGroup>
  ```tsx React theme={null}
  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));
    }}
  />
  ```

  ```html Web Component theme={null}
  <sofia-sdk id="sofia" apikey="your-api-key" userid="doctor-123" patientid="patient-456"></sofia-sdk>

  <script>
    customElements.whenDefined('sofia-sdk').then(() => {
      const el = document.getElementById('sofia');

      // JSON prop — camelCase JS property (HTML attribute: template-extras)
      el.templateExtras = {
        type: 'object',
        properties: {
          peticiones: { type: 'array', items: { type: 'object',
            properties: { type: { type: 'string' }, description: { type: 'string' } } } },
          citas: { type: 'array', items: { type: 'object',
            properties: { type: { type: 'string' }, description: { type: 'string' } } } },
        },
      };

      // Function prop — JS property only
      el.handleExtras = (extras) => extras.forEach(sendToHis);
    });
  </script>
  ```
</CodeGroup>

<Tip>
  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.
</Tip>

## 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](/sofia/en/sdk/insertion-preview)** — let the doctor curate the items before they reach your app
* **[Clinical data schemas](/sofia/en/sdk/templates)** — how to design the JSON Schema
* **[Optional properties](/sofia/en/sdk/optional-properties)** — full callbacks reference