FHIR Search

Searches for FHIR resources by type and search parameters. Includes a built-in visual filter builder.

Inputs

payload.access_token string

Access token for FHIR server authentication (required)

payload.resourceType string

FHIR resource type (e.g., Patient, Observation). Overrides node configuration

payload.searchFilter object

Search parameters as JSON object. Used when no visual filters are configured in the node

payload.filterValues object

Values for {{variable}} substitution in visual filter rows

Outputs

payload object

FHIR Bundle containing matching resources

fhir object

Metadata about the FHIR operation:

• resourceType - Type of resource searched
• searchFilter - Search parameters used
• url - Full FHIR URL used
• integrationId - Integration used
• operation - Always "search"
• totalResults - Number of results in bundle

Details

This node performs a FHIR search operation to find resources matching the specified criteria.

The node requires an access token to be provided in msg.payload.access_token. This token should have appropriate permissions to search the requested resource type.

Search parameters should be provided as a JSON object. Common FHIR search parameters include:

• _count - Number of results to return
• _sort - Sort order for results
• _include - Include related resources
• Resource-specific parameters (e.g., name, birthdate for Patient)

Search Parameter Priority

1. Visual filter rows configured in the node (if any)
2. msg.payload.searchFilter (e.g., from ec-fhir-searchfilter node)
3. Raw JSON textarea in node config
4. msg.toolInput (AI Tool structures)

Filter Operators

• equals - Exact match (default)
• not equals - ne prefix
• greater than - gt prefix
• greater or equal - ge prefix
• less than - lt prefix
• less or equal - le prefix
• contains - :contains modifier
• exact - :exact modifier

Variable Substitution

Use {{variableName}} in filter values. Resolved from msg.payload.filterValues.

Nested paths: {{patient.id}} resolves to msg.payload.filterValues.patient.id.

Multiple variables can be used in a single value, and variables can be placed anywhere in the string.

Examples:

• Simple: {{patientId}} → 123
• Multiple: {{resourceType}}/{{id}} → Patient/456
• With operators: ge{{startDate}} → ge2024-01-01

Scope Validation

The node checks if the selected resource type is included in the integration's scopes. Scopes follow the format: [user|patient|system]/[ResourceType|*].[read|write|*]

Examples:

• patient/*.read - Can read all resource types in patient context
• user/Patient.read - Can read Patient resources in user context
• system/Observation.* - Can perform all operations on Observations

Search Examples

Patient Search:

{
  "family": "Smith",
  "given": "John",
  "birthdate": "1980-01-01",
  "_count": 10
}

Observation Search:

{
  "patient": "Patient/123",
  "code": "http://loinc.org|8867-4",
  "_sort": "-date",
  "_count": 5
}

Encounter Search:

{
  "patient": "Patient/123",
  "date": "ge2024-01-01",
  "status": "finished"
}

Example Output

Filter configuration:

• Parameter: patient, Value: {{patientId}}
• Parameter: date, Value: ge{{startDate}}

With msg.payload.filterValues:

{
  "patientId": "123",
  "startDate": "2024-01-01"
}

Resulting query parameters:

{
  "patient": "123",
  "date": "ge2024-01-01"
}

Best Practices

• Use variables (e.g., {{patientId}}) for dynamic values rather than hardcoding.
• Enable Enforce Validation to catch missing variable values early in the workflow.
• Set an appropriate _count to limit the result set size and improve performance.
• Use _sort for predictable result ordering (e.g., -date for newest first).
• Test complex filter logic using a standalone FHIR Search Filter node before connecting it to this node.
• Document the expected filterValues input structure in your flow's notes.