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 multiple operations such as creating, reading, updating, deleting, patching, searching, retrieving history, versioned reads, and resolving references of FHIR resources.
Common scenarios where this node is beneficial include:
- Managing healthcare data by creating or updating patient records, observations, or other clinical resources.
- Querying FHIR servers for specific resources or search results.
- Deleting obsolete or incorrect resources.
- Applying JSON Patch operations to modify resources partially.
- Resolving references within FHIR resources to retrieve linked data.
- Handling paginated search results by optionally retrieving all pages.
Practical examples:
- Creating a new Patient resource on a FHIR server.
- Searching for all Observation resources matching certain criteria.
- Deleting a specific Encounter resource by its ID.
- Patching an existing CarePlan resource to update some fields.
- Retrieving the history of changes for a MedicationRequest resource.
- Resolving references in a Composition resource to fetch included resources.
Properties
| Name | Meaning |
|---|---|
| Authentication | The method used to authenticate requests to the FHIR server. Options include: 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. |
| Resource Type | The type of FHIR resource to operate on, e.g., Patient, Observation, CarePlan, etc. A comprehensive list of standard FHIR resource types is provided, plus an option for custom resource types. |
| Custom Resource Type | If "Resource Type" is set to "- Custom -", this string specifies the custom resource type name. |
| Operation | The operation to perform on the resource. Supported operations include Create, Delete, History, Patch, Read, Resolve, Search, Update, VRead. |
| ID | The ID of the resource to target for operations that require it (Delete, History, Patch, Read, Update, VRead). |
| Version ID | The version ID of the resource for version-specific read (VRead) operations. |
| Specify Patch Body | For Patch operations, whether to specify the patch body using key-value pairs or raw JSON. |
| Patch Parameters | When specifying patch body as key-value pairs, this collection defines the individual patch operations (op, from, path, value) according to JSON Patch specification. |
| Body | The JSON body of the resource for Create, Patch (if using JSON), or Update operations. |
| 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 to specify query parameters for operations that support them (e.g., Search). Options are key-value pairs or JSON. |
| Query Parameters | When specifying query parameters as key-value pairs, this collection defines the individual parameters (name and value). |
| JSON | When specifying query parameters as JSON, this field contains the JSON object representing the parameters. |
| FHIR Path | A FHIRPath expression to extract specific data from the response output. If specified, the node evaluates this expression against the response and outputs the result instead of the full response. |
| Ignore SSL Issues | Whether to allow connections even if SSL certificate validation fails (e.g., self-signed certificates). |
Output
The node outputs an array of items, each containing:
json: The JSON representation of the FHIR resource or response returned by the FHIR server for the requested operation.pairedItem: Metadata linking the output item to the corresponding input item index.
For Search operations returning Bundles, the node can output multiple items, one per resource entry in the Bundle. It also supports pagination to retrieve all pages of results if configured.
If a FHIRPath expression is specified, the output contains the evaluation result of that expression applied to the response data.
Binary data is not explicitly handled or output by this node.
Dependencies
- Requires access to a FHIR server API endpoint.
- Supports various 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 beyond standard n8n credential configurations are required.
Troubleshooting
Common Issues
- Authentication failures: Ensure correct credentials and authentication method are configured.
- Invalid resource IDs or types: Verify that the resource type and ID exist on the FHIR server.
- Malformed JSON bodies or patch parameters: Validate JSON syntax and patch operations conform to JSON Patch standards.
- Search returning multiple results when only one expected: Use the "Error if More than One Result" property to control behavior.
- SSL certificate errors: Enable "Ignore SSL Issues" if connecting to servers with self-signed or invalid certificates.
Error Messages
- "The operation "
" is not supported" : The selected operation is not implemented; choose a valid operation. - "The search returned more than one result": Occurs if "Error if More than One Result" is enabled and the search returns multiple entries.
- "Unable to find a unit for
" : Related to unit conversion utilities used internally; ensure units are valid UCUM codes. - JSON parsing errors: Check that JSON inputs (body, query parameters) are well-formed.
Links and References
Summary
This node provides comprehensive interaction capabilities with FHIR servers, supporting all common CRUD and query operations on FHIR resources, including advanced features like patching and reference resolution. It is highly configurable with respect to authentication, query parameters, and output filtering via FHIRPath, making it suitable for diverse healthcare integration workflows.