Skip to content

Launching Apps (SMART)

This guide explains how to attach and invoke your own SMART-on-FHIR app using Form Lab’s local environment.

1. Register Your App

Add your app to the EHR Launcher configuration (ehr-config.json). Example entry:

{
  "name": "My SMART App",
  "client_id": "my-smart-app-client-id",
  "launch_url": "http://localhost:3000/",
  "redirect_uri": "http://localhost:3000/callback",
  "scope": "launch/patient patient/*.read openid fhirUser",
  "aud": "http://smart-launcher:8081/fhir"
}
  • name: Display name in the launcher UI
  • client_id: Registered client ID for your app
  • launch_url: Entry point for your app
  • redirect_uri: OAuth2 redirect URI
  • scope: Required SMART scopes
  • aud: Audience (FHIR base URL via proxy)

To launch your app, use the following URL format in the EHR Launcher UI (port 81):

http://localhost:81/launch?app=my-smart-app-client-id&patient=example-patient-id&iss=http://smart-launcher:8081/fhir
  • app: Your app’s client ID
  • patient: Patient ID to launch with
  • iss: FHIR issuer (SMART proxy base URL)

3. Handle OAuth2 in Your App

  • Implement PKCE (Proof Key for Code Exchange)
  • Exchange the authorization_code at the token endpoint (http://localhost:8081/token)
  • Extract fhirUser, patient, and scope from the access token

4. Testing Tips

  • Use the test patient “Mrs Smart Form” for demo launches
  • Inspect QuestionnaireResponse resources at https://fhir.formlab.fhirlab.net/resource?...
  • Enable verbose logging in your app and monitor the proxy container logs

5. Common Pitfalls

  • Ensure redirect URIs match exactly
  • Use secure contexts (localhost is fine)
  • CORS issues are usually handled by the proxy, but keep origins consistent

For more details, see the _docs/api-reference.md and _docs/examples.md.