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

# Optional Properties

> Additional settings to customize the SofIA SDK

These properties allow you to customize the behavior and appearance of the SofIA SDK component to fit the specific needs of your implementation.

## Active Properties

### Interface Control

| Property   | Type      | Default Value | Description                                                                                                                                    |
| ---------- | --------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **isopen** | `boolean` | `true`        | Component visibility state, allows bidirectional control of the open/closed state. When not provided, the component starts **open** by default |

### Callbacks

| Property             | Type       | Description                                                                                                                                                                                                 |
| -------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **handleReport**     | `function` | Callback that receives the structured clinical report generated by SofIA. Assign it as a JS property on the element (`el.handleReport = fn`) — it is **not** delivered via an HTML attribute or a DOM event |
| **setIsOpen**        | `function` | Callback function to handle visibility changes requested by the component                                                                                                                                   |
| **setGetLastReport** | `function` | A callback that receives a function to retrieve the last generated report                                                                                                                                   |
| **onReportApply**    | `function` | Receives the curated report when the doctor clicks **Apply** in the [insertion preview modal](/sofia/en/sdk/insertion-preview). Falls back to `handleReport` when the modal is disabled                     |
| **updateTemplate**   | `function` | Returns the doctor's existing EMR field content so generation integrates it. See [Pre-fill from your EMR](/sofia/en/sdk/update-template)                                                                    |
| **handleExtras**     | `function` | Receives the clinical actions (petitions, appointments, tests…) extracted from the transcript, pass-through. See [Clinical Actions (Extras)](/sofia/en/sdk/extras)                                          |

### Callback Signatures

**handleReport**

```typescript theme={null}
handleReport: (report: Record<string, unknown>) => void
```

Called when the user triggers report generation. The `report` object matches the structure defined in your `template` JSON Schema. Example payload:

```json theme={null}
{
  "diagnosis": "Type 2 Diabetes Mellitus",
  "treatment_plan": "Metformin 500mg twice daily"
}
```

**setIsOpen**

```typescript theme={null}
setIsOpen: (isOpen: boolean) => void
```

Called when the SDK requests a visibility change (e.g., user clicks the close button).

**setGetLastReport**

```typescript theme={null}
setGetLastReport: (getter: () => Promise<Record<string, unknown> | undefined>) => void
```

Called once during initialization. Provides a function you can store and call later to retrieve the last generated report for the current patient/user session.

**handleExtras**

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

Called when the user clicks an extras category button (petitions, appointments, tests, referrals…). Receives the array of items for that category, delivered **exactly as the model extracted it** against your `templateExtras` schema — the SDK does not rename or transform fields. The shape of each item is defined by your schema. Pairs with the `templateExtras` prop. See [Clinical Actions (Extras)](/sofia/en/sdk/extras).

### Contextual Data

| Property           | Type                        | Default Value | Description                                                                                                                                                                                                                                                                         |
| ------------------ | --------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **patientdata**    | `string` (JSON) \| `object` | `undefined`   | Contextual patient information (background, previous notes, referrals) to enrich clinical processing                                                                                                                                                                                |
| **templateExtras** | `string` (JSON) \| `object` | `undefined`   | JSON Schema whose top-level properties are the action categories. Each property renders a button that extracts that category from the transcript. JS property `el.templateExtras`; web-component attribute `template-extras`. See [Clinical Actions (Extras)](/sofia/en/sdk/extras) |

### Report curation and EMR pre-fill

These props power two report features. See their dedicated guides for the full flow.

| Property                       | Type       | Description                                                                                                                                                                                                                                      |
| ------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **onReportApply**              | `function` | Fires when the doctor clicks **Apply** in the [insertion preview modal](/sofia/en/sdk/insertion-preview). Receives only the fields the doctor kept/edited                                                                                        |
| **insertionPreviewClassNames** | `object`   | Class-name overrides to style the [insertion preview modal](/sofia/en/sdk/insertion-preview) (which lives in the SDK shadow DOM). Keys: `backdrop`, `panel`, `header`, `body`, `footer`, `group`, `row`, `gapRow`, `applyButton`, `cancelButton` |
| **updateTemplate**             | `function` | Returns the doctor's existing EMR field content, keyed by template property id, so generated notes integrate what is already documented. See [Pre-fill from your EMR](/sofia/en/sdk/update-template)                                             |

### Consent Indicator

The consent status indicator in the header is **not** a component property. It is enabled through your Omniloy account/profile settings (contact [support@omniloy.com](mailto:support@omniloy.com) to turn it on). When enabled, the indicator reflects the `signedConsent` field you provide inside `patientdata` (see [Patient Data](/sofia/en/sdk/patient-data)).

### Localization

| Property     | Type     | Default Value | Description                                                              |
| ------------ | -------- | ------------- | ------------------------------------------------------------------------ |
| **language** | `string` | `"es"`        | Interface language. Supported values: `"es"` (Spanish), `"en"` (English) |

<Info>
  The default language is `"es"` (Spanish). If your application targets English-speaking users, set `language="en"` explicitly.
</Info>

### Analytics context

| Property                 | Type     | Default Value | Description                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------ | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **usermedicalspecialty** | `string` | `undefined`   | The doctor's medical specialty (e.g. `"cardiology"`). Purely descriptive — it does **not** change SDK behavior. When set, it is attached to every analytics event (as `user_medical_specialty`) so usage can be segmented by specialty. Passed through verbatim, with no normalization. Works both as a React prop and as a web-component attribute/property |

<Warning>
  **Breaking change (v1.0.9).** `usermedicalspecialty` replaces the camelCase `userMedicalSpecialty` that shipped in v1.0.8. The old name is no longer read: a host still passing it gets **no error**, but the value is silently dropped and events lose the specialty. Rename to the all-lowercase `usermedicalspecialty`, matching the other string props (`userid`, `patientid`, `templateid`).
</Warning>

### Debugging

| Property  | Type      | Default Value | Description                                     |
| --------- | --------- | ------------- | ----------------------------------------------- |
| **debug** | `boolean` | `false`       | Enables detailed logging for debugging purposes |

## CSS Customization

SofIA SDK renders as a Web Component with Shadow DOM. This prevents style conflicts with the host application, but it also means the application's global CSS does not directly affect internal SDK elements.

If you need to adjust specific internal styles, inject a `<style>` tag into the component `shadowRoot` after the Web Component has been defined and mounted:

```javascript theme={null}
async function setupSofIACustomStyles(selector = '#sofia') {
  await customElements.whenDefined('sofia-sdk');
  const sofia = await waitForSofiaComponent(selector);

  const customStyles = `
    :host {
      --sofia-custom-spacing: 12px;
    }

    .omniscribe_chat-view-stick-to-bottom-content {
      font-size: 14px;
    }
  `;

  const existingStyle = sofia.shadowRoot.querySelector('style[data-sofia-custom]');
  const styleTag = existingStyle || document.createElement('style');

  styleTag.setAttribute('data-sofia-custom', 'true');
  styleTag.textContent = customStyles;

  if (!existingStyle) {
    sofia.shadowRoot.appendChild(styleTag);
  }
}

function waitForSofiaComponent(selector) {
  return new Promise((resolve, reject) => {
    let attempts = 0;
    const maxAttempts = 40;

    function check() {
      const sofia = document.querySelector(selector);

      if (sofia?.shadowRoot) {
        resolve(sofia);
        return;
      }

      attempts += 1;
      if (attempts >= maxAttempts) {
        reject(new Error('SofIA is not mounted or has no shadowRoot available'));
        return;
      }

      setTimeout(check, 100);
    }

    check();
  });
}

setupSofIACustomStyles('#sofia').catch((error) => {
  console.warn('Could not apply SofIA custom styles:', error);
});
```

Use the selector that matches your component, for example `#sofia` or `#sofia-component`. In Angular, run this logic in `ngAfterViewInit`. In AngularJS, call it after configuring the component attributes and callbacks. If the component is mounted conditionally, run the function again after mounting it.

<Warning>
  Internal class selectors can change between SDK versions. The selector above matches `@omniloy/sofia-sdk` 1.0.4. Keep these styles centralized, test the interface when updating `@omniloy/sofia-sdk`, and prefer documented component properties when they are available.
</Warning>

## Manual Report Retrieval

In addition to receiving the report automatically, you can request it on-demand from your application.

The `set-get-last-report` property executes a callback that provides you with an asynchronous function. You should store this reference to use it whenever you need to retrieve the last generated report.

```javascript theme={null}
let getLastReportFn = null;

// Callback assigned to: set-get-last-report
function registerGetter(fn) {
  getLastReportFn = fn;
}

// Example of use in an external button
async function handleSaveClick() {
  if (getLastReportFn) {
    const report = await getLastReportFn();
    console.log("Report retrieved:", report);
  }
}
```

## Usage Examples

### Basic setup with patient data

Data properties go on the element as attributes; callbacks are assigned as JS properties:

```html theme={null}
<sofia-sdk
  id="sofia"
  patientdata='{"age": 45, "history": "Arterial hypertension"}'
  language="es"
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
  template='{"type": "object"}'
  templateid="soap-general-v1"
  isopen="true"
></sofia-sdk>

<script>
  customElements.whenDefined('sofia-sdk').then(() => {
    const sofia = document.getElementById('sofia');
    sofia.handleReport = (report) => console.log('Report:', report);
    sofia.setIsOpen = (isOpen) => console.log('Open:', isOpen);
  });
</script>
```

### Chat-only mode (no report generation)

To use SofIA in chat-only mode, simply omit the `template` and `templateid` properties. The generate button will not appear.

```html theme={null}
<sofia-sdk
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
  language="es"
>
</sofia-sdk>
```

### Advanced configuration with callbacks

```html theme={null}
<sofia-sdk
  id="sofia"
  debug="true"
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
></sofia-sdk>

<script>
  customElements.whenDefined('sofia-sdk').then(() => {
    const sofia = document.getElementById('sofia');
    sofia.handleReport = (report) => console.log('Report:', report);
    sofia.setGetLastReport = (getReport) => { window.getLastSofiaReport = getReport; };
  });
</script>
```

<Tip>
  **Callbacks are JS properties, not HTML attributes.** Assign every callback directly on the element with camelCase (e.g. `element.handleReport = fn`, `element.setIsOpen = fn`, `element.setGetLastReport = fn`, `element.onReportApply = fn`, `element.updateTemplate = fn`). There is no `handle-report` HTML attribute or DOM event — an attribute like `handle-report="myFn"` will not fire. Simple data properties (`isopen`, `patientdata`, `debug`) use the same lowercase name as both an HTML attribute and a JS property.

  | Property           | Kind     | How to set                                                          |
  | ------------------ | -------- | ------------------------------------------------------------------- |
  | `handleReport`     | callback | JS property only: `el.handleReport = fn`                            |
  | `setIsOpen`        | callback | JS property only: `el.setIsOpen = fn`                               |
  | `setGetLastReport` | callback | JS property only: `el.setGetLastReport = fn`                        |
  | `onReportApply`    | callback | JS property only: `el.onReportApply = fn`                           |
  | `updateTemplate`   | callback | JS property only: `el.updateTemplate = fn`                          |
  | `handleExtras`     | callback | JS property only: `el.handleExtras = fn`                            |
  | `isopen`           | data     | HTML attribute or JS property                                       |
  | `patientdata`      | data     | HTML attribute or JS property                                       |
  | `templateExtras`   | data     | JS property `el.templateExtras` or HTML attribute `template-extras` |
  | `debug`            | data     | HTML attribute or JS property                                       |
</Tip>

## Deprecated Properties

<Warning>
  The following properties are deprecated and will be removed in v2.0. They have no effect in the current Chat-based UI architecture.
</Warning>

| Property                     | Migration                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------- |
| **toolsargs**                | Renamed to `template`. See [Required Properties](/sofia/en/sdk/required-properties)         |
| **isonlychat**               | No longer needed. Chat-only mode is automatic when `template`/`templateid` are not provided |
| **disableactions**           | To disable all actions, do not mount the `<sofia-sdk>` component                            |
| **disablegenerate**          | To hide the generate button, do not pass `template`/`templateid`                            |
| **sofiatitle**               | No longer configurable. The title is always "SofIA"                                         |
| **isscreenloading**          | Not available in Chat-based UI                                                              |
| **transcriptorselectvalues** | Not used in Chat-based UI                                                                   |
| **render-report-content**    | Not available in Chat-based UI                                                              |
| **handleFill**               | Not available in Chat-based UI                                                              |

## Important Notes

* **patientdata**: Should only contain information necessary for the clinical context, following data minimization principles.
* **States**: Changes in boolean properties are immediately reflected in the interface.
* **Localization**: Changing the language affects the entire component interface, including error messages and labels.
* **Callbacks**: Assign callbacks programmatically as JS properties on the element (e.g., `element.handleReport = fn`). They cannot be wired through HTML attributes or global function names.