Lesson 14: FHIR Documents and Messaging

HL7 FHIR - Basic to Advanced Healthcare Data Standard

Part 5: Integration, Messaging and Security

xdev.asia

1. Three Paradigms exchange data in FHIR

Paradigm	Description	Use cases
RESTful APIs	CRUD operations on each Resource	Real-time interactive application
Documents	The Resources collection forms the complete "document".	Discharge summary, transfer papers, medical records
Messaging	Event-driven, sending messages between systems	Hospital admission notice, test results, orders

2. FHIR Documents

FHIR Document is Bundle type "document", the first entry must be Composition, followed by all referenced Resources.

Composition Resource

{
  "resourceType": "Composition",
  "id": "comp-discharge-001",
  "status": "final",
  "type": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "18842-5",
        "display": "Discharge summary"
      }
    ],
    "text": "Tóm tắt xuất viện"
  },
  "subject": {
    "reference": "Patient/patient-001",
    "display": "Nguyễn Văn A"
  },
  "encounter": {
    "reference": "Encounter/encounter-inpatient-001"
  },
  "date": "2025-01-20T16:00:00+07:00",
  "author": [
    {
      "reference": "Practitioner/practitioner-001",
      "display": "BS. Trần Thị B"
    }
  ],
  "title": "Tóm tắt xuất viện - Nguyễn Văn A",
  "custodian": {
    "reference": "Organization/org-bvdk-001"
  },
  "section": [
    {
      "title": "Chẩn đoán",
      "code": {
        "coding": [
          {
            "system": "http://loinc.org",
            "code": "11535-2",
            "display": "Hospital discharge Dx Narrative"
          }
        ]
      },
      "text": {
        "status": "generated",
        "div": "
Tăng huyết áp độ 2, Đái tháo đường type 2
"
      },
      "entry": [
        {"reference": "Condition/cond-hypertension-001"},
        {"reference": "Condition/cond-diabetes-001"}
      ]
    },
    {
      "title": "Thuốc kê đơn khi xuất viện",
      "code": {
        "coding": [
          {
            "system": "http://loinc.org",
            "code": "10183-2",
            "display": "Hospital discharge medications"
          }
        ]
      },
      "entry": [
        {"reference": "MedicationRequest/mr-amlodipine-001"},
        {"reference": "MedicationRequest/mr-metformin-001"}
      ]
    },
    {
      "title": "Kết quả xét nghiệm",
      "code": {
        "coding": [
          {
            "system": "http://loinc.org",
            "code": "30954-2",
            "display": "Relevant diagnostic tests/lab data"
          }
        ]
      },
      "entry": [
        {"reference": "DiagnosticReport/dr-cbc-001"},
        {"reference": "Observation/obs-hba1c-001"}
      ]
    }
  ]
}

Document Bundle

{
  "resourceType": "Bundle",
  "type": "document",
  "identifier": {
    "system": "http://hospital.vn/documents",
    "value": "DOC-20250120-001"
  },
  "timestamp": "2025-01-20T16:00:00+07:00",
  "entry": [
    {
      "fullUrl": "urn:uuid:comp-001",
      "resource": {
        "resourceType": "Composition"
      }
    },
    {
      "fullUrl": "urn:uuid:patient-001",
      "resource": {
        "resourceType": "Patient"
      }
    },
    {
      "fullUrl": "urn:uuid:cond-001",
      "resource": {
        "resourceType": "Condition"
      }
    }
  ]
}

Document Rules

1. Bundle.type = "document"
2. The first entry MUST be Composition
3. All Resources referenced from Composition MUST be in the Bundle
4. Document is immutable after signing
5. Can be digitally signed (signature in Bundle or Provenance)

3. FHIR Messaging

Messaging usage Bundle type "message" with MessageHeader make the first entry.

MessageHeader Resource

{
  "resourceType": "MessageHeader",
  "id": "msg-admission-001",
  "eventCoding": {
    "system": "http://terminology.hl7.org/CodeSystem/message-events",
    "code": "admin-notify"
  },
  "source": {
    "name": "HIS Bệnh viện ĐK TW",
    "endpoint": "https://his.bvdk.vn/fhir/$process-message"
  },
  "destination": [
    {
      "name": "Hệ thống BHXH",
      "endpoint": "https://api.bhxh.gov.vn/fhir/$process-message"
    }
  ],
  "focus": [
    {
      "reference": "Encounter/encounter-inpatient-001"
    },
    {
      "reference": "Patient/patient-001"
    }
  ],
  "reason": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/message-reasons-encounter",
        "code": "admit"
      }
    ],
    "text": "Thông báo nhập viện"
  }
}

Message Bundle

{
  "resourceType": "Bundle",
  "type": "message",
  "timestamp": "2025-01-15T14:30:00+07:00",
  "entry": [
    {
      "fullUrl": "urn:uuid:msg-001",
      "resource": {
        "resourceType": "MessageHeader"
      }
    },
    {
      "fullUrl": "urn:uuid:encounter-001",
      "resource": {
        "resourceType": "Encounter"
      }
    },
    {
      "fullUrl": "urn:uuid:patient-001",
      "resource": {
        "resourceType": "Patient"
      }
    }
  ]
}

Send Message

POST /fhir/$process-message HTTP/1.1
Content-Type: application/fhir+json

{
  "resourceType": "Bundle",
  "type": "message",
  ...
}

4. Compare three paradigms

Criteria	REST	Documents	Messaging
Model	Request/Response CRUD	Immutable package	Event-driven
Coupling	Loose	None (self-contained)	Loose
Atomicity	Transaction bundle	Entire document	Entire message
Routing	URL-based	N/A	Endpoint-based
Timing	Synchronous	N/A	Async or sync
Compatible with HL7 v2	Different model	Similar to CDA	Similar to HL7 v2 messages

5. Summary

• Documents — Composition + Bundle "document", self-contained, immutable, signable

• Messaging — MessageHeader + Bundle "message", event-driven, $process-message

• REST is still the most popular paradigm, but Documents and Messaging are essential for many traditional medical use cases