FHIR Transaction Bundle

The defining characteristic of a Transaction Bundle is its all-or-nothing processing model. The server processes all entries in the bundle as a single atomic unit. If any single interaction fails—due to a validation error, a reference integrity issue, or a business rule violation—the entire transaction is rolled back. No partial changes are persisted, ensuring the server's state remains consistent. This is critical for workflows like admitting a patient, which requires creating an Encounter, a Condition, and a Provenance record simultaneously.

Transaction Bundles support conditional references, allowing a client to link resources without knowing their final server-assigned IDs in advance. A placeholder identifier is used within the bundle, and the server resolves it during processing. For example:

• A newly created Patient resource can be assigned a temporary UUID like urn:uuid:04121321-4af5-424c-a0e1-ed3aab1c349d.
• A subsequent Observation in the same bundle can reference that patient using the same temporary UUID.
• The server resolves all internal references atomically, replacing placeholders with permanent IDs.

Instead of using direct resource IDs, a transaction can use conditional interactions based on search criteria. This enables idempotent operations:

• Conditional Create: If-None-Exist header prevents duplicate resource creation. For example, only create a new Patient if no existing patient matches a specific MRN (Medical Record Number).
• Conditional Update: The server updates a resource only if it matches specific search parameters, avoiding the need to first query for the resource's logical ID.
• Conditional Delete: Removes a resource identified by search criteria rather than a direct ID.

A Transaction Bundle differs fundamentally from a Batch Bundle in its execution contract:

• Transaction: Entries are processed in order, and the entire set must succeed or fail as one. Dependencies between entries are enforced.
• Batch: Entries are processed independently. The failure of one entry does not affect others. The server may process entries in any order.
• Use a Transaction when data integrity across multiple resources is required. Use a Batch for independent operations like loading bulk reference data where partial success is acceptable.

Upon completion, the server returns a Bundle of type transaction-response with one entry for each entry in the request, in the same order. Each response entry contains:

• The HTTP status code for that specific operation (e.g., 201 Created, 200 OK).
• The Location header with the final resource ID for created resources.
• An OperationOutcome resource if that specific entry failed, detailing validation errors. This granular response allows the client to understand exactly what happened, even though the transaction as a whole failed and was rolled back.

The server enforces strict integrity rules during transaction processing:

• Referential Integrity: All internal references must resolve within the bundle or to pre-existing resources on the server. Dangling references cause the entire transaction to fail.
• Profile Validation: Each resource is validated against its declared FHIR Profile. A resource that fails profile constraints will cause a rollback.
• Business Rules: Server-specific invariants and business logic are applied. For example, a rule preventing two active MedicationRequest resources for the same drug on the same patient would trigger a failure.
• Concurrency Control: Servers typically use optimistic locking via the ETag/If-Match header to prevent lost updates when modifying existing resources within a transaction.