Overview
The node named "bonFHIR" is designed to perform various operations on FHIR (Fast Healthcare Interoperability Resources) resources by interacting with a FHIR server API. It supports multiple operations such as creating, reading, updating, deleting, searching, patching, retrieving history, versioned reads, and resolving references of FHIR resources.
A key feature is the ability to resolve FHIR references, which means it can fetch the actual resource(s) pointed to by one or more reference strings or objects. This is particularly useful in healthcare data workflows where resources often reference other resources, and you need to retrieve the full linked data.
Common scenarios include:
- Fetching a specific FHIR resource by ID.
- Searching for resources with query parameters.
- Resolving references within a resource to obtain related resources.
- Applying patches or updates to existing resources.
- Handling paginated search results automatically.
Practical example:
- You have a Patient resource that contains references to Practitioner resources (e.g., primary care provider). Using the "Resolve" operation, you can input these references and retrieve the full Practitioner resources for further processing or analysis.
Properties
| Name | Meaning |
|---|---|
| Authentication | The method used to authenticate requests to the FHIR server. Options: Basic Auth, Custom Auth, Digest Auth, Header Auth, None, OAuth1, OAuth2, Query Auth. |
| Base URL | The base URL of the FHIR server API to which requests are sent. |
| Resource Type | The type of FHIR resource to operate on (e.g., Patient, Observation, Encounter). |
| Custom Resource Type | A custom resource type string if "Resource Type" is set to "- Custom -". |
| Operation | The operation to perform: Create, Read, Update, Delete, Search, Patch, History, VRead, Resolve. |
| Retrieve All Pages? | For Search operation: whether to retrieve all pages of results automatically. |
| Normalize Next URL to Base URL | For Search operation with pagination: whether to normalize next page URLs to the base URL. |
| Error if More than One Result | For Search operation: whether to throw an error if more than one result is returned. |
| ID | The ID of the resource (required for operations like Read, Update, Delete, Patch, VRead). |
| Version ID | The version ID of the resource (required for VRead operation). |
| Specify Patch Body | For Patch operation: whether the patch body is specified using fields below or raw JSON. |
| Patch Parameters | For Patch operation when specifying patch body via fields: list of JSON Patch operations (op, from, path, value). |
| Body | The JSON body for Create, Update, or Patch (when specifying patch body as JSON). |
| Reference | For Resolve operation: a string, a Reference object, or an array of Reference objects to resolve. |
| Specify Query Parameters | For Search operation: whether query parameters are specified as key-value pairs or as JSON. |
| Query Parameters | For Search operation when specifying query parameters as key-value pairs: list of name-value pairs. |
| JSON | For Search operation when specifying query parameters as JSON: raw JSON object. |
| FHIR Path | A FHIRPath expression to extract data from the output. |
| Ignore SSL Issues | Whether to allow connections even if SSL certificate validation fails. |
Output
The node outputs an array of items, each containing a json field with the resulting FHIR resource(s) or data extracted via FHIRPath. Specifically:
- For most operations, the output
jsoncontains the FHIR resource or response returned by the FHIR server. - For Search operations, the output includes entries from the Bundle resource, potentially across multiple pages if "Retrieve All Pages?" is enabled.
- For Resolve operation, the output contains the resolved referenced resources corresponding to the input references.
- If a FHIRPath expression is provided, the output will be the evaluation result of that expression on the response.
- Binary data is not explicitly handled or output by this node.
Each output item also includes a pairedItem property indicating the index of the input item it corresponds to.
Dependencies
- Requires access to a FHIR server API endpoint.
- Supports various authentication methods; appropriate credentials or tokens must be configured in n8n.
- Uses internal utilities for HTTP requests with authentication handling.
- Utilizes a FHIRPath evaluation library to process FHIRPath expressions.
- No external environment variables beyond standard n8n credential configurations are required.
Troubleshooting
Common Issues
- Invalid Base URL: Ensure the FHIR server base URL is correct and accessible.
- Authentication Failures: Verify that the selected authentication method is correctly configured and credentials are valid.
- Reference Resolution Errors: Input references must be valid FHIR references; invalid or missing references will cause errors or empty results.
- Pagination Handling: When retrieving all pages, large result sets may cause performance issues or timeouts.
- Malformed JSON Inputs: For JSON inputs (body or query), ensure valid JSON syntax to avoid parsing errors.
- Error if More than One Result: If enabled, the node throws an error when a search returns multiple results; disable if multiple results are expected.
Common Error Messages
"The operation \"<operation>\" is not supported": Indicates an unsupported operation was selected."The search returned more than one result": Occurs if "Error if More than One Result" is enabled and multiple results are found."JSON parameter need to be a valid JSON": Indicates invalid JSON input in query or body parameters.- Network or SSL errors: May occur if the server is unreachable or SSL certificates are invalid; can be bypassed by enabling "Ignore SSL Issues" but use with caution.
Links and References
- FHIR Specification
- FHIRPath Specification
- n8n Documentation
- UCUM Units of Measure
- BonFHIR GitHub Repository (for icon and additional info)
Summary
This node provides comprehensive interaction capabilities with FHIR servers, including resource CRUD operations, search with pagination, and reference resolution. It supports flexible authentication and allows extraction of specific data via FHIRPath. It is ideal for healthcare automation workflows requiring integration with FHIR-compliant systems.