Overview
This 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 operations such as creating, reading, updating, deleting, patching, searching, retrieving history, versioned reads, and resolving references within FHIR resources.
Typical use cases include:
- Creating new FHIR resources on a FHIR server.
- Reading or updating existing FHIR resources.
- Searching for resources with specific criteria.
- Patching resources using JSON Patch.
- Resolving references to other FHIR resources.
- Retrieving the history of changes to a resource.
- Accessing specific versions of a resource.
Practical examples:
- Creating a new Patient resource with specified details.
- Searching for all Observation resources matching certain parameters.
- Updating an Encounter resource with new information.
- Resolving a Reference field in a resource to fetch the referenced resource.
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 will be sent. Example: http://example.com/fhir. |
| Resource Type | The type of FHIR resource to operate on. Includes standard FHIR resource types like Patient, Observation, Encounter, etc., and also allows specifying a custom resource type string. |
| Custom Resource Type | If "Resource Type" is set to "- Custom -", this string specifies the custom resource type name. |
| Body | The JSON body content for Create, Patch, or Update operations. For Patch, it can be a JSON Patch array or key-value pairs depending on "Specify Patch Body". |
| Patch Parameters | A collection of JSON Patch operations (add, copy, move, remove, replace, test) used when "Specify Patch Body" is set to "Using Fields Below". Each parameter includes operation type, from path, target path, and value. |
| Specify Query Parameters | How query parameters are specified for Search operations: either as key-value pairs or as a raw JSON object. |
| Query Parameters | Key-value pairs representing query parameters for Search operations when "Specify Query Parameters" is set to "Using Fields Below". |
| JSON | Raw JSON object representing query parameters for Search operations when "Specify Query Parameters" is set to "Using JSON". |
| FHIR Path | A FHIRPath expression to extract specific data from the response output. |
| Ignore SSL Issues | Whether to allow connections even if SSL certificate validation fails (e.g., self-signed certificates). |
| Operation | The FHIR operation to perform: Create, Read, Update, Delete, Patch, Search, History, VRead, Resolve. |
| ID | The ID of the resource to operate on (required for operations like Read, Update, Delete, Patch, History, VRead). |
| Version ID | The version ID of the resource (used for VRead operation). |
| Specify Patch Body | For Patch operation, whether to specify the patch body using key-value pairs or raw JSON. |
| Reference | For Resolve operation, the reference(s) to resolve. Can be a string, a Reference object, or an array of Reference objects. |
| 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 the next page URL to the base URL. Useful if the next URL uses a different base URL. |
| Error if More than One Result | For Search operation, whether to throw an error if more than one result is returned. |
Output
The node outputs an array of items where each item contains:
json: The JSON representation of the FHIR resource(s) returned or affected by the operation.pairedItem: Metadata linking the output to the input item index.
For Search operations returning Bundles, the node extracts individual resources from the Bundle entries and outputs them as separate items.
If a FHIRPath expression is specified, the node evaluates it against the response and outputs the extracted data instead of the full resource.
Binary data is not explicitly handled or output by this node.
Dependencies
- Requires access to a FHIR server API endpoint.
- Supports multiple authentication methods; appropriate credentials or tokens must be configured in n8n.
- Uses internal libraries for HTTP requests with authentication handling.
- Utilizes a FHIRPath evaluation library to process FHIRPath expressions.
- No external environment variables are required beyond standard n8n credential configurations.
Troubleshooting
Common issues:
- Incorrect or missing Base URL leading to connection errors.
- Authentication failures due to invalid or missing credentials.
- Invalid resource type or operation causing API errors.
- Malformed JSON in the Body or Query Parameters fields.
- For Search operations, large result sets may cause performance issues if "Retrieve All Pages?" is enabled.
- FHIRPath expressions that do not match any data will result in empty outputs.
Error messages:
"The operation \"<operation>\" is not supported": Occurs if an unsupported operation is selected."The search returned more than one result (<count>)": Thrown if "Error if More than One Result" is enabled and the search returns multiple matches.- JSON parsing errors for invalid JSON inputs in Body or Query Parameters.
- Network or SSL errors if the server is unreachable or SSL validation fails (unless "Ignore SSL Issues" is enabled).
Resolutions:
- Verify Base URL and network connectivity.
- Ensure correct and valid credentials are configured.
- Validate JSON inputs before running the node.
- Use FHIRPath tester tools to validate expressions.
- Enable "Ignore SSL Issues" only if you trust the server's certificate.
Links and References
- FHIR Specification
- FHIR RESTful API
- FHIRPath Specification
- JSON Patch RFC 6902
- n8n Documentation - Creating Custom Nodes
- UCUM Units of Measure (used internally for unit validation)
Summary
This node provides comprehensive support for interacting with FHIR servers, enabling users to perform CRUD and other common FHIR operations with flexible authentication and query options. It integrates FHIRPath evaluation for advanced data extraction and supports pagination for search results. Proper configuration of authentication and careful construction of request bodies and queries are essential for successful operation.