Skip to main content

$useFhirServer

$useFhirServer(target?, config?) -> undefined
Compact type signature<s?o?:u>
Browse categories
FHIR Server And Resource

Availability​

Community v3.1.0+
Enterprise v3.1.0+

Signature​

$useFhirServer(target?: string, config?: { authType?: 'NONE' | 'BASIC'; username?: string; password?: string; fhirVersion?: string; timeout?: number }) -> undefined

Documentation​

$useFhirServer(target?, config?) switches the active FHIR server for subsequent FHIR operations within the current expression block. The switch is scoped to the block and does not affect outer blocks or future evaluations.

Arguments​

target (optional)

  • Type: string
  • A connection name defined in Named FHIR Connections, or a full URL starting with http:// or https://.
  • For a named connection, target is the configured name. For an inline URL connection, target is the server baseUrl.
  • If omitted or null, resets to the default server (from FHIR_SERVER_BASE).

config (optional)

  • Type: object
  • Only meaningful when target is a URL (not a named connection).
  • Supported properties:
    • authType?: 'NONE' | 'BASIC'
    • username?: string
    • password?: string
    • fhirVersion?: string
    • timeout?: number
  • If authType is omitted, FUME treats inline credentials as BASIC auth and otherwise defaults to no auth.
  • Named connections stay file-driven. Configure named connection auth, timeout, and FHIR version in Named FHIR Connections instead of passing config here.

Return value​

Always undefined.

Scoping behavior​

$useFhirServer() modifies the lexical scope of the enclosing block. The change takes effect for all FHIR operations in the current block and nested blocks, but does not leak to the outer block or sibling blocks.

Example: block-scope isolation​

(
  /* Default server (FHIR_SERVER_BASE) is active here */
  $defaultPatients := $search("Patient", {"_count": 1});

  $altResult := (
    /* Switch to alternate server for this block only */
    $useFhirServer("myAltServer");
    $altPatients := $search("Patient", {"_count": 1});  /* uses myAltServer */
    $nestedOrgs := (
      /* Nested block inherits the switch */
      $search("Organization", {})    /* still uses myAltServer */
    );
    { "patients": $altPatients.entry.resource, "orgs": $nestedOrgs.entry.resource }
  );

  /* myAltServer is no longer active here */
  $defaultAfter := $search("Patient", {"_count": 1});  /* uses FHIR_SERVER_BASE again */

  {
    "before": $defaultPatients.entry.resource,
    "fromAlt": $altResult,
    "after": $defaultAfter.entry.resource
  }
)

Connection modes​

Named connection​

If you have configured a named connection in Named FHIR Connections, reference it by name:

$useFhirServer("healthSystemFhir");
$search("Patient", {"identifier": memberId})

To discover the configured names dynamically instead of hard-coding them, use $fhirConnectionNames().

URL mode​

Use a full URL to query a FHIR server without pre-configuring it:

$useFhirServer("https://r4.smarthealthit.org");
$search("Patient", {"_count": 5})

URL-based connections are cached in an LRU pool to reduce connection overhead. Configure FHIR_CONNECTIONS_URL_POOL_SIZE.

URL mode with BASIC authentication​

Pass a second argument to use HTTP Basic authentication with a URL:

$useFhirServer(
  "https://fhir.internal.example.com/R4",
  {"authType": "BASIC", "username": "myuser", "password": "mypass"}
)

URL mode with inline FHIR version​

Use config.fhirVersion when the inline URL target should not inherit the server-wide default:

$useFhirServer(
  "https://fhir-r5.internal.example.com",
  {"fhirVersion": "5.0.0"}
);
$capabilities();

URL mode with inline timeout​

Use config.timeout to override the request timeout for that inline URL target:

$useFhirServer(
  "https://slow-partner.example.com/fhir",
  {"timeout": 60000}
);
$search("Patient", {"_count": 5});
Security warning

Embedding credentials directly in expressions is a security risk. Credentials may appear in:

  • Mapping definitions stored on disk or in version control
  • Server logs and audit trails
  • Diagnostic traces

Prefer named connections with environment variable substitution instead. Example:

# connections.yml
fhir:
  - name: internal
    baseUrl: "https://fhir.internal.example.com/R4"
    authType: BASIC
    username: ${MY_FHIR_USER}
    password: ${MY_FHIR_PASSWORD}

Then use it securely:

$useFhirServer("internal")

Affected operations​

The following FHIR client functions respect the active connection set by $useFhirServer():

Non-affected operations​

The following operations always use the default server and cannot be switched:

  • $translate(), $translateCode(), $translateCoding() — always use default server for terminology
  • Alias resolution — always use default server for conformance
  • StructureMap and ConceptMap fetching — always use default server for conformance

This design ensures that terminology and mapping definitions remain stable across an evaluation, even when switching between servers for data operations.

Resetting to default​

To reset back to the default server mid-block, call $useFhirServer() with no arguments:

(
  $useFhirServer("altServer");
  $altPatients := $search("Patient", {"_count": 1});       /* uses altServer */

  $useFhirServer();                                         /* reset to default */
  $defaultOrgs := $search("Organization", {"_count": 1});  /* uses default again */

  { "patients": $altPatients.entry.resource, "orgs": $defaultOrgs.entry.resource }
)

Error handling​

ScenarioBehavior
Unknown named connectionThrows an error: Unknown FHIR connection name: "..."
Named connection with inline configThrows an error because inline FHIR connection config is only supported for URL targets
Invalid URL formatThrows an error
Server unreachableError thrown by the underlying FHIR client during the actual request
Invalid inline auth/configThrows before the request if the config is inconsistent, such as authType: 'BASIC' without both credentials

Examples​

Simple named connection​

Suppose Named FHIR Connections contains:

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

Use it in an expression:

$useFhirServer("publicFhir");
$search("Patient", {"_count": 10})

Querying multiple servers in one expression​

Switch servers mid-block and capture each result into a named variable, then return an aggregate object:

(
  $useFhirServer("serverA");
  $patientsA := $search("Patient", {"_count": 5});

  $useFhirServer("serverB");
  $patientsB := $search("Patient", {"_count": 5});

  {
    "fromServerA": $patientsA.entry.resource,
    "fromServerB": $patientsB.entry.resource
  }
)

URL with inline config​

$useFhirServer(
  "https://fhir.internal.example.com/R4",
  {
    "authType": "BASIC",
    "username": "operator",
    "password": "secret123",
    "fhirVersion": "4.0.1",
    "timeout": 45000
  }
);
$search("Patient", {"identifier": memberId});

See also​