AWS healthlake documentation change
Summary
Updated documentation for FHIR bundles in AWS HealthLake with expanded explanations of batch vs. transaction bundles, added async transactions feature, improved conditional PUTs documentation, and clarified message bundle limitations
Security assessment
The changes primarily focus on feature documentation improvements and adding new async transaction capabilities. Security-related aspects include: 1) Warning about message bundle type requiring AWS account allowlisting and not enforcing FHIR R4 message semantics or referential integrity, 2) Documentation of SMART on FHIR authorization requirements for async transactions, 3) Clarification that polling results are only available for 90 days. However, there's no evidence of addressing a specific security vulnerability or incident.
Diff
diff --git a/healthlake/latest/devguide/managing-fhir-resources-bundle.md b/healthlake/latest/devguide/managing-fhir-resources-bundle.md index 82746c591..acb2982cb 100644 --- a//healthlake/latest/devguide/managing-fhir-resources-bundle.md +++ b//healthlake/latest/devguide/managing-fhir-resources-bundle.md @@ -5 +5 @@ -Bundle as independent entitiesConditional PUTs in BundlesBundle as a single entityConfiguring validation level for bundlesLimited support for Bundle type "message" +Bundle as independent entitiesConditional PUTsBundle as a single entityConfiguring validation level for bundlesLimited support for Bundle type "message"Async transactions @@ -9 +9 @@ Bundle as independent entitiesConditional PUTs in BundlesBundle as a single enti -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). +A FHIR `Bundle` is a container for a collection of FHIR resources in AWS HealthLake. AWS HealthLake supports two types of bundles with different processing behaviors. @@ -11 +11 @@ A FHIR `Bundle` is a container for a collection of FHIR resources in AWS HealthL - * 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. +[`Batch`](https://hl7.org/fhir/R4/http.html#transaction) bundles process each resource independently. If one resource fails, the remaining resources can still succeed. Each operation is processed individually, and processing continues even when some operations fail. Use batch bundles for bulk operations where partial success is acceptable, such as uploading multiple unrelated patient records. @@ -13 +13 @@ A FHIR `Bundle` is a container for a collection of FHIR resources in AWS HealthL - * 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. +[`Transaction`](https://hl7.org/fhir/R4/http.html#transaction) bundles process all resources atomically as a single unit. Either all resource operations succeed, or AWS HealthLake commits none of them. Use transaction bundles when you need guaranteed referential integrity across related resources, such as creating a patient with related observations and conditions where all data must be recorded together. @@ -14,0 +15,7 @@ A FHIR `Bundle` is a container for a collection of FHIR resources in AWS HealthL +Differences between batch and transaction bundles Feature | Batch | Transaction +---|---|--- +Processing model | Each operation succeeds or fails independently. | All operations succeed or fail as a single atomic unit. +Failure handling | Processing continues even if individual operations fail. | The entire bundle fails if any single operation fails. +Execution order | Execution order is not guaranteed. | Operations are processed in the order specified. +Referential integrity | Not enforced across operations. | Enforced for locally referenced resources within the bundle. +Best used for | Bulk operations where partial success is acceptable. | Related resources that must be created or updated together. @@ -15,0 +23 @@ A FHIR `Bundle` is a container for a collection of FHIR resources in AWS HealthL +You can bundle FHIR resources of the same or different types, and they can include a mix of FHIR operations, such as `create`, `read`, `update`, `delete`, and `patch`. For additional information, see [Resource Bundle](https://hl7.org/fhir/R4/Bundle) in the __FHIR R4 documentation__. @@ -16,0 +25 @@ A FHIR `Bundle` is a container for a collection of FHIR resources in AWS HealthL +The following are example use cases for each bundle type. @@ -18 +27 @@ A FHIR `Bundle` is a container for a collection of FHIR resources in AWS HealthL -You can bundle FHIR resources of the same or different types, and they can include a mix of other FHIR interactions defined in this chapter (e.g. `create`, `read`, `update`, `delete`, and `search`). For additional information, see [Resource Bundle](https://hl7.org/fhir/R4/Bundle) in the __FHIR R4 documentation__. +Batch bundles @@ -20 +28,0 @@ You can bundle FHIR resources of the same or different types, and they can inclu -Key differences between Batch and Transaction type Bundles: @@ -22 +30 @@ Key differences between Batch and Transaction type Bundles: -Batch + * Upload multiple unrelated patient records from different facilities during nightly data synchronization. @@ -23,0 +32 @@ Batch + * Bulk upload historical medication records where some records might have validation issues. @@ -25 +34 @@ Batch - * Independent operations that can succeed or fail individually + * Load reference data, such as organizations and practitioners, where individual failures don't affect other entries. @@ -27 +35,0 @@ Batch - * Processing continues even if some operations fail @@ -29 +36,0 @@ Batch - * Order of execution not guaranteed @@ -31 +37,0 @@ Batch - * Ideal for bulk operations where partial success is acceptable @@ -32,0 +39 @@ Batch +Transaction bundles @@ -34,0 +42 @@ Batch + * Create a patient with related observations and conditions during an emergency department admission where all data must be recorded together. @@ -36 +44 @@ Batch -Transaction + * Update a patient's medication list and related allergy information that must remain consistent. @@ -37,0 +46 @@ Transaction + * Record a complete encounter with the patient, observations, procedures, and billing information as a single atomic unit. @@ -39 +47,0 @@ Transaction - * Atomicity guaranteed - either all succeed or all fail @@ -41 +48,0 @@ Transaction - * Maintains referential integrity for locally referenced (within Bundle) resources @@ -43 +49,0 @@ Transaction - * Operations processed in the order specified @@ -45 +51 @@ Transaction - * Fails completely if any operation fails +###### Important @@ -46,0 +53 @@ Transaction +Both batch and transaction bundles use the same `Bundle` resource structure. The only difference is the value of the `type` field. @@ -48,14 +55 @@ Transaction - - -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: +The following example shows a transaction bundle with multiple resource types and operations. @@ -341 +335 @@ The server returns a response showing the `Patient` and `Medication` resources c -## Conditional PUTs in Bundles +## Conditional PUTs in bundles @@ -343 +337 @@ The server returns a response showing the `Patient` and `Medication` resources c -AWS HealthLake supports conditional updates within Bundles using the following query parameters: +AWS HealthLake supports conditional updates within bundles using the following query parameters: @@ -358,11 +352 @@ AWS HealthLake supports conditional updates within Bundles using the following q -Based on the results of matching the conditions provided to the existing resource, the following will occur with the associated result codes indicating the action taken: - -When creating or updating FHIR resources, the system handles different scenarios based on resource ID provision and existing matches: - - * Resources without IDs are always created (201). - - * Resources with new IDs are created (201). - - * Resources with existing IDs either update the matching resource (200) or return errors if there's a conflict (409) or ID mismatch (400). - - * Multiple matching resources trigger a precondition failure (419). +When you use conditional PUTs in bundles, AWS HealthLake evaluates the query parameters against existing resources and takes action based on the match results. @@ -369,0 +354,8 @@ When creating or updating FHIR resources, the system handles different scenarios +Conditional update behavior Scenario | HTTP status | Action taken +---|---|--- +Resource without ID provided | 201 Created | Always creates a new resource. +Resource with new ID (no match) | 201 Created | Creates a new resource with the specified ID. +Resource with existing ID (single match) | 200 OK | Updates the matching resource. +Resource with existing ID (conflict detected) | 409 Conflict | Returns an error. No changes are made. +Resource with existing ID (ID mismatch) | 400 Bad Request | Returns an error. No changes are made. +Multiple resources match conditions | 412 Precondition Failed | Returns an error. No changes are made. @@ -371,3 +363 @@ When creating or updating FHIR resources, the system handles different scenarios - - -In the example Bundle with conditional update, the Patient resource with FHIR ID `456` will only update if the condition `_lastUpdated=lt2025-04-20` is met. +In the following example bundle with a conditional update, the `Patient` resource with FHIR ID `476` updates only if the condition `_lastUpdated=lt2025-04-20` is met. @@ -637 +627,5 @@ Note that data ingested that is malformed according the R4 specification may not -HealthLake provides limited support for FHIR Bundle type `message` through an internal conversion process. This support is designed for scenarios where message Bundles cannot be reformatted at the source. +HealthLake provides limited support for FHIR Bundle type `message` through an internal conversion process. This support is designed for scenarios where message bundles cannot be reformatted at the source, such as ingesting ADT (Admission, Discharge, Transfer) feeds from legacy hospital systems. + +###### Warning + +This feature requires explicit AWS account allowlisting and does not enforce FHIR R4 message semantics or referential integrity. Contact AWS Support to request enablement for your account before using message bundles. @@ -661,4 +654,0 @@ HealthLake provides limited support for FHIR Bundle type `message` through an in -### Typical use case - -Ingesting ADT (Admission, Discharge, Transfer) feeds from hospital systems that send Bundle type `message` containing related Patient, Encounter, Organization, and Provenance resources. - @@ -694,0 +686,303 @@ Each resource is stored independently as if submitted via individual PUT operati +## Asynchronous bundle transactions + +AWS HealthLake supports asynchronous `Bundle` type `transaction` that allows you to submit transactions with up to 500 resources. When you submit an asynchronous transaction, HealthLake queues it for processing and immediately returns a polling URL. You can use this URL to check the status and retrieve the response. This follows the [FHIR async bundle pattern](https://hl7.org/fhir/async-bundle.html). + +###### When to use asynchronous transactions + + * You need to submit more than 100 resources (synchronous limit) in a single transaction. + + * You want to avoid blocking your application while waiting for transaction processing to complete. + + * You need to process high volumes of related resources with better throughput. + + + + +###### Important + +Polling results are available for 90 days after the transaction is completed. After this 90-day period, the polling URL no longer returns results. Design your integration to retrieve and store results within this window. + +###### Note + +Synchronous `Bundle` type `transaction` continues to support up to 100 resources and is the default processing mode. If you submit a `Bundle` type `transaction` with more than 100 resources without the `Prefer: respond-async` header, HealthLake returns a `422 Unprocessable Entity` error. Bundles with type `batch` are not supported for asynchronous processing—only `Bundle` type `transaction` can be submitted asynchronously (with up to 500 operations). + +### Submitting an asynchronous transaction + +To submit an asynchronous transaction, send a `POST` request to the data store endpoint with the `Prefer: respond-async` header. The bundle must have type `transaction`. Bundles with type `batch` are not supported for asynchronous bundle processing. + +HealthLake does initial validations for the bundle at submission time. If validation succeeds, HealthLake returns HTTP 202 Accepted with a `content-location` response header that contains the polling URL. + +###### To submit an asynchronous `Bundle` type `transaction` + + 1. Send a `POST` request to the HealthLake data store endpoint. + + POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/ + + 2. Construct a JSON body for the request with bundle type `transaction`. For the purpose of this procedure, save the file as `async-transaction.json`. + + { + "resourceType": "Bundle", + "type": "transaction", + "entry": [ + { + "resource": { + "resourceType": "Patient", + "active": true, + "name": [ + { + "use": "official", + "family": "Smith", + "given": ["Jane"] + } + ], + "gender": "female", + "birthDate": "1990-01-15" + }, + "request": { + "method": "POST", + "url": "Patient" + } + }, + { + "resource": { + "resourceType": "Observation", + "status": "final", + "code": { + "coding": [ + { + "system": "http://loinc.org", + "code": "85354-9", + "display": "Blood pressure panel" + }