Overview
This node provides comprehensive interaction with FHIR (Fast Healthcare Interoperability Resources) servers, focusing here on the Search operation for the Default resource. It allows users to perform searches against a specified FHIR server's API endpoint, retrieving resources based on query parameters. The node supports advanced features such as pagination handling (retrieving all pages of results), normalization of next-page URLs, and conditional error throwing when multiple results are returned but only one is expected.
Common scenarios include:
- Querying patient records or clinical data from a FHIR server.
- Retrieving all matching resources across paginated responses.
- Extracting specific data using FHIRPath expressions from search results.
- Integrating FHIR data retrieval into automated workflows.
Practical example:
- Searching for all Patient resources with a given family name, retrieving all pages of results, and extracting only the patient names using a FHIRPath expression.
Properties
| Name | Meaning |
|---|---|
| Authentication | Method of authentication to use when connecting 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. |
| Retrieve All Pages? | Boolean flag indicating whether to retrieve all pages of search results automatically. Use with caution as this may result in large data sets. |
| Normalize Next URL to Base URL | When retrieving all pages, this option attempts to normalize the "next" page URL to the base URL if they differ, ensuring consistent API calls. |
| Error if More than One Result | If enabled, the node throws an error when a search returns more than one result in the Bundle, useful when expecting a single resource. |
| Resource Type | The type of FHIR resource to search for, e.g., Patient, Observation, Condition, 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 to search for. |
| Specify Query Parameters | Choose how to specify query parameters: either as key-value pairs or as a raw JSON object. |
| Query Parameters | Key-value pairs representing query parameters to include in the search request URL. |
| JSON | Raw JSON object specifying query parameters for the search request. |
| FHIR Path | A FHIRPath expression used to extract or transform data from the search response before outputting. |
| 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 where each item contains a json field holding the FHIR resource(s) retrieved by the search operation. If the search returns a Bundle, it extracts individual resources from the Bundle entries and outputs them separately, preserving their original structure.
If a FHIRPath expression is specified, the output reflects the evaluation of that expression on the response data, potentially transforming or filtering the results.
Binary data is not handled by this node; all outputs are JSON representations of FHIR resources or extracted data.
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 support.
- Utilizes a FHIRPath evaluation library to process FHIRPath expressions.
- No external environment variables are explicitly required beyond those needed for authentication.
Troubleshooting
- Error if More than One Result: If enabled and the search returns multiple resources, the node throws an error. To resolve, either disable this option or refine the search query to ensure a single result.
- Pagination Issues: When retrieving all pages, if the "next" link uses a different base URL, enabling "Normalize Next URL to Base URL" can help avoid request failures.
- Invalid Query Parameters: Ensure query parameters are correctly specified either as key-value pairs or valid JSON. Malformed JSON will cause errors.
- Authentication Failures: Verify that the selected authentication method is supported by the FHIR server and that credentials are correctly configured.
- SSL Certificate Errors: If connecting to servers with self-signed or invalid certificates, enable "Ignore SSL Issues" to bypass validation.
- FHIRPath Expression Errors: Invalid FHIRPath expressions will cause evaluation errors. Validate expressions independently if issues arise.
Links and References
Summary of execute() logic (for Search operation):
- Reads input data items.
- For each item, constructs HTTP request options based on node parameters (base URL, resource type, query parameters, etc.).
- Sends the search request to the FHIR server with proper authentication.
- If "Retrieve All Pages?" is enabled, follows the "next" links in Bundle responses to fetch all pages.
- Optionally normalizes "next" URLs to the base URL.
- Applies FHIRPath expression if specified to extract or transform data.
- Throws error if "Error if More than One Result" is enabled and multiple results are found.
- Outputs each resource or extracted element as a separate item in the workflow output.