FHIR Devices and Transformation

Connexion v26 adds purpose-built FHIR devices alongside the more flexible Liquid Template Device. Together they support converting healthcare messages to FHIR R4, parsing and validating FHIR resources, and sending those resources to a FHIR REST endpoint.

The three building blocks serve different needs:

HL7v2 to FHIR Device

The HL7v2 to FHIR Device converts Connexion HL7 messages into FHIR R4 JSON using the Microsoft-derived FHIR Converter Liquid templates bundled with Connexion.

For normal messages, the device selects a root template from the message type in MSH-9. For example, an ADT^A01 message resolves to the corresponding Hl7v2/ADT_A01 template. Local template overrides take precedence over the built-in catalog, and message-type rules can provide aliases, select a different template, or disable conversion for an exceptional message type.

The device is intended to handle the standard conversion path without exposing custom C# code. Existing HL7 Transform devices can still be placed upstream when a site needs to normalize local fields, apply map tables, reshape Z-segments, or otherwise prepare the message before FHIR conversion.

Rendered output can be required to be a FHIR Bundle or may be allowed to contain any FHIR resource. If a template is missing or the rendered FHIR is invalid, the channel can either fail the message or record a warning and continue, depending on its configuration.

FHIR Sender

The FHIR Sender transmits FHIR R4 JSON to a FHIR REST endpoint using the standard application/fhir+json media type. It accepts either FHIR JSON or a Firely FHIR Resource object; Firely resource objects are serialized with the FHIR JSON serializer before transmission.

The sender supports the common FHIR REST interactions:

• Post a Bundle to the server base URL.

• Create a resource with POST /{resourceType}.

• Update a resource with PUT /{resourceType}/{id}.

• Perform a conditional update with a configured search expression.

• Select the appropriate operation automatically: Bundles are posted to the base URL, resources without an ID are created, and resources with an ID are updated.

Connection options include anonymous, Basic, bearer-token, and Integrated Windows authentication, together with proxy, TLS certificate pinning, and mutual-TLS support. Responses can be left only in processing history, retained for diagnostics, or used to replace the current message. Optional HTTP tracing is available for troubleshooting; request and response bodies may contain PHI and should only be captured under appropriate operational controls.

FHIR parsing and validation

Both purpose-built devices use the Firely FHIR .NET packages for FHIR R4 parsing and validation. This is more than checking whether the rendered body is syntactically valid JSON: the parser materializes it as a FHIR resource and reports FHIR-specific errors and diagnostics.

The available validation levels are:

• Off — do not parse the resource before continuing.

• Lenient parse — parse with Firely while tolerating some input variations.

• Strict parse — apply the stricter Firely FHIR JSON parser.

• Profile validation — parse the resource and validate it against the base R4 definitions, a profile declared by the resource, or an explicitly configured canonical profile URL.

The HL7v2 to FHIR Device defaults to lenient parsing so that template output can be reviewed and tightened during rollout. The FHIR Sender defaults to strict parsing so invalid resources normally fail before an HTTP request is sent. Both devices can instead downgrade validation failures to warnings when a staged migration requires traffic to continue.

Profile validation uses Firely's R4 validation and package-resolution libraries. Environments that rely on profile validation should verify package availability and outbound access to the configured FHIR package source as part of deployment validation.

Local validation cannot guarantee that a destination server will accept a resource. A server may apply additional implementation guides, terminology services, business rules, authorization policies, or interaction constraints. Treat Connexion validation as an early quality gate and retain destination-server testing in the rollout plan.

Liquid transformations beyond FHIR

The Liquid Template Device is compatible with Microsoft FHIR Converter templates, including common HL7 v2-to-FHIR, C-CDA-to-FHIR, and JSON-to-FHIR conversions. However, the engine is not restricted to FHIR and does not require a FHIR resource as its output.

A Liquid device can expose the incoming message as text, an HL7 object graph, or a custom model assembled by its device code. A template can then render JSON, XML, delimited text, another HL7 representation, or another text-oriented format required by the integration. Public helper methods on the device can be called from a template for calculations, lookups, and site-specific logic.

Connexion adds healthcare-oriented capabilities to the underlying Liquid language:

• HL7-aware objects for navigating segments, fields, and components.

• Standard Liquid conditions, loops, includes, variables, and filters.

• Global and map-table lookups.

• Protected configuration values.

• Custom C# helper functions exposed deliberately by the device.

• Optional FHIR code-system mapping tables.

• A bundled template catalog with dependency-aware imports.

Use the purpose-built HL7v2 to FHIR Device when its convention-based template selection and validation model fit the channel. Use the Liquid Template Device when the source or target format, template-selection rules, or supporting logic are more specialized.

Templates are channel configuration and should be reviewed, versioned, tested, and promoted like code. Test representative messages as well as missing, repeated, malformed, and site-specific fields, and keep PHI out of general operational logs.

Related pages

• Liquid and Razor Transformation