Publish Box goes here

Source Role Integration

Source Role Integration

Use the source adapter role when your organization supplies care data, but the source system does not implement FHIR Subscriptions.

In this role, the adapter sits between external subscribers and the internal source system.

subscriber party
  -> FHIR Subscription request
source adapter
  -> simple event/data calls
source system

Responsibilities

The source adapter role is responsible for the FHIR Subscription side of the interaction:

• publish supported topics;
• accept FHIR R4 Subscription Backport requests;
• store active subscriptions;
• deduplicate repeated subscriptions for the same endpoint, topic and patient;
• perform the handshake notification;
• receive simple event signals from the source system;
• match events to active subscriptions;
• send event notifications;
• serve the event-specific pull endpoint.

The source system remains responsible for the clinical data:

• store or expose patient data;
• create event data;
• decide that a source event exists;
• expose the data elements that belong to that event;
• keep source-system audit and access controls.

The source system does not need a Subscription endpoint.

Minimum Integration Contract

A source system needs only two capabilities for this prototype.

First, it must signal that an event exists:

POST /source-system/internal/events/heart-failure-daily-check
Content-Type: application/json

{
  "patientId": "hf-patient-001",
  "weightKg": 83.4,
  "dyspnea": "toegenomen kortademigheid bij traplopen",
  "status": "attention-needed"
}

Second, it must let the adapter retrieve the FHIR resources for a specific event. In the prototype this is modeled as simple FHIR search by notification-id:

GET /source-system/fhir/Observation?notification-id={notification-id}
GET /source-system/fhir/QuestionnaireResponse?notification-id={notification-id}

The source adapter then exposes the public notified-pull endpoint:

GET /source-adapter/fhir/$notify-pull?notification-id={notification-id}

Subscription Scope

Subscriptions are scoped by:

• subscriber endpoint;
• topic canonical;
• patient id.

If the same endpoint asks for the same topic and patient again, the adapter returns the existing subscription instead of creating a duplicate. A different patient on the same topic creates a separate subscription.

This is important for operational safety. A retrying client should not accidentally multiply notifications.

Source Event Handling

When the source system signals an event, the adapter:

1. stores or reads the event-specific data references;
2. finds active subscriptions for the event topic and patient;
3. sends an R4 Backport event-notification to each matching subscriber endpoint;
4. includes a related-query URL in the notification;
5. serves only the resources for that notification when the subscriber pulls.

The pull result is intentionally event-specific. It should not return the full patient history. In the heart-failure example it returns only:

• the body-weight Observation;
• the symptom QuestionnaireResponse.

Production Considerations

A production source adapter must add controls that are deliberately small or absent in this prototype:

• authentication of subscriber endpoints;
• authorization per topic, patient and care relationship;
• consent and policy enforcement;
• endpoint allowlisting;
• durable subscription storage;
• retry and dead-letter behavior for failed notifications;
• replay windows and event retention;
• source-system audit correlation;
• validation against national profiles and topic definitions.