31 Aug
A vendor walks a health system through a FHIR API demo. Every resource comes back clean. Patient, Observation, Coverage, all correctly shaped JSON. Then someone on the evaluation team asks for a chained search across Encounter and Practitioner. The system returns a 501. Not implemented. The FHIR layer was real enough to pass a screenshot, and that was about it.
This is the trap. A FHIR facade in front of an HL7v2 engine can look identical to a native build in a sales call. The differences only show up once someone pushes past the happy path, which is exactly where prior authorization, DTR, and CDex workflows live.
What a FHIR facade actually is (and what it isn't)
A FHIR facade takes an existing HL7v2 interface engine and bolts a translation layer on top. Inbound FHIR requests get converted to whatever the legacy engine already understands. Outbound HL7v2 messages get reshaped into FHIR resources on the way out. The system speaks FHIR at the edge. Underneath, it still thinks in segments, fields, and Z-segments nobody has documented since 2011.
That’s not automatically a bad thing. A well-built facade with a real mapping layer, proper terminology binding, and persistent storage that supports versioning can satisfy a surprising amount of the FHIR spec. The problem isn’t facades in general. The problem is facades built fast, to check a box, with the mapping logic hardcoded to whatever fields happened to be populated in the vendor’s test environment.
These tend to fail in a consistent pattern: they work for the demo patient, and they fall apart on the messy real-world record with missing segments, local code sets, and out-of-order ADT messages.
Six red flags you can catch before lunch
A lab environment isn’t required to catch most of these. A laptop, an API client, and thirty minutes with the vendor’s sandbox will surface them.
- Local codes in coding.system. Open any Observation or Condition resource. If the coding array points to a home-grown code system instead of LOINC, SNOMED CT, or RxNorm, the underlying system never did real terminology mapping. It just relabeled the local code as if it were standard.
- Everything crammed into extensions. A Patient resource with half its clinical content stuffed into custom extensions usually means the source system has no first-class field for that data. The facade had nowhere else to put it.
- No vread, no history. Ask for a resource’s version history. If the system returns a 404 or ignores the _history parameter entirely, the underlying database isn’t tracking versions, which HL7v2 systems typically don’t.
- CapabilityStatement says yes, reality says no. The CapabilityStatement lists chained search, _include, and _revinclude as supported. Try them. A shocking number of facades publish a CapabilityStatement copied from a reference implementation rather than one reflecting actual capability.
- One giant Bundle instead of granular resources. If every query returns a bloated single Bundle with dozens of unrelated resources jammed together, the source system likely isn’t querying selectively. It’s dumping everything it has and letting the client sort it out.
- Subscriptions that are actually polling in disguise. Ask how their FHIR Subscription resource notifies your system. If the answer involves a background job checking every few minutes rather than a real notification channel, it’s not a subscription. It’s polling wearing a subscription’s name tag.
Where resource mapping quietly breaks
Resource mapping looks like the simplest layer and causes some of the ugliest downstream problems, mostly because errors here pass every automated schema validator. A field can be perfectly valid FHIR and still be wrong.
Watch for these patterns during mapping review:
- Status field collapsing. Source systems often have five or six internal status values that all get mapped to a single FHIR status code, losing information a downstream system needs to route the resource correctly.
- Free-text leaking into coded fields. A “notes” or “comments” field gets stuffed into a coded element because nobody built a proper terminology lookup, and it passes validation because FHIR allows text-only CodeableConcepts.
- Date and time zone drift. Source timestamps stored in local time get mapped without a time zone offset, which corrupts anything time-sensitive, including prior authorization expiration windows.
- Identifier system mismatches. A member ID gets mapped without the correct identifier.system value, so a receiving payer can’t match it to their own records even though the number itself is correct.
- Silent truncation. Long-form clinical notes or lengthy code descriptions get cut off at a field length limit inherited from a legacy system, and the truncation happens before mapping, so the FHIR resource is technically valid and factually incomplete.
- One-to-many collapsed to one-to-one. A patient with three active coverages gets mapped as if they have one, because the source schema was built around a single-payer assumption that FHIR’s Coverage resource doesn’t share.
None of these show up in a CapabilityStatement. All of them show up the first time a real transaction runs against a real payer or exchange partner.
The five-test diagnostic every consultant should run
When a red flag shows up, don’t stop at noticing it. Run these five tests and document the results before writing the assessment.
- Run the vendor’s sandbox through Inferno. Pick the Da Vinci test suite relevant to the client’s use case, PAS, DTR, or CRD, and let it run unattended. Inferno checks conformance details a sales demo never covers, and it produces a report that can go straight to procurement.
- Request the HL7v2-to-FHIR mapping table. Ask for it in writing, field by field. A vendor with a real implementation has this document already, because their engineers needed it to build the thing. A vendor without one will stall, deflect, or send a marketing PDF instead.
- Test a write, then read it back through both interfaces. Update a resource through the FHIR API, then pull the same record through the legacy HL7v2 feed. If the update doesn’t show up, or shows up with fields dropped, the facade is one-directional or lossy.
- Push a message with a segment the demo never used. Real hospital data has NK1 segments, OBX repeats, and Z-segments the vendor’s demo patient conveniently lacks. Feed the sandbox a message with an unusual but valid structure and see what the FHIR output looks like.
- Check terminology binding against the actual value set. Grab a required value set from the relevant Da Vinci profile and confirm the returned codes actually validate against it, not just that a code is present.
Native FHIR vs. HL7v2-in-a-facade: side by side
| Capability | Native FHIR-modeled system | HL7v2 wrapped in a FHIR facade |
|---|---|---|
| Terminology binding | Codes mapped to LOINC, SNOMED, RxNorm at the source | Local codes often passed through unchanged |
| Versioning and history | vread and _history work as specified | Frequently unsupported, since HL7v2 has no native versioning concept |
| Search capability | Chained search, _include, _revinclude fully functional | Often returns 501 or silently ignores the parameter |
| Round-trip writes | Updates persist consistently across all access points | Writes may not propagate back into the legacy engine |
| Subscriptions | Real event-driven notifications | Often polling dressed up as a subscription |
| Da Vinci profile conformance | Passes Inferno’s profile-specific test suites | Frequently fails on required extensions or bindings |
| Mapping documentation | Field-level mapping exists and is maintained | Often missing, undocumented, or outdated |
Why this stops being theoretical after the CMS prior auth deadline
None of this matters much if the FHIR endpoint is a nice-to-have sitting next to the real integration. It matters enormously once a payer or provider organization is required to move actual prior authorization decisions through Da Vinci PAS and DTR. A facade that returns clean-looking JSON in a demo but drops coding systems in production will generate PAS bundles that payers reject, not because the workflow logic is wrong, but because the underlying data was never structured well enough to survive the trip.
This played out at a mid-size hospital system that had already signed off on a vendor based on a smooth demo. Six weeks into building the DTR questionnaire response workflow, the integration team discovered that diagnosis codes from three different service lines were arriving as free text in an extension, because the legacy ADT feed never carried structured coding for those departments. The fix wasn’t a FHIR problem. It was a data governance problem the facade had been quietly hiding.
The questions that end a vendor call early
A short list of questions, asked in order, tends to separate real implementations from wrappers faster than any RFP language:
- Can you show your field-level HL7v2-to-FHIR mapping documentation right now, on this call?
- What happens when the sandbox runs through Inferno’s Da Vinci PAS test suite?
- Does a write through the FHIR API persist back into the core system, and can that be tested live?
- How does the system handle a code that exists locally but has no equivalent in LOINC or SNOMED?
- What’s the actual mechanism for FHIR Subscriptions, and is it event-driven or polling?
A vendor with a native or well-built facade answers these directly, usually with a screen share. A vendor without one changes the subject to roadmap timelines.
What to do with a client stuck on a facade
Not every facade needs to be ripped out. Some can be remediated with proper terminology mapping and a real subscription mechanism, especially if the underlying HL7v2 feeds are otherwise clean. The decision point is whether the vendor can produce the mapping documentation and pass Inferno testing after remediation, not before budget has been spent assuming it already does.
Build the assessment around the five tests above, document exactly where the facade fails, and give the client a remediation cost estimate against a replacement cost estimate. That comparison, backed by an actual Inferno report instead of a vendor’s claim, is what turns a vague interoperability concern into a decision the client’s CFO can act on.
FAQs
A FHIR facade is a translation layer placed in front of a legacy HL7v2 interface engine. It accepts FHIR requests and returns FHIR-shaped JSON, but underneath, the source system still stores and moves data as HL7v2 segments and fields. The facade converts on the way out and on the way in, without changing how the underlying system models the data.
Run the vendor's CapabilityStatement against actual test calls: request _revinclude, chained searches, and $everything, then check whether the results match what the CapabilityStatement claims. Ask for the HL7v2-to-FHIR mapping documentation. If the vendor can't produce a field-level mapping table or the system fails basic conformance testing in Inferno, it's likely a wrapper.
The rule doesn't specify implementation architecture, only conformance to the required FHIR profiles, including Da Vinci PAS, DTR, and CRD. A facade can technically satisfy this if it fully supports the profile's required elements, extensions, and terminology bindings. In practice, most facades fail profile-level conformance because the source data was never structured to support it.
Inferno is ONC's open-source FHIR test kit, used to validate whether a system meets specific certification and Da Vinci profile requirements. It matters because a system can look correct in a sales demo and still fail Inferno's structured test suite, since Inferno checks conformance details that manual demos skip: terminology bindings, search parameter behavior, and required extensions.
Prior authorization workflows depend on structured, coded data moving reliably in both directions. If the facade can't preserve coding systems, versioning, or round-trip updates, PAS and DTR transactions will produce incomplete or rejected requests. The failure usually surfaces after go-live, when payers reject bundles that looked fine in testing but broke on data the demo never covered.
ISO 27001:2022 Certified
Aigilx health specializes in developing Interoperability solutions to create a healthcare ecosystem and aids in the delivery of efficient, patient-centric and population-focused healthcare.
