Formbox Docs

EHR integration via SMART on FHIR

Formbox can be launched from an external EHR as a SMART on FHIR app. In this mode, the form opens in the EHR context and has access to the current patient and encounter.

In the current implementation, Questionnaire and QuestionnaireResponse are stored in Formbox, while other patient data stays in the EHR.

This integration has been tested with Cerner.

When to use it

Use this integration when you want:

  • to open Formbox from an EHR chart or patient workspace
  • to prefill forms from the current patient context

SMART launch flow

The browser entrypoint for a SMART EHR launch is:

https://your-aidbox-domain/ui/sdc/smart/launch?iss=<...>&client-id=d414f88f-232f-4a25-bb22-025e8172ea94&launch=<...>

The callback URL uses the same host and path prefix:

https://your-aidbox-domain/ui/sdc/smart/callback?code=<...>&state=<...>

The EHR opens this page in the user's browser. Formbox reads the SMART launch context here and starts the OAuth exchange.

The launch URL carries these query parameters:

  • iss - the EHR FHIR base URL. Required.
  • client-id - the SMART client id registered in the EHR. Required.
  • launch - the EHR launch token. Passed through to the OAuth request.

launch

launch is the user-facing entrypoint opened by the EHR. It receives the SMART launch parameters, starts the authorization flow, and keeps the browser in the same session while login completes.

callback

callback is the OAuth redirect target. After login, the authorization server returns here with the authorization result, typically as code or error query parameters. Formbox finishes the token exchange and restores the SMART session.

In short:

  • launch is opened by the EHR
  • callback is used by the authorization server after login

Connection setup

Related setup docs:

The minimal setup is:

  1. Register the app in the EHR developer portal.
  2. Configure a SMART connection resource in Formbox.
  3. Point the default SDCConfig to that SMART connection.
  4. Allow the SMART client to access the required SDC routes.

1. Token validation

If the EHR issues opaque access tokens, configure a TokenIntrospector with type: opaque and an introspection endpoint.

resourceType: TokenIntrospector
id: ehr-opaque
type: opaque
cache_ttl: 300
introspection_endpoint:
  url: https://ehr.example.com/tokeninfo

If the EHR issues JWT access tokens, configure a TokenIntrospector with type: jwt and either a shared secret, local keys, or jwks_uri.

resourceType: TokenIntrospector
id: ehr-jwt
type: jwt
jwt:
  iss: https://ehr.example.com
jwks_uri: https://ehr.example.com/.well-known/jwks.json

2. SMART connection

Use SDCSmartConnect to describe the EHR connection:

resourceType: SDCSmartConnect
id: ehr-smart
name: ehr-smart
client-id: <client-id>
fhir-url: https://ehr.example.com/fhir
auth:
  reference: TokenIntrospector/ehr-opaque
scopes:
  - openid
  - fhirUser
  - launch
  - offline_access
  - user/Patient.rs

3. Default SDC config

Link the SMART connection from the default SDCConfig:

resourceType: SDCConfig
name: ehr-smart-config
default: true
smart-connect:
  reference: SDCSmartConnect/ehr-smart

4. Access policy

The SMART client must be allowed to reach the Formbox endpoints used by the app. The client_id in the policy must match the client-id from SDCSmartConnect.

resourceType: AccessPolicy
id: sdc-smart-provider-policy
engine: matcho
matcho:
  token:
    active: true
    client_id: <client-id>
  uri:
    $one-of:
      - '#^/sdc/.*$'
      - '#^/\$sdc-config$'
      - '#^/\$sdc-resource-types$'
      - '#^/\$sdc-resource-schema$'
      - '#^/\$sdc-file(/.*)?$'
      - '#^/\$extend-sdc-session$'
      - '#^/\$drop-sdc-session$'
      - '#^/QuestionnaireTheme(/.*)?$'
      - '#^/QuestionnaireResponse/[^/]+/\$[a-z-]+$'
      - '#^/fhir/Questionnaire(/[^/]+)?(/\$[a-z-]+)?/?$'
      - '#^/fhir/QuestionnaireResponse(/\$[a-z-]+)?/?$'
  request-method:
    $one-of: [get, post, put, patch, delete]

Sandbox note

EHR sandboxes may require whitelisting or a support request before SMART launch is available in the provider UI.

UI behavior in SMART mode

The SMART launch changes the default UI in a few places:

  • On Forms / Responses / Library, a patient header appears in the upper-left corner with the patient name and birth date.
  • If patient lookup fails, the header falls back to Patient/<id>.
  • Responses is filtered to the current patient only.
  • The Run button on Forms appears only in SMART mode.
  • Clicking Run populates the form with patient data and opens the created QuestionnaireResponse.
  • In Share and Send, Subject and Encounter come from the SMART context and are read-only.

Populate and context parameters

Questionnaire/$populatelink and Questionnaire/$populate accept a Parameters resource. In SMART mode, Formbox passes patient context as EHR-side identifiers instead of internal FHIR references.

  • subject and encounter use the EHR identity namespace
  • patient is passed as a context parameter and is available to populate expressions

In a regular Formbox session, the same fields are resolved as internal FHIR references.

Populate examples

Non-SMART Parameters request:

resourceType: Parameters
parameter:
  - name: subject
    valueReference:
      reference: Patient/pt1
  - name: encounter
    valueReference:
      reference: Encounter/enc1

SMART Parameters request:

resourceType: Parameters
parameter:
  - name: subject
    valueReference:
      identifier:
        system: https://ehr.example.com/fhir
        value: pt1
  - name: encounter
    valueReference:
      identifier:
        system: https://ehr.example.com/fhir
        value: enc1
  - name: context
    part:
      - name: name
        valueString: patient
      - name: content
        valueReference:
          identifier:
            system: https://ehr.example.com/fhir
            value: pt1

Use identifier in SMART mode so Formbox keeps EHR identities separate from internal FHIR references.

Where the identifier comes from

In SMART mode, Formbox builds the identifier from the launch context provided by the EHR:

  • identifier.system is the EHR FHIR server base URL
  • identifier.value is the patient or encounter id from the SMART launch context

As a result, a patient reference is represented as "this patient on this EHR FHIR server", not as an internal Aidbox Patient/{id} reference.

Last updated: