Migration Guide

Step-by-step guide to migrate from SofIA SDK v0.x to v1.0

This guide covers every breaking change and deprecation between SofIA SDK v0.0.x and v1.0.0, with before/after code examples and a checklist to complete the migration.

Start by upgrading to the latest version:

npm install @omniloy/sofia-sdk@latest

Migration overview

Area	What changed	Impact
Template prop	toolsargs → template	High — must rename
Chat-only mode	isonlychat removed	Medium — auto-detected now
Generate control	disablegenerate removed	Medium — omit template/templateid instead
Action control	disableactions removed	Low — don’t mount the component
UI customization	sofiatitle removed	Low — title is always “SofIA”
Loading state	isscreenloading removed	Low — not available in Chat UI
Transcriptor	transcriptorselectvalues removed	Low — no effect
Report rendering	renderReportContent removed	Low — not available in Chat UI
Fill callback	handleFill removed	Low — not available in Chat UI
Toast	toast removed	Low — no effect

Step-by-step migration

1. Rename toolsargs to template

The toolsargs prop has been renamed to template. The JSON Schema content is identical — only the attribute name changes.

Before (v0.x):

<sofia-sdk
  baseurl="https://api.example.com"
  wssurl="wss://ws.example.com"
  apikey="your-key"
  userid="doctor-1"
  patientid="patient-1"
  toolsargs='{"$schema":"http://json-schema.org/draft-07/schema#","title":"notes","type":"object","properties":{"diagnosis":{"type":"string"}}}'
></sofia-sdk>

After (v1.0):

<sofia-sdk
  baseurl="https://api.example.com"
  wssurl="wss://ws.example.com"
  apikey="your-key"
  userid="doctor-1"
  patientid="patient-1"
  template='{"$schema":"http://json-schema.org/draft-07/schema#","title":"notes","type":"object","properties":{"diagnosis":{"type":"string"}}}'
  templateid="your-template-id"
></sofia-sdk>

In v1.0, templateid is also required for report generation. Without both template and templateid, the SDK operates in chat-only mode.

2. Remove isonlychat

Chat-only mode is now automatic. If you omit both template and templateid, the SDK operates in chat-only mode without showing the generate button.

Before (v0.x):

<sofia-sdk
  isonlychat="true"
  baseurl="https://..."
  <!-- other props -->
></sofia-sdk>

After (v1.0):

<!-- Simply omit template and templateid -->
<sofia-sdk
  baseurl="https://..."
  <!-- other props -->
></sofia-sdk>

3. Remove disablegenerate

To hide the generate button, omit template and templateid instead of setting a flag.

Before (v0.x):

<sofia-sdk
  disablegenerate="true"
  toolsargs='...'
  <!-- other props -->
></sofia-sdk>

After (v1.0):

<!-- Omit template and templateid to disable generation -->
<sofia-sdk
  baseurl="https://..."
  <!-- other props, no template/templateid -->
></sofia-sdk>

4. Remove disableactions

If the component should not be rendered, don’t mount it at all instead of passing a disable flag.

Before (v0.x):

<sofia-sdk disableactions="true" ...></sofia-sdk>

After (v1.0):

// Conditionally render based on your application logic
if (shouldShowSofia) {
  document.getElementById('container').innerHTML = '<sofia-sdk ...></sofia-sdk>';
}

5. Remove remaining deprecated props

Remove these props entirely — they have no effect in v1.0:

Prop	Reason
sofiatitle	Title is always “SofIA”
isscreenloading	Not available in Chat-based UI
transcriptorselectvalues	No effect
toast	No effect
renderReportContent	Custom rendering not available in Chat UI
handleFill	Not available in Chat UI

6. Update callback assignments (framework-specific)

The handleReport, setIsOpen, and setGetLastReport callbacks remain unchanged. However, verify your bindings are correct:

Vanilla JS:

document.addEventListener('DOMContentLoaded', () => {
  const sofia = document.querySelector('sofia-sdk');
  sofia.handleReport = (report) => {
    console.log('Report:', report);
  };
});

React:

useEffect(() => {
  if (sofiaRef.current) {
    sofiaRef.current.handleReport = handleReport;
    sofiaRef.current.setIsOpen = setIsOpen;
  }
}, [handleReport, setIsOpen]);

Angular:

ngAfterViewInit() {
  this.sofia.nativeElement.handleReport = this.handleReport.bind(this);
  this.sofia.nativeElement.setIsOpen = this.setIsOpen.bind(this);
}

Migration checklist

Use this checklist to verify your migration is complete:

• Renamed all toolsargs attributes to template
• Added templateid wherever template is used
• Removed isonlychat — chat-only mode is automatic when template/templateid are omitted
• Removed disablegenerate — omit template/templateid instead
• Removed disableactions — conditionally mount/unmount the component
• Removed sofiatitle, isscreenloading, transcriptorselectvalues, toast
• Removed renderReportContent and handleFill callbacks
• Verified handleReport callback still works correctly
• Tested with debug="true" to confirm no deprecation warnings in console
• Validated in all target browsers

Enable debug="true" during migration. The SDK logs deprecation warnings for any v0.x props still in use, prefixed with [Sofia SDK] DEPRECATED:.

Breaking changes summary

Props removed in v1.0

These props were deprecated in v0.0.10 and are removed in v1.0. If still passed, they have no functional effect but emit deprecation warnings when debug="true" is enabled.

New requirements in v1.0

• templateid is now required alongside template for report generation
• The generate button only appears when both template and templateid are provided
• template must be a valid JSON Schema Draft-07 with $schema, type, and properties

No changes

These props work exactly the same in v1.0:

• baseurl, wssurl, apikey — required connection props
• userid, patientid — required session identifiers
• patientdata — optional patient context
• language — localization ("es" or "en")
• debug — enables verbose logging
• isopen — controls widget visibility
• handleReport — report delivery callback
• setIsOpen — visibility state callback
• setGetLastReport — last report retrieval