AWS healthlake documentation change
Summary
Added detailed documentation about batch vs transaction bundle processing differences and conditional PUT operations in Bundles, including error handling scenarios and example payloads
Security assessment
The changes clarify atomic transaction behavior and conditional updates using parameters like _lastUpdated, which helps prevent race conditions and unintended overwrites. While this improves data integrity patterns, there's no explicit mention of addressing a specific security vulnerability.
Diff
diff --git a/healthlake/latest/devguide/managing-fhir-resources-bundle.md b/healthlake/latest/devguide/managing-fhir-resources-bundle.md index e14cb39a7..b47446285 100644 --- a//healthlake/latest/devguide/managing-fhir-resources-bundle.md +++ b//healthlake/latest/devguide/managing-fhir-resources-bundle.md @@ -5 +5 @@ -Bundle as independent entitiesBundle as a single entity +Bundle as independent entitiesConditional PUTs in BundlesBundle as a single entity @@ -9 +9 @@ Bundle as independent entitiesBundle as a single entity -A FHIR `Bundle` is a container for a collection of FHIR resources in AWS HealthLake. Bundling is performed using a [`batch`](https://hl7.org/fhir/R4/http.html#transaction) interaction in one of the following ways: +A FHIR `Bundle` is a container for a collection of FHIR resources in AWS HealthLake. AWS HealthLake supports two types of bundles with different behaviors: [`batch`](https://hl7.org/fhir/R4/http.html#transaction) or [`transaction`](https://hl7.org/fhir/R4/http.html#transaction). @@ -11 +11 @@ A FHIR `Bundle` is a container for a collection of FHIR resources in AWS HealthL - * FHIR resource changes are processed and logged as independent entities. + * For a 'batch' bundle, each FHIR resource contained in the bundle is processed and logged individually. Each resource operation is treated independently from the other resources. @@ -13 +13 @@ A FHIR `Bundle` is a container for a collection of FHIR resources in AWS HealthL - * FHIR resource changes are processed and logged as a single entity. + * For a ‘transaction’ bundle, all FHIR resources contained in the bundle are processed as an atomic operation. All of the resources in the operation must succeed, or no resource updates in the bundle are committed and stored. @@ -19,0 +20,170 @@ You can bundle FHIR resources of the same or different types, and they can inclu +Key differences between Batch and Transaction type Bundles: + +Batch + + + * Independent operations that can succeed or fail individually + + * Processing continues even if some operations fail + + * Order of execution not guaranteed + + * Ideal for bulk operations where partial success is acceptable + + + + +Transaction + + + * Atomicity guaranteed - either all succeed or all fail + + * Maintains referential integrity for locally referenced (within Bundle) resources + + * Operations processed in the order specified + + * Fails completely if any operation fails + + + + +Example Use Cases: + + * Batch: Uploading multiple unrelated patient records + + * Transaction: Creating a patient with related observations and conditions where all must succeed together + + + + +###### Note + +Both use Bundle resource type but differ in 'type' field: + + + { + "resourceType": "Bundle", + "type": "transaction", + "entry": [ + { + "fullUrl": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065", + "resource": { + "resourceType": "Patient", + "id": "new-patient", + "active": true, + "name": [ + { + "family": "Johnson", + "given": [ + "Sarah" + ] + } + ], + "gender": "female", + "birthDate": "1985-08-12", + "telecom": [ + { + "system": "phone", + "value": "555-123-4567", + "use": "home" + } + ] + }, + "request": { + "method": "POST", + "url": "Patient" + } + }, + { + "fullUrl": "urn:uuid:7f83f473-d8cc-4a8d-86d3-9d9876a3248b", + "resource": { + "resourceType": "Observation", + "id": "blood-pressure", + "status": "final", + "code": { + "coding": [ + { + "system": "http://loinc.org", + "code": "85354-9", + "display": "Blood pressure panel" + } + ], + "text": "Blood pressure panel" + }, + "subject": { + "reference": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065" + }, + "effectiveDateTime": "2023-10-15T09:30:00Z", + "component": [ + { + "code": { + "coding": [ + { + "system": "http://loinc.org", + "code": "8480-6", + "display": "Systolic blood pressure" + } + ] + }, + "valueQuantity": { + "value": 120, + "unit": "mmHg", + "system": "http://unitsofmeasure.org", + "code": "mm[Hg]" + } + }, + { + "code": { + "coding": [ + { + "system": "http://loinc.org", + "code": "8462-4", + "display": "Diastolic blood pressure" + } + ] + }, + "valueQuantity": { + "value": 80, + "unit": "mmHg", + "system": "http://unitsofmeasure.org", + "code": "mm[Hg]" + } + } + ] + }, + "request": { + "method": "POST", + "url": "Observation" + } + }, + { + "resource": { + "resourceType": "Appointment", + "id": "appointment-123", + "status": "booked", + "description": "Annual physical examination", + "start": "2023-11-15T09:00:00Z", + "end": "2023-11-15T09:30:00Z", + "participant": [ + { + "actor": { + "reference": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065" + }, + "status": "accepted" + } + ] + }, + "request": { + "method": "PUT", + "url": "Appointment/appointment-123" + } + }, + { + "request": { + "method": "DELETE", + "url": "MedicationRequest/med-request-456" + } + } + ] + } + @@ -170,0 +341,135 @@ The server returns a response showing the `Patient` and `Medication` resources c +## Conditional PUTs in Bundles + +AWS HealthLake supports conditional updates within Bundles using the following query parameters: + + * `_id` (standalone) + + * `_id` in combination with one of the following: + + * `_tag` + + * `_createdAt` +