fetching-fhir-resources

# Fetching FHIR R4 Resources for OpenMed FHIR R4 is the modern EHR API: a RESTful, JSON-or-XML interface over resources like `Patient`, `Encounter`, `Condition`, `Observation`, `DiagnosticReport`, and `DocumentReference`. The unstructured clinical text you want for NLP lives in **`DocumentReference.content.attachment`** and **`DiagnosticReport.presentedForm`** — usually **base64-encoded** PDF, RTF, or plain text. This skill pulls those resources, pages through results, decodes the attachments, and hands the narrative to OpenMed. ## When to use - You have FHIR R4 access to an EHR (Epic, Oracle Health/Cerner, HAPI, Medplum, Azure/Google/AWS HealthLake) and want note text for de-id and NER. - You need to page a large search result set safely (`Bundle.link[next]`). - You want to pull a patient's documents/reports and rejoin NLP output by patient and encounter. ## FHIR REST in one minute Search is `GET [base]/[Type]?param=value`. Results come back as a **searchset `Bundle`**; the next page is the URL in `Bundle.link` where `relation == "next"`. Use `_count` to size pages, `_revinclude` to pull related resources in one round trip, and `_since`/`_lastUpdated` for incremental sync. ``` GET /Patient?identifier=http://hospital.org/mrn|12345 GET /DocumentReference?patient=Patient/abc&category=clinical-note&_count=50 GET /DiagnosticReport?patient=Patient/abc&_revinclude=Observation:related ``` ## Quick start Page a search, decode attachments, hand narrative to OpenMed: ```python import base64 import requests import openmed BASE = "https://fhir.example.org/r4" HEADERS = {"Accept": "application/fhir+json", "Authorization": "Bearer <token>"} def iter_bundle(url, params=None): """Yield resources across all pages following Bundle.link[next].""" while url: bundle = requests.get(url, params=params, headers=HEADERS, timeout=30).json() for entry in bundle.get("entry", []): yield entry.get("resource", {}) params = None # next links are fully-qualified url = next( (l["url"] for l in bundle.get("link", []) if l.get("relation") == "next"), None, ) def attachment_text(att): """Decode a FHIR Attachment to text (handles base64 and inline text/plain).""" if att.get("data"): raw = base64.b64decode(att["data"]) if att.get("contentType", "").startswith("text/"): return raw.decode("utf-8", "replace") return "" # PDF/RTF: route to OpenMed multimodal/OCR intake instead return "" # Pull a patient's clinical notes and analyze each. for doc in iter_bundle(f"{BASE}/DocumentReference", {"patient": "Patient/abc", "category": "clinical-note", "_count": 50}): for content in doc.get("content", []): text = attachment_text(content.get("attachment", {})) if not text.strip(): continue deid = openmed.deidentify(text, method="replace", policy="hipaa_safe_harbor") result = openmed.analyze_text(deid.text, output_format="dict") patient_ref = doc.get("subject", {}).get("reference") # rejoin key ``` ## Workflow 1. **Authenticate.** Most production FHIR endpoints use SMART-on-FHIR OAuth2 (client-credentials for backend services). Scope to the minimum (`system/DocumentReference.read`, `system/DiagnosticReport.read`). 2. **Search narrowly.** Filter by `patient`, `category`, `type` (LOINC), `date`, and `_count`. Prefer server-side filtering over client-side. 3. **Page** via `Bundle.link[next]` until exhausted. Never assume one page. 4. **Extract narrative:** `DocumentReference.content.attachment` and `DiagnosticReport.presentedForm`. Decode base64; for PDF/RTF/scanned content, route bytes to OpenMed's document intake (`multimodal`/`ocr`) rather than decoding as UTF-8. 5. **De-identify → analyze** each narrative with OpenMed. 6. **Rejoin** results to `subject.reference` (patient) and `context.encounter` so downstream consumers can group by patient/encounter — storing hashed, not raw, identifiers. ## Hand-off to / from OpenMed - **To OpenMed (client-side):** decoded narrative → `openmed.deidentify` → `openmed.analyze_text`. Carry `subject.reference` as the rejoin key. - **Server-side `$de-identify`:** `openmed.interop.fhir_operations` implements the FHIR `$de-identify` *operation logic* over the OpenMed privacy pipeline: - `de_identify_resource(resource, policy=..., method=...)` - `de_identify_bundle(bundle, policy=..., method=...)` - `de_identify(parameters)` — accepts/returns a `Parameters` envelope and reports modified element paths as an `OperationOutcome`. It de-identifies free-text strings, identifier values, and `text.div` narrative while never altering codes, references, systems, or temporal values. Use this to de-identify a whole fetched Bundle before storage: ```python from openmed.interop.fhir_operations import de_identify_bundle safe_bundle = de_identify_bundle(bundle, policy="hipaa_safe_harbor", method="replace") ``` - **Onward:** re-export structured findings with `openmed.clinical.exporters.fhir` (`to_bundle`, `to_operation_outcome`). ## Edge cases & gotchas - **Attachments are often base64.** `attachment.data` is base64; large files use `attachment.url` (a separate Binary fetch) instead. Handle both. - **Non-text content types.** `application/pdf`, `text/rtf`, scanned TIFF — do not `utf-8` decode these; send bytes to OpenMed multimodal/OCR intake. - **Pagination loops.** Some servers emit cyclic or stale `next` links; cap page count and dedupe by resource `id`. - **`_revinclude` vs `_include`.** `_include` pulls referenced resources; `_revinclude` pulls resources that *reference* yours. Mixing them changes Bundle entry `search.mode` (`match` vs `include`) — filter on it. - **Versioning & profiles.** Confirm the server is R4 (`/metadata` CapabilityStatement) and US Core-conformant; field cardinality differs across FHIR versions. - **Throttling.** Respect `429`/`Retry-After`; batch with `_count` and back off. - **PHI everywhere.** A FHIR resource is PHI by definition — never log raw resources; de-identify before persistence or analytics. ## Standards & references - FHIR R4 specification: https://hl7.org/fhir/R4/ - FHIR RESTful API & search: https://hl7.org/fhir/R4/http.html and https://hl7.org/fhir/R4/search.html - US Core Implementation Guide: https://hl7.org/fhir/us/core/ - DocumentReference: https://hl7.org/fhir/R4/documentreference.html - DiagnosticReport (`presentedForm`): https://hl7.org/fhir/R4/diagnosticreport.html - SMART on FHIR (backend services auth): https://hl7.org/fhir/smart-app-launch/