> ## 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. # Required Properties > Mandatory configuration for SofIA SDK The SofIA SDK requires just three properties to connect: **`apikey`**, **`userid`**, and **`patientid`**. The component validates their presence and type before establishing the connection. `baseurl` is only required for some keys — see [Connection and authentication](#connection-and-authentication) below. ## Quick Reference All SofIA SDK properties in a single table. For detailed documentation, see [Connection and authentication](#connection-and-authentication) and [Optional Properties](/sofia/en/sdk/optional-properties). | Property | Type | Default | Status | Description | | ------------------------------ | -------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **apikey** | `string` | — | Required | Authentication key from Omniloy | | **userid** | `string` | — | Required | Internal surrogate identifier of the healthcare professional (never an MRN or direct PII) | | **patientid** | `string` | — | Required | Internal surrogate identifier of the patient for the session (never an MRN or direct PII) | | **baseurl** | `string` | auto | Conditional | REST API endpoint (HTTPS). Optional for newer keys since 1.0.8 (auto-resolved); required otherwise | | **template** | `object` | — | Optional | JSON Schema Draft-07 defining the clinical data structure. Enables report generation when used with `templateid` | | **templateid** | `string` | — | Optional | Integrator-defined identifier for the template. Required with `template` to enable report generation | | **isopen** | `boolean` | `true` | Optional | Component visibility state (open/closed) | | **handleReport** | `function` | — | Optional | Callback that receives the generated clinical report | | **setIsOpen** | `function` | — | Optional | Callback for visibility change events | | **setGetLastReport** | `function` | — | Optional | Callback that receives a function to retrieve the last report | | **onReportApply** | `function` | — | Optional | Receives the curated report from the [insertion preview modal](/sofia/en/sdk/insertion-preview) | | **updateTemplate** | `function` | — | Optional | Feeds existing EMR field content into generation ([pre-fill](/sofia/en/sdk/update-template)) | | **insertionPreviewClassNames** | `object` | — | Optional | Class-name overrides for the [insertion preview modal](/sofia/en/sdk/insertion-preview) | | **templateExtras** | `object` | — | Optional | JSON Schema of action categories; enables the [Extras](/sofia/en/sdk/extras) buttons together with `handleExtras`. `template-extras` attribute on the web component | | **handleExtras** | `function` | — | Optional | Receives the clinical actions extracted per category, pass-through ([Extras](/sofia/en/sdk/extras)) | | **patientdata** | `string` \| `object` | — | Optional | Contextual patient information for enriched processing | | **language** | `string` | `"es"` | Optional | Interface language (`"es"` or `"en"`) | | **debug** | `boolean` | `false` | Optional | Enables detailed console logging | | ~~wssurl~~ | `string` | — | Deprecated | Ignored since 1.0.7 — the transcriber URL now comes from the settings API | | ~~toolsargs~~ | `object` | — | Deprecated | Use `template` instead | | ~~isonlychat~~ | `boolean` | — | Deprecated | Auto-detected — omit `template`/`templateid` for chat-only | | ~~disableactions~~ | `boolean` | — | Deprecated | Do not mount the component instead | | ~~disablegenerate~~ | `boolean` | — | Deprecated | Omit `template`/`templateid` instead | | ~~sofiatitle~~ | `string` | — | Deprecated | Title is always "SofIA" | | ~~isscreenloading~~ | `boolean` | — | Deprecated | Not available in Chat-based UI | | ~~transcriptorselectvalues~~ | `array` | — | Deprecated | No effect | | ~~render-report-content~~ | `function` | — | Deprecated | Not available in Chat-based UI | | ~~handleFill~~ | `function` | — | Deprecated | Not available in Chat-based UI | For migration guidance on deprecated properties, see the [Migration Guide](/sofia/en/sdk/migration). ## Connection and authentication The `apikey` is the only connection property you always need. For newer keys, the SDK selects the endpoint automatically — so you do **not** pass `baseurl`. | Property | Type | Description | | ----------- | -------- | ---------------------------------------------------------------------------------------------- | | **apikey** | `string` | Authentication key from Omniloy. For newer keys the correct endpoint is selected automatically | | **baseurl** | `string` | REST API endpoint (HTTPS). **Optional** for newer keys; **required** otherwise | **Does my key need `baseurl`?** Newer keys don't — the SDK resolves the endpoint for you, so you can omit `baseurl`. Other keys do — keep passing the `baseurl` value Omniloy assigned you. If you're unsure, Omniloy will tell you which applies to your key. **`wssurl` is deprecated and ignored since v1.0.7.** The transcription WebSocket URL is now provided automatically by the settings API. Passing `wssurl` has no effect; you can safely remove it from your integration. ## Session Identifiers | Property | Type | Description | | ------------- | -------- | ---------------------------------------------------------------------------------- | | **userid** | `string` | Internal surrogate identifier of the healthcare professional in the EHR/HIS system | | **patientid** | `string` | Internal surrogate identifier of the patient for the current session | Use **internal surrogate identifiers** for `userid` and `patientid` — never a medical record number (MRN) or other direct patient/professional identifier. Unlike `patientdata`, these values are sent without anonymization. * Use persistent, unique identifiers * Avoid personally identifiable information * Maintain consistency across sessions * Consider using professional license numbers or internal IDs * Must be unique within your system * Should not contain direct personal identifiers * Can be changed dynamically for different consultations * Must comply with data protection regulations **Changing `patientid` triggers a full session reset.** When you update `patientid` dynamically, the SDK clears the chat history, closes the current WebSocket connection, and starts a completely new session. The previous conversation context is not carried over to the new patient. Always ensure any pending report generation has completed before switching patients. ## Report Generation These properties enable report generation. When both `template` and `templateid` are provided, the generate button becomes available in the interface. Without them, SofIA operates in chat-only mode automatically. | Property | Type | Required | Description | | -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **template** | `object` | Optional | Complete JSON Schema Draft-07 schema that defines the clinical data structure to generate. Required together with `templateid` to enable report generation. Pass as a JSON string in HTML attributes or as a JavaScript object programmatically | | **templateid** | `string` | Optional | Integrator-defined identifier for the template. Each unique template should have its own `templateid`. Required together with `template` to enable report generation | **Deprecated:** The `toolsargs` property has been renamed to `template`. Use `template` instead. `toolsargs` will be removed in v2.0. ### `template` (Optional — required for report generation) JSON Schema defining the structure for clinical data capture. When provided together with `templateid`, enables the report generation feature and shows the generate button in the interface. ```html theme={null} ``` **Schema requirements:** * Must be valid JSON Schema Draft-07 * Must include `$schema` property * Should define required fields appropriately * Must not exceed 100KB in size **Example for general consultation:** ```json theme={null} { "$schema": "http://json-schema.org/draft-07/schema#", "title": "General Medical Consultation", "type": "object", "properties": { "chief_complaint": { "type": "string", "description": "Primary reason for visit" }, "diagnosis": { "type": "string", "description": "Primary diagnosis" }, "treatment_plan": { "type": "string", "description": "Recommended treatment" } }, "required": ["chief_complaint", "diagnosis"] } ``` For complex schemas, set the `template` programmatically via JavaScript instead of inline HTML to avoid JSON escaping issues. See [Templates — Passing templates](/sofia/en/sdk/templates#passing-templates-to-the-component). ### `templateid` (Optional — required for report generation) Integrator-defined identifier that you assign to each template. Must be provided together with `template` to enable report generation. ```html theme={null} ``` **How it works:** * You choose the `templateid` value — it is not provided by Omniloy * Each unique template must have its own `templateid` * SofIA uses this ID to associate configurations and report history on the server * If you reuse the same `templateid` with a different `template` schema, the previous configuration will be overwritten Using the same `templateid` for different template schemas will overwrite the previous configuration. Always assign a distinct `templateid` to each template you use. **Naming examples:** * `"soap-general-v1"` — SOAP notes for general practice * `"emergency-triage-v2"` — emergency department triage * `"cardiology-consult-v1"` — cardiology consultations * `"my-clinic-intake-form"` — custom intake form for your clinic ## Automatic Validation The SofIA SDK component performs automatic validation of the required configuration properties: * **Type verification**: Confirms that each property has the correct type * **URL validation**: Verifies that the resolved `baseurl` uses the secure HTTPS protocol ### Validation Error Messages When validation fails, the SofIA SDK will display detailed error messages in the browser console and prevent the component from mounting. This ensures that integration issues are identified early in the development process. **Example validation error output:** ``` [Sofia SDK] Configuration Error - Missing or invalid required properties: • apikey: API key for authentication • userid: Unique identifier of the healthcare professional in the EHR/HIS system • patientid: Unique identifier of the patient in the EHR/HIS system • baseurl: API base URL (only required for keys that need it) Current value: "INVALID_API_KEY" Current value: "INVALID_USER_ID" Current value: "INVALID_PATIENT_ID" Component will not mount until all required properties are provided. Documentation: https://omniloy.mintlify.app/en/sdk/required-properties ``` **Error message components:** * **Property name**: Identifies which property failed validation * **Description**: Explains the purpose of each property * **Current value**: Shows the invalid value that was provided (when applicable) * **Documentation link**: Provides direct access to this reference guide **Component behavior during validation errors:** * The SofIA SDK component will not establish connections * No medical data processing will occur * The component remains in a safe, non-functional state * Error messages are logged to help developers identify and resolve issues quickly For comprehensive troubleshooting of validation errors, see our [troubleshooting guide](/sofia/en/sdk/troubleshooting). ## Minimal example (chat-only mode) With a newer key, `apikey`, `userid`, and `patientid` are all you need: ```html theme={null} ``` Does your key require a `baseurl`? Add the one Omniloy assigned you: ```html theme={null} ``` If any required property is missing or invalid, the component will show an error and will not connect to SofIA services. ## With report generation To enable report generation, add both `template` and `templateid`: ```html theme={null} ``` ## Complete Configuration Example ```html theme={null} ``` ## Dynamic Configuration ### Updating properties programmatically ```javascript theme={null} const sofiaElement = document.querySelector('sofia-sdk'); // Update patient for new consultation sofiaElement.setAttribute('patientid', 'patient-456'); // Update schema for different specialty const cardiologySchema = { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Cardiology Consultation", "type": "object", "properties": { "heart_rhythm": { "type": "string", "enum": ["normal", "irregular", "fast", "slow"] }, "blood_pressure": { "type": "string", "pattern": "^\\d{2,3}/\\d{2,3}$" }, "ecg_findings": { "type": "string" } }, "required": ["heart_rhythm", "blood_pressure"] }; sofiaElement.setAttribute('template', JSON.stringify(cardiologySchema)); ``` ### Framework-specific configuration **React** ```jsx theme={null} const [patientId, setPatientId] = useState('patient-123'); const [template, setTemplate] = useState({ "$schema": "http://json-schema.org/draft-07/schema#", "title": "Clinical Notes", "type": "object", "properties": { "diagnosis": { "type": "string", "description": "Primary diagnosis" } }, "required": ["diagnosis"] }); const [templateId, setTemplateId] = useState('soap-general-v1'); return ( ); ``` **Angular** ```typescript theme={null} export class AppComponent { apiKey = 'your-api-key'; userId = 'dr-lopez-456'; patientId = 'patient-789'; templateId = 'soap-general-v1'; schema = { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Clinical Notes", "type": "object", "properties": { "diagnosis": { "type": "string", "description": "Primary diagnosis" } }, "required": ["diagnosis"] }; templateJson = JSON.stringify(this.schema); } ``` ## Validation ### Property validation checklist * [ ] `apikey` is valid and not expired * [ ] `baseurl` uses HTTPS protocol (only needed for keys that require it) * [ ] `userid` is unique and consistent * [ ] `patientid` is unique for the consultation * [ ] `templateid` is unique per template and consistent across sessions (if using report generation) * [ ] `template` is valid JSON Schema Draft-07 (if using report generation) * [ ] All required properties are present * [ ] No properties exceed size limits ## Next Steps After configuring required properties: 1. [Configure optional properties](/sofia/en/sdk/optional-properties) 2. [Design clinical data schemas](/sofia/en/sdk/templates) 3. [Implement in your framework](/sofia/en/sdk/vanilla)