FHIR Source

The FHIR source starts an HTTP server that exposes a FHIR-compliant REST endpoint, accepting resource create and update operations, or receiving FHIR Subscription notifications from an upstream FHIR server.

It supports both FHIR R4 and STU3, making it compatible with a wide range of EHR systems and FHIR intermediaries.

Configuration

source:
  type: fhir
  port: 9443
  base_path: /fhir
  version: R4
  resources:
    - Patient
    - Encounter
    - Observation
  subscription_type: rest-hook
  tls:
    cert_file: ./certs/server.crt
    key_file: ./certs/server.key
  auth:
    type: oauth2
    issuer: https://idp.hospital.org
    audience: intu-fhir
    jwks_url: https://idp.hospital.org/.well-known/jwks.json

Properties

Property	Type	Required	Default	Description
`port`	`int`	Yes	—	TCP port the FHIR server binds to.
`base_path`	`string`	No	`/fhir`	Base URL path for the FHIR endpoint.
`version`	`"R4"` \| `"STU3"`	No	`R4`	FHIR version to advertise and validate against.
`resources`	`string[]`	No	—	Restrict accepted resource types. If omitted, all resource types are accepted.
`subscription_type`	`"rest-hook"` \| `"websocket"`	No	—	Enable FHIR Subscription mode instead of direct REST.
`tls`	`object`	No	—	TLS certificate and key for HTTPS.
`auth`	`object`	No	—	Authentication configuration.

Subscription Types

Type	Description
`rest-hook`	The upstream FHIR server POSTs a notification payload to this endpoint when a subscribed resource changes.
`websocket`	The source opens a WebSocket connection to the upstream server and receives real-time notifications.

When subscription_type is not set, the source operates as a standard FHIR REST server accepting POST and PUT operations directly.

Authentication

The auth block supports multiple strategies:

Bearer Token

auth:
  type: bearer
  token: ${FHIR_BEARER_TOKEN}

OAuth 2.0 (JWT Validation)

auth:
  type: oauth2
  issuer: https://idp.hospital.org
  audience: intu-fhir
  jwks_url: https://idp.hospital.org/.well-known/jwks.json

SMART on FHIR

auth:
  type: smart
  issuer: https://idp.hospital.org
  audience: intu-fhir
  jwks_url: https://idp.hospital.org/.well-known/jwks.json
  scopes:
    - patient/*.read
    - system/*.write

Complete Example

A FHIR endpoint with OAuth 2.0 that accepts Patient and Encounter resources and forwards them as HL7v2 ADT messages:

id: fhir-to-hl7
enabled: true
group: admissions

source:
  type: fhir
  port: 9443
  base_path: /fhir
  version: R4
  resources:
    - Patient
    - Encounter
  tls:
    cert_file: ./certs/server.crt
    key_file: ./certs/server.key
  auth:
    type: oauth2
    issuer: https://idp.hospital.org
    audience: intu-fhir
    jwks_url: https://idp.hospital.org/.well-known/jwks.json

transformer: fhir-patient-to-adt.ts

destinations:
  - hl7_downstream
  - audit_log

Transformer Example

A TypeScript transformer that converts a FHIR Patient resource into an HL7v2 ADT^A01 message using node-hl7-client:

import { Message } from "node-hl7-client";

export default function transform(msg: IntuMessage): IntuMessage {
  const patient = JSON.parse(msg.payload) as fhir4.Patient;

  const adt = new Message({ messageHeader: { msh_9_1: "ADT", msh_9_2: "A01" } });

  adt.set("PID.3.1", patient.identifier?.[0]?.value ?? "");
  adt.set("PID.5.1", patient.name?.[0]?.family ?? "");
  adt.set("PID.5.2", patient.name?.[0]?.given?.[0] ?? "");
  adt.set("PID.7.1", patient.birthDate?.replace(/-/g, "") ?? "");
  adt.set("PID.8", patient.gender === "male" ? "M" : patient.gender === "female" ? "F" : "U");

  msg.payload = adt.toString();
  return msg;
}