LaunchContextProvider API

Complete API reference for the LaunchContextProvider component, which provides patient context to FormFiller for intelligent form pre-population.

Overview

The LaunchContextProvider component:

Fetches patient data from FHIR R5 endpoints
Provides launch context to FormFiller instances
Enables pre-population of questionnaires with patient information
Supports SDC $populate operation for smart form initialization
Works seamlessly with FormFiller through shared references

Constructor

Signature

new LaunchContextProvider(config: LaunchContextConfig): LaunchContextProvider

Parameters

config LaunchContextConfig (required)

Configuration object with the following properties:

Property	Type	Required	Description
`dataEndpoint`	`EndpointConfig`	Yes	FHIR R5 data endpoint for patient resources
`filler`	`FormFiller`	Yes	FormFiller instance to provide context to
`patientId`	`string`	No	Patient ID to load context for

EndpointConfig Type

interface EndpointConfig {
  resourceType: 'Endpoint'
  address: string
}

Basic Example

import { FormFiller, LaunchContextProvider } from '@tiro-health/web-sdk'

const filler = new FormFiller({
  questionnaire: 'patient-intake',
  sdcEndpoint: { /* ... */ }
})

const contextProvider = new LaunchContextProvider({
  dataEndpoint: {
    resourceType: 'Endpoint',
    address: 'https://fhir-server.example.com/fhir'
  },
  filler: filler,
  patientId: 'patient-123'
})

Configuration Options

dataEndpoint

Type: EndpointConfig (required)

FHIR R5-compliant endpoint that provides patient data and related resources.

dataEndpoint: {
  resourceType: 'Endpoint',
  address: 'https://fhir-server.example.com/fhir'
}

Required capabilities:

GET /Patient/{id} - Retrieve patient demographics
GET /Observation?patient={id} - Retrieve patient observations
GET /Condition?patient={id} - Retrieve patient conditions
Other resources as needed for pre-population

Note: This is typically your main FHIR server, separate from the SDC endpoint.

filler

Type: FormFiller (required)

The FormFiller instance to provide patient context to.

const filler = new FormFiller({ /* ... */ })

const contextProvider = new LaunchContextProvider({
  dataEndpoint: { /* ... */ },
  filler: filler  // Pass the filler instance
})

Important:

Must be created before LaunchContextProvider
Can be shared with Narrative and ValidationFeedback components
Context is automatically synchronized

patientId

Type: string (optional)

The FHIR Patient resource ID to load context for.

patientId: 'patient-123'

// Or from URL parameter
patientId: new URLSearchParams(window.location.search).get('patient')

// Or from application state
patientId: getCurrentPatient().id

Note: If not provided, the provider will wait for patient selection through its UI.

Methods

mount()

Mounts the LaunchContextProvider component to a DOM element.

Signature:

mount(element: HTMLElement): void

Parameters:

element: DOM element to mount the component into

Example:

const container = document.getElementById('context-container')
contextProvider.mount(container)

What it displays:

Patient information card (if patientId provided)
Patient selector (if patientId not provided)
Loading states during data fetch
Error messages if patient data unavailable

unmount()

Unmounts the LaunchContextProvider component and cleans up resources.

Signature:

unmount(): void

Example:

contextProvider.unmount()

Cleanup performed:

Removes all DOM elements
Cancels pending FHIR requests
Clears patient context
Frees memory

Use Cases

Pre-populating Forms with Patient Data

The primary use case is automatically filling questionnaire fields with existing patient data:

const filler = new FormFiller({
  questionnaire: 'annual-checkup',
  sdcEndpoint: { /* ... */ }
})

const contextProvider = new LaunchContextProvider({
  dataEndpoint: {
    resourceType: 'Endpoint',
    address: 'https://fhir-server.example.com/fhir'
  },
  filler: filler,
  patientId: 'patient-123'
})

contextProvider.mount(document.getElementById('context'))
filler.mount(document.getElementById('form'))

Automatic pre-population:

Patient name → name fields
Patient date of birth → DOB fields
Patient gender → gender fields
Recent observations → clinical value fields
Known conditions → diagnosis fields

Dynamic Patient Selection

Allow users to select a patient before filling the form:

// Don't provide patientId initially
const contextProvider = new LaunchContextProvider({
  dataEndpoint: { /* ... */ },
  filler: filler
  // No patientId - shows patient selector
})

// The UI will display a patient search/select interface
contextProvider.mount(document.getElementById('patient-selector'))

// When patient is selected, context is automatically provided to filler

Multi-Patient Workflows

Support workflows where multiple patients are processed:

let currentContextProvider = null

function loadPatientForm(patientId) {
  // Clean up previous context
  currentContextProvider?.unmount()

  // Create new context for this patient
  currentContextProvider = new LaunchContextProvider({
    dataEndpoint: { /* ... */ },
    filler: filler,
    patientId: patientId
  })

  currentContextProvider.mount(document.getElementById('context'))
}

// Load different patients
loadPatientForm('patient-123')
// Later...
loadPatientForm('patient-456')

Integration with EHR Launch

Use with SMART on FHIR launch context:

// Get patient from SMART launch context
const smart = await FHIR.oauth2.ready()
const patient = smart.patient.id

const contextProvider = new LaunchContextProvider({
  dataEndpoint: {
    resourceType: 'Endpoint',
    address: smart.state.serverUrl
  },
  filler: filler,
  patientId: patient
})

Examples

Complete Setup with All Components

import {
  FormFiller,
  LaunchContextProvider,
  Narrative,
  ValidationFeedback
} from '@tiro-health/web-sdk'

// Create FormFiller
const filler = new FormFiller({
  questionnaire: 'comprehensive-assessment',
  sdcEndpoint: {
    resourceType: 'Endpoint',
    address: 'https://sdc.example.com/fhir'
  },
  onSubmit: (response) => {
    console.log('Submitted:', response)
  }
})

// Create LaunchContextProvider
const contextProvider = new LaunchContextProvider({
  dataEndpoint: {
    resourceType: 'Endpoint',
    address: 'https://fhir-server.example.com/fhir'
  },
  filler: filler,
  patientId: 'patient-123'
})

// Create additional components
const narrative = new Narrative({ filler })
const validation = new ValidationFeedback({ filler })

// Mount all components
contextProvider.mount(document.getElementById('patient-context'))
filler.mount(document.getElementById('questionnaire-form'))
narrative.mount(document.getElementById('clinical-narrative'))
validation.mount(document.getElementById('validation-feedback'))

// Cleanup on page unload
window.addEventListener('beforeunload', () => {
  contextProvider.unmount()
  filler.unmount()
  narrative.unmount()
  validation.unmount()
})

With Error Handling

const contextProvider = new LaunchContextProvider({
  dataEndpoint: {
    resourceType: 'Endpoint',
    address: 'https://fhir-server.example.com/fhir'
  },
  filler: filler,
  patientId: patientId,
  onError: (error) => {
    console.error('Failed to load patient context:', error)

    // Show user-friendly message
    showNotification({
      type: 'warning',
      message: 'Unable to load patient data. Form will not be pre-populated.',
      action: {
        label: 'Retry',
        onClick: () => retryContextLoad()
      }
    })
  }
})

React Integration

import { useEffect, useRef } from 'react'
import {
  FormFiller,
  LaunchContextProvider
} from '@tiro-health/web-sdk'

export function PatientForm({ patientId }) {
  const contextRef = useRef<HTMLDivElement>(null)
  const formRef = useRef<HTMLDivElement>(null)
  const fillerRef = useRef<FormFiller | null>(null)
  const contextProviderRef = useRef<LaunchContextProvider | null>(null)

  useEffect(() => {
    if (!contextRef.current || !formRef.current) return

    // Create filler
    const filler = new FormFiller({
      questionnaire: 'patient-intake',
      sdcEndpoint: { /* ... */ }
    })

    // Create context provider
    const contextProvider = new LaunchContextProvider({
      dataEndpoint: { /* ... */ },
      filler: filler,
      patientId: patientId
    })

    // Mount components
    contextProvider.mount(contextRef.current)
    filler.mount(formRef.current)

    // Store refs
    fillerRef.current = filler
    contextProviderRef.current = contextProvider

    // Cleanup
    return () => {
      contextProvider.unmount()
      filler.unmount()
    }
  }, [patientId])

  return (
    <div>
      <div ref={contextRef} />
      <div ref={formRef} />
    </div>
  )
}

Angular Integration

import { Component, AfterViewInit, OnDestroy, ViewChild, ElementRef } from '@angular/core'
import { FormFiller, LaunchContextProvider } from '@tiro-health/web-sdk'

@Component({
  selector: 'app-patient-form',
  templateUrl: './patient-form.component.html'
})
export class PatientFormComponent implements AfterViewInit, OnDestroy {
  @ViewChild('contextContainer') contextContainer!: ElementRef
  @ViewChild('formContainer') formContainer!: ElementRef

  private contextProvider?: LaunchContextProvider
  private filler?: FormFiller

  ngAfterViewInit(): void {
    this.filler = new FormFiller({
      questionnaire: 'patient-intake',
      sdcEndpoint: { /* ... */ }
    })

    this.contextProvider = new LaunchContextProvider({
      dataEndpoint: { /* ... */ },
      filler: this.filler,
      patientId: 'patient-123'
    })

    this.contextProvider.mount(this.contextContainer.nativeElement)
    this.filler.mount(this.formContainer.nativeElement)
  }

  ngOnDestroy(): void {
    this.contextProvider?.unmount()
    this.filler?.unmount()
  }
}

Next Steps

Learn about FormFiller for complete form capabilities
Explore Narrative for clinical text generation
See ValidationFeedback for real-time validation
Check integration guides for framework patterns

For questions or support, please contact the Tiro.health team.