Required Properties

These properties are mandatory for the correct functioning of the SofIA SDK component. The component will automatically validate the presence and type of each property before establishing the connection.

Configuration Properties

Property	Type	Description
baseurl	`string`	URL of the SofIA REST API endpoint. Must use HTTPS protocol (e.g.: `https://api.example.com/v1`)
wssurl	`string`	WebSocket URL for real-time streaming. Must use WSS protocol (e.g.: `wss://ws.example.com`)
apikey	`string`	Authentication key provided by Omniloy for access to SofIA services

Session Identifiers

Property	Type	Description
userid	`string`	Unique identifier of the healthcare professional in the EHR/HIS system
patientid	`string`	Unique identifier of the patient for the current session

Schema Configuration

Property	Type	Description
toolsargs	`string` (JSON)	Complete JSON Schema Draft-07 schema that defines the clinical data structure to generate
templateid	`string`	Unique identifier for the clinical template being used (mandatory if `isonlychat` is not “true”)

Automatic Validation

The SofIA SDK component performs automatic validation of all required properties:

Type verification: Confirms that each property has the correct type
URL validation: Verifies that baseurl and wssurl use secure protocols (HTTPS/WSS)
JSON schema: Validates that toolsargs contains a valid JSON Schema

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:

  • baseurl: API base URL for backend communication
  • wssurl: WebSocket URL for real-time communication
  • 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
    Current value: "INVALID_BASE_URL"
    Current value: "INVALID_WSS_URL"
    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/api-schemas-properties/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.

Minimal Example

<sofia-sdk
  baseurl="https://api.example.com/v1"
  wssurl="wss://ws.example.com"
  apikey="your-api-key"
  userid="doctor123"
  patientid="patient456"
  toolsargs='{"type": "object", "properties": {"diagnosis": {"type": "string"}}}'
  templateid="template-123"
>
</sofia-sdk>

If any required property is missing or invalid, the component will show an error and will not connect to SofIA services.

`userid` (Required)

Unique identifier for the healthcare professional using the system.

<sofia-sdk userid="dr-martinez-123"></sofia-sdk>

Best practices:

Use persistent, unique identifiers
Avoid personally identifiable information
Maintain consistency across sessions
Consider using professional license numbers or internal IDs

`patientid` (Required)

Unique identifier for the patient in the current session.

<sofia-sdk patientid="patient-789"></sofia-sdk>

Important notes:

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

Schema Configuration

`toolsargs` (Required)

JSON Schema defining the structure for clinical data capture.

<sofia-sdk toolsargs='{"$schema":"http://json-schema.org/draft-07/schema#","title":"Medical Consultation"}'></sofia-sdk>

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:

{
  "$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"]
}

`templateid` (Required)

Unique identifier for the clinical template that defines the specific workflow and data structure for the consultation.

<sofia-sdk templateid="template-soap-123"></sofia-sdk>

Template requirements:

Must be a non-empty string
Should correspond to a valid template configured in your Omniloy account
Templates define the clinical workflow and output format
Different templates support different clinical specialties and documentation formats

Usage patterns:

SOAP Template: "soap-general-v1" for structured SOAP note generation
Emergency Template: "emergency-triage-v2" for emergency department workflows
Specialty Templates: "cardiology-consult-v1", "radiology-report-v1", etc.
Custom Templates: User-defined templates for specific organizational needs

Important notes:

This property is mandatory when isonlychat is not set to "true"
The template ID must be configured in your Omniloy account before use
Templates determine the available fields in the generated reports
Contact support@omniloy.com to configure custom templates

Complete Configuration Example

<sofia-sdk
  apikey="prod_abc123xyz789"
  baseurl="https://api.omniloy.com"
  wssurl="wss://wss.omniloy.com"
  userid="dr-garcia-456"
  patientid="patient-123"
  templateid="emergency-triage-v2"
  toolsargs='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Emergency Consultation",
    "type": "object",
    "properties": {
      "triage_level": {
        "type": "string",
        "enum": ["1", "2", "3", "4", "5"],
        "description": "Emergency triage level"
      },
      "chief_complaint": {
        "type": "string",
        "description": "Main complaint"
      },
      "vital_signs": {
        "type": "object",
        "properties": {
          "blood_pressure": {"type": "string"},
          "heart_rate": {"type": "number"},
          "temperature": {"type": "number"}
        }
      },
      "diagnosis": {
        "type": "string",
        "description": "Emergency diagnosis"
      },
      "disposition": {
        "type": "string",
        "enum": ["discharge", "admit", "transfer", "observe"],
        "description": "Patient disposition"
      }
    },
    "required": ["triage_level", "chief_complaint", "diagnosis", "disposition"]
  }'>
</sofia-sdk>

Dynamic Configuration

Updating properties programmatically

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('toolsargs', JSON.stringify(cardiologySchema));

Framework-specific configuration

React

const [patientId, setPatientId] = useState('patient-123');
const [toolsArgs, setToolsArgs] = useState(defaultSchema);
const [templateId, setTemplateId] = useState('soap-general-v1');

return (
  <sofia-sdk
    apikey="YOUR_API_KEY"
    baseurl="https://api.omniloy.com"
    wssurl="wss://wss.omniloy.com"
    userid="dr-smith-789"
    patientid={patientId}
    templateid={templateId}
    toolsargs={JSON.stringify(toolsArgs)}
  />
);

Angular

export class AppComponent {
  apiKey = 'YOUR_API_KEY';
  baseUrl = 'https://api.omniloy.com';
  wssUrl = 'wss://wss.omniloy.com';
  userId = 'dr-lopez-456';
  patientId = 'patient-789';
  templateId = 'soap-general-v1';
  toolsArgs = JSON.stringify(this.getSchemaForSpecialty('general'));
}

Vue.js

export default {
  data() {
    return {
      apiKey: 'YOUR_API_KEY',
      baseUrl: 'https://api.omniloy.com',
      wssUrl: 'wss://wss.omniloy.com',
      userId: 'dr-rodriguez-123',
      patientId: 'patient-456',
      toolsArgs: JSON.stringify(this.generalSchema)
    };
  }
};

Validation

Property validation checklist

apikey is valid and not expired
baseurl uses HTTPS protocol
wssurl uses WSS protocol
userid is unique and consistent
patientid is unique for the consultation
templateid is configured in your Omniloy account before use
toolsargs is valid JSON Schema Draft-07
All required properties are present
No properties exceed size limits

Next Steps

After configuring required properties:

Installation and Configuration

Framework Integration

Automation

Support Guides

Configuration Properties

Session Identifiers

Schema Configuration

Automatic Validation

Validation Error Messages

Minimal Example

`userid` (Required)

`patientid` (Required)

Schema Configuration

`toolsargs` (Required)

`templateid` (Required)

Complete Configuration Example

Dynamic Configuration

Updating properties programmatically

Framework-specific configuration

Validation

Property validation checklist

Next Steps

Installation and Configuration

Framework Integration

Automation

Support Guides

​Configuration Properties

​Session Identifiers

​Schema Configuration

​Automatic Validation

​Validation Error Messages

​Minimal Example

​userid (Required)

​patientid (Required)

​Schema Configuration

​toolsargs (Required)

​templateid (Required)

​Complete Configuration Example

​Dynamic Configuration

​Updating properties programmatically

​Framework-specific configuration

​Validation

​Property validation checklist

​Next Steps

Configuration Properties

Session Identifiers

Schema Configuration

Automatic Validation

Validation Error Messages

Minimal Example

`userid` (Required)

`patientid` (Required)

Schema Configuration

`toolsargs` (Required)

`templateid` (Required)

Complete Configuration Example

Dynamic Configuration

Updating properties programmatically

Framework-specific configuration

Validation

Property validation checklist

Next Steps