A FHIR Bundle is fundamentally a resource that groups multiple entries, each of which can contain any type of FHIR resource (like Patient, Bundle, Observation, or Medication). This packaging of resources can serve numerous purposes — from transactions and batch operations to document compilations and message exchanges.
Developers new to FHIR may find it difficult to navigate the complexity of FHIR, including using bundles. This article will explain the idea and practical uses of FHIR Bundles, helping developers understand how to incorporate them into their FHIR projects. We aim to speed up the learning process and promote better implementation of FHIR-based solutions through a strong foundation.
Highlights:
- HL7 FHIR Bundles are versatile containers with various resources to serve multiple purposes across healthcare systems. They are crucial for transactions, batch operations, document compilations, and message exchanges.
- There are several types of bundles in FHIR: Document, Message, Transaction, Batch, and Search/History — each designed for specific uses, from managing clinical documents to facilitating information exchange between systems.
- Implementing FHIR Bundles can significantly improve data management practices in healthcare by enabling efficient data migration, EHR system synchronization, and regulatory reporting.
Types of FHIR Bundles
The FHIR specification outlines several types of bundles, each tailored for specific operations:
- Document Bundles: These are structured compilations of resources that collectively represent a coherent clinical document. An example of a document bundle would include a discharge summary or a referral letter.
- Message Bundles: These facilitate the exchange of information between systems, like notification of a new patient record or a laboratory result.
- Transaction/Batch Response Bundles: A significant addition involves explaining how responses are managed in transaction and batch operations. In a transaction-response or batch-response bundle, each entry corresponds to an entry in the original transaction or batch and includes a response element, indicating the outcome of the HTTP operation performed by the server. This detail clarifies how responses are structured and should be handled when using transaction or batch bundles.
- Collection Bundles: Another type to highlight is the collection bundle, which comprises a series of entries with no specific use defined in the FHIR specification beyond containing resources. This bundle type is versatile for general data collection without transactional or batch processing constraints.
- Search/History Bundles: Generated in response to a search or history query, these bundles contain entries that match the search criteria or historical versions of a specific resource.
How to Use and Create FHIR Bundles
Bundle Endpoints and Interaction
It’s crucial to understand that the bundle resource type interacts with the system like most other resources. When bundles are POSTed to the /Bundle endpoint, they are stored as static resources, and the content is not processed as batch or transaction operations. Instead, they are treated like normal resources and are subject to indexing and auditing. Performing a GET request on /Bundle/[location] retrieves the same resource, emphasizing the standard RESTful behavior of the Bundle endpoint.
Resolving References in Bundles
Resolving references within a bundle, particularly for transaction types, is complex but critical when working with FHIR Bundles.
If the reference is relative (like [type]/[id]), the process involves trying to resolve it both as a relative and an absolute URL using the root URL reference in the bundle and the database.
- If the URL is an absolute URL that doesn’t start with the root URL, it is not resolved.
- If the URL is an urn:uuid URL, it is resolved within the bundle and changed to the relative reference of the entry in the bundle.
- If the reference is conditional, it is searched for in the database and changed to a relative reference when saving the resource from the FHIR Bundle.
A FHIR Bundle consists of several key components:
- ResourceType: This is always set to Bundle.
- Type: Defines the intent of the bundle (e.g., document, message, transaction, batch, searchset, history).
- Entry: A list of entries where each entry contains a resource and optional request or response information related to the resource.
Here’s the HL7 FHIR Bundle example in JSON:
{
"resourceType": "Bundle",
"id": "b28518e0-2132-4fef-b56f-866167566c6e",
"type": "transaction",
"entry": [
{
"fullUrl": "https://demo.kodjin.com/fhir/Patient/671382cb-65ad-48e7-85af-2b2f612a0beb",
"resource": {
"resourceType": "Patient",
"id": "671382cb-65ad-48e7-85af-2b2f612a0beb",
"meta": {
"source": "671382cb-65ad-48e7-85af-2b2f612a0beb",
"versionId": "1"
},
"active": true,
"name": [
{
"use": "official",
"text": "Stepan Spring",
"family": "Spring",
"given": [
"Stepan"
]
}
],
"telecom": [
{
"system": "email",
"value": "[email protected]",
"use": "work"
}
],
"gender": "male",
"managingOrganization": {
"reference": "urn:uuid:a551ab84-df6f-4a47-a9ae-76c6046d6698"
}
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"fullUrl": "urn:uuid:a551ab84-df6f-4a47-a9ae-76c6046d6698",
"resource": {
"resourceType": "Organization",
"name": "Health Level Seven International",
"alias": [
"HL7 International"
],
"telecom": [
{
"system": "phone",
"value": "(+1) 734-677-7777"
}
],
"address": [
{
"line": [
"3300 Washtenaw Avenue, Suite 227"
],
"city": "Ann Arbor",
"state": "MI",
"postalCode": "48104",
"country": "USA"
}
]
},
"request": {
"method": "POST",
"url": "Organization"
}
}
]
}
The response from the server for this FHIR patient bundle would be:
{
"resourceType": "Bundle",
"type": "transaction-response",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "f54d2119-8afe-4827-86af-8d921b018e57",
"meta": {
"source": "f54d2119-8afe-4827-86af-8d921b018e57",
"versionId": "1",
"lastUpdated": "2024-09-19T12:19:30.667987876+00:00"
},
"active": true,
"name": [
{
"use": "official",
"text": "Stepan Spring",
"family": "Spring",
"given": [
"Stepan"
]
}
],
"telecom": [
{
"system": "email",
"value": "[email protected]",
"use": "work"
}
],
"gender": "male",
"managingOrganization": {
"reference": "Organization/8919e13f-e35d-4cc3-810b-6e2f1b7979e6"
}
},
"response": {
"status": "201 Created",
"location": "https://demo.kodjin.com/fhir/Patient/f54d2119-8afe-4827-86af-8d921b018e57/_history/1",
"etag": "W/\"1\"",
"lastModified": "2024-09-19T12:19:30.667987876+00:00"
}
},
{
"resource": {
"resourceType": "Organization",
"name": "Health Level Seven International",
"alias": [
"HL7 International"
],
"telecom": [
{
"system": "phone",
"value": "(+1) 734-677-7777"
}
],
"address": [
{
"line": [
"3300 Washtenaw Avenue, Suite 227"
],
"city": "Ann Arbor",
"state": "MI",
"postalCode": "48104",
"country": "USA"
}
],
"id": "8919e13f-e35d-4cc3-810b-6e2f1b7979e6",
"meta": {
"versionId": "1",
"lastUpdated": "2024-09-19T12:19:30.666133205+00:00"
}
},
"response": {
"status": "201 Created",
"location": "https://demo.kodjin.com/fhir/Organization/8919e13f-e35d-4cc3-810b-6e2f1b7979e6/_history/1",
"etag": "W/\"1\"",
"lastModified": "2024-09-19T12:19:30.666133205+00:00"
}
}
]
}
Step-by-Step Guide to Creating FHIR Bundles
“When working with bundles, it’s important to ensure that they conform to specific requirements, often captured in FHIR Bundle Profiles. These profiles (e.g., US Core, UK Core, Da Vinci Profiles, etc.) define how bundles should be structured and provide constraints tailored to particular workflows or use cases.”
Sveta Medved, Business Analyst at Edenlab
1. Determine the Bundle Type: Determine what bundle you need based on your operation. For instance, use transaction for multiple CRUD operations in a single API request or document for a collection of resources representing a clinical document.
2. Assemble Resources: Gather all the resources that need to be included in the bundle. Each resource will be an entry in the bundle.
3. Set Entry Details:
- URI: This is a unique identifier for the resource within the bundle. It can be a URL server address, URI for UUID/OID, etc.
- Resource: The actual FHIR resource data (e.g., Patient, Observation).
- Request: Depending on the bundle type, include request information (for transaction or batch types), specifying the HTTP method and/or FHIR operations (POST, PUT, DELETE) and the resource URL.
4. Add Metadata: Optionally, you can add metadata such as signature for security purposes.
5. How to Validate a FHIR Bundle:
Server-side validation: FHIR servers, including Kodjin, typically validate the bundle when submitted, ensuring that it complies with the FHIR specification and that the included resources are valid.
Client-side validation: Before sending the bundle to a FHIR server, you can validate it using the Kodjin Profile Editor or community tools. Client-side validation is a good practice to catch errors early.
Practical Use Cases of FHIR Bundles
Implementing FHIR Bundles can enhance data management practices in healthcare settings. Here are several practical scenarios:
- EHR System Synchronization: Bundles can synchronize patient records across different electronic health record (EHR) systems, ensuring that healthcare providers have up-to-date and complete patient information.
- Data Migration: When transitioning between health IT systems, bundles offer a structured way to migrate data in bulk, maintaining data integrity.
- Regulatory Reporting: Bundles can be used to compile required reports, such as for quality improvement and regulatory compliance, streamlining the data aggregation process.
Conclusion
For more detailed technical guidance and examples, the official FHIR documentation provides an extensive resource for developers to dive deeper into the specifics of various bundle types and their applications in healthcare data management.
See our Kodjin documentation for information on how bundles work in the Kodjin FHIR Server.
FAQs
1. What are the different types of FHIR Bundles?
The main types of FHIR Bundles include Document, Message, Transaction, Batch, Collection, and Search/History Bundles. Each serves specific purposes, such as document compilation, system messaging, data operations, or search results.
2. How can I validate a FHIR Bundle?
FHIR Bundles can be validated server-side using a FHIR server like Kodjin, which checks compliance with the FHIR specification. You can also perform client-side validation using tools to catch errors before submission.
3. What are some common uses of FHIR Bundles in healthcare?
FHIR Bundles are commonly used for EHR system synchronization, bulk data migration, and regulatory reporting, ensuring data is consistent, structured, and ready for compliance.
4. What support do you offer for FHIR Bundle implementation and ongoing management?
The Kodjin FHIR Server offers comprehensive support for FHIR Bundle implementation, including built-in validation against bundle profiles to ensure compliance with FHIR standards and specific business needs. Our team provides technical assistance, detailed documentation, and resources to guide developers through creating, structuring, and managing FHIR Bundles.
