Skip to main content

Named FHIR Connections

Applies to​

  • Community v3.1.0+
  • Enterprise v3.1.0+

Purpose​

Configure alternate FHIR servers that can be switched to dynamically within expressions using $useFhirServer(). Named connections are the recommended approach for reusable targets and any connection that carries credentials.

File location and configuration​

By default, FUME looks for a connections.yml file in the server's working directory. To use a different path or filename, set FHIR_CONNECTIONS_FILE to that path.

FHIR_CONNECTIONS_FILE=/etc/fume/my-connections.yml

If the file does not exist, FUME starts normally with no named connections available (only the default server from FHIR_SERVER_BASE is available).

As an alternative deployment mode, FHIR_CONNECTIONS_FILE can also hold an inline base64-encoded YAML document instead of a file path. If the configured value does not resolve to an existing file, FUME attempts to decode it as base64 and parse the decoded YAML.

FHIR_CONNECTIONS_FILE=ZmhpcjoKICAtIG5hbWU6IHB1YmxpY0ZoaXIKICAgIGJhc2VVcmw6ICJodHRwczovL3I0LnNtYXJ0aGVhbHRoaXQub3JnIg==

Schema​

fhir:
  - name: myFhirServer
    baseUrl: "https://fhir.example.com/R4"
    fhirVersion: "4.0.1"           # optional; falls back to global FHIR_VERSION
    authType: BASIC                 # optional; NONE (default) or BASIC
    username: ${FHIR_CONN_UN}       # required if authType is BASIC
    password: ${FHIR_CONN_PW}       # required if authType is BASIC
    timeout: 30000                  # optional (milliseconds); falls back to global FHIR_SERVER_TIMEOUT

  - name: publicServer
    baseUrl: "https://r4.smarthealthit.org"
    fhirVersion: "4.0.1"
    authType: NONE

Field descriptions​

FieldTypeRequiredNotes
namestringyesConnection name for use in $useFhirServer("name")
baseUrlstringyesFHIR server base URL
fhirVersionstringnoFHIR version (e.g., "4.0.1"). If omitted, falls back to global FHIR_VERSION environment variable.
authTypeNONE | BASICnoAuthentication type. Default is NONE. BEARER and token-based auth are not yet supported.
usernamestringconditionalRequired if authType: BASIC. Supports ${ENV_VAR} substitution.
passwordstringconditionalRequired if authType: BASIC. Supports ${ENV_VAR} substitution.
timeoutnumbernoRequest timeout in milliseconds. If omitted, falls back to global FHIR_SERVER_TIMEOUT.

Environment variable substitution​

Fields containing ${VARIABLE_NAME} are expanded at server startup using the value of the environment variable VARIABLE_NAME. If a referenced variable is not set, FUME will emit an error and fail to start.

fhir:
  - name: healthSystem
    baseUrl: "https://fhir.healthsystem.local/R4"
    authType: BASIC
    username: ${HEALTHSYSTEM_USER}
    password: ${HEALTHSYSTEM_PASSWORD}

This environment-variable substitution happens in both source modes: after reading a file and after decoding an inline base64 payload.

Before starting the server:

HEALTHSYSTEM_USER=myuser
HEALTHSYSTEM_PASSWORD=mysecret
Security best practice

Use environment variables for all credentials. Never embed secrets directly in connections.yml or check them into version control.

URL-based usage​

Using $useFhirServer() with a raw URL is documented on the function page, including scope behavior and security guidance.

If you need the configured names inside an expression, call $fhirConnectionNames(). It returns the configured named connection names in load order and never exposes URLs or credentials.

When you call $useFhirServer(target, config):

  • target supplies either the named connection name or the inline URL baseUrl
  • config is only for inline URL targets and supports the same meaningful connection settings as the named-connections YAML document: authType, username, password, fhirVersion, and timeout
  • name and baseUrl are not repeated inside config; they come from the first function argument
  • Named connections remain YAML-driven. Passing inline config together with a named connection is invalid; put those settings in the named-connections YAML instead

Use inline URL config for one-off targets. Use named connections for stable, reusable, or secret-bearing connections.

Important: Conformance resources always use the default server​

The following operations always use the default FHIR server (from FHIR_SERVER_BASE) and are not affected by $useFhirServer():

This design ensures that terminology and mapping definitions remain stable throughout an evaluation, even if other FHIR operations switch servers mid-expression.

Examples​

Basic connection (no auth)​

fhir:
  - name: publicFhir
    baseUrl: "https://r4.smarthealthit.org"
    fhirVersion: "4.0.1"

BASIC auth connection​

fhir:
  - name: internal
    baseUrl: "https://fhir.internal.example.com/R4"
    fhirVersion: "4.0.1"
    authType: BASIC
    username: ${INTERNAL_FHIR_USER}
    password: ${INTERNAL_FHIR_PASSWORD}

Multiple connections with environment-specific URLs​

fhir:
  - name: staging
    baseUrl: "https://fhir-staging.example.com/R4"
    fhirVersion: "4.0.1"
    authType: BASIC
    username: ${STAGING_USER}
    password: ${STAGING_PASSWORD}

  - name: production
    baseUrl: "https://fhir-prod.example.com/R4"
    fhirVersion: "4.0.1"
    authType: BASIC
    username: ${PROD_USER}
    password: ${PROD_PASSWORD}

Then, from an expression, switch between them:

(
  $useFhirServer("staging");
  $patient := $search("Patient", {"identifier": memberId});

  $useFhirServer("production");
  $org := $resolve("Organization/" & orgId);

  {
    "patient": $patient.entry.resource,
    "organization": $org
  }
)

Notes​