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 common FHIR RESTful operations such as Create, Read, Update, Delete, Patch, History retrieval, Versioned Read, Search, and Resolve references within FHIR resources.
A key feature of this node is the ability to resolve FHIR references: given one or more references (strings or objects), it fetches the referenced resources from the FHIR server. This is useful in healthcare data workflows where linked resources need to be retrieved automatically for further processing.
Common scenarios include:
- Fetching patient records or related clinical data.
- Searching for resources matching specific criteria.
- Resolving references inside FHIR bundles or resources to get full details.
- Applying patches or updates to existing resources.
- Retrieving historical versions or audit trails of resources.
Practical example:
- A workflow that receives a FHIR Bundle containing references to Observations can use the Resolve operation to fetch all referenced Observation resources for detailed analysis.
Properties
| Name | Meaning |
|---|---|
| Authentication | Method of authentication 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 (e.g., http://example.com/fhir). |
| Resource Type | The type of FHIR resource to operate on (e.g., Patient, Observation, Encounter, etc.). |
| Custom Resource Type | If "Resource Type" is set to custom, specify the custom resource type string here. |
| Operation | The FHIR operation to perform: Create, Read, Update, Delete, Patch, History, VRead, Search, Resolve |
| ID | The resource ID (required for operations like Read, Update, Delete, Patch, History, VRead). |
| Version ID | The version ID of the resource (required for VRead operation). |
| Specify Patch Body | For Patch operation, choose whether patch body is specified using fields below or raw JSON. |
| Patch Parameters | Collection of patch operations (op, from, path, value) when specifying patch body via fields. |
| Body | JSON body for Create, Update, or Patch (when specifying patch body as JSON). |
| Reference | For Resolve operation, the reference(s) to resolve. Can be a string, a Reference object, or an array of Reference objects. |
| Specify Query Parameters | How query parameters are specified for Search operation: Using Fields Below or Using JSON. |
| Query Parameters | Key-value pairs of query parameters when specifying query parameters using fields. |
| JSON | Raw JSON query parameters when specifying query parameters using JSON. |
| FHIR Path | Optional FHIRPath expression to extract data from the output. |
| Retrieve All Pages? | For Search operation, whether to retrieve all pages of results (pagination). |
| 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 error if more than one result is returned. |
| Ignore SSL Issues | Whether to ignore SSL certificate validation issues when connecting to the FHIR server. |
Output
The node outputs an array of items, each containing a json field with the FHIR resource data retrieved or affected by the operation.
- For operations returning a single resource (e.g., Read, VRead), the output contains the resource JSON.
- For Search operations, the output contains entries from the search Bundle, each as a separate item.
- For Resolve operation, the output contains the resolved referenced resources as individual items.
- If a FHIRPath expression is specified, the output is filtered accordingly, potentially returning extracted values instead of full resources.
- Binary data is not handled by this node; output is JSON only.
Each output item includes a pairedItem property linking back to the input item index for traceability.
Dependencies
- Requires access to a FHIR server API endpoint.
- Supports multiple authentication methods; user must provide appropriate credentials or tokens.
- Uses internal HTTP request utilities with authentication support.
- Utilizes a FHIRPath evaluation library to process optional FHIRPath expressions on responses.
- Handles pagination for Search operation by following "next" links in Bundles.
- No external environment variables required beyond standard n8n credential configuration.
Troubleshooting
- More than one result error: When "Error if More than One Result" is enabled for Search, if the search returns multiple matching resources, the node throws an error. To fix, either refine the search query or disable this option.
- Invalid JSON in Patch or Query JSON fields: Ensure JSON inputs are valid JSON strings.
- Reference resolution failures: If references cannot be resolved, check that the references are correctly formatted and that the FHIR server has the referenced resources accessible.
- SSL errors: If connecting to servers with self-signed certificates, enable "Ignore SSL Issues".
- Authentication errors: Verify that the selected authentication method and credentials are correct and have sufficient permissions.
- Large result sets: Enabling "Retrieve All Pages?" may cause large data transfers; use with caution.
Links and References
- FHIR Specification
- FHIR RESTful API
- FHIRPath Specification
- UCUM Units
- n8n Documentation - Creating Nodes
Summary of execute() logic
- Reads input data items.
- For each item, reads parameters: base URL, operation, resource type, IDs, query parameters, patch body, references, etc.
- Constructs HTTP request options based on operation and parameters.
- For Resolve operation, extracts references and creates requests for each referenced resource.
- Sends HTTP requests with authentication.
- Processes response:
- For Search with pagination and "Retrieve All Pages?", follows next links to fetch all pages.
- Applies optional FHIRPath expression to filter/extract data.
- Converts Bundle entries into individual output items.
- Returns array of output items with JSON data and paired input item index.
- Handles errors according to "Continue On Fail" setting.
This node provides comprehensive FHIR resource interaction capabilities suitable for healthcare integration workflows requiring flexible FHIR API access and reference resolution.