FHIR R4 Source Connector | intu Healthcare Integration Framework

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

Configure the FHIR source under listener in channel.yaml, with type: fhir and a fhir block:

listener:
  type: fhir
  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
      token_url: https://idp.hospital.org/oauth2/token
      client_id: ${FHIR_CLIENT_ID}
      client_secret: ${FHIR_CLIENT_SECRET}

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 that accepts Patient and Encounter resources and forwards them as HL7v2 ADT messages:

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

listener:
  type: fhir
  fhir:
    port: 9443
    base_path: /fhir
    version: R4
    resources:
      - Patient
      - Encounter
    tls:
      cert_file: ./certs/server.crt
      key_file: ./certs/server.key

validator:
  entrypoint: validator.ts

transformer:
  entrypoint: transformer.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 function transform(msg: IntuMessage, ctx: IntuContext): IntuMessage {
  const patient = msg.body as { identifier?: Array<{ value?: string }>; name?: Array<{ family?: string; given?: string[] }>; birthDate?: string; gender?: string };

  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", patient.birthDate?.replace(/-/g, "") ?? "");
  adt.set("PID.8", patient.gender === "male" ? "M" : patient.gender === "female" ? "F" : "U");

  return { body: adt.toString() };
}