# Healthcare integration: keep the service identity across the handoff

The coordinator asks, “We translated the service and received an answer. Why can't we use it?” Both pieces can work separately while disagreeing at their join. In this lab, the translation names vocabulary version payer-1, but the response names payer-2. The code still looks familiar. The missing engineering work is deciding whether the answer applies to the question you actually prepared.

This original exercise connects the previous terminology and eligibility interpreters without changing either one. All identities, codes and responses are invented. It runs locally with Python 3.11 or newer, uses no network or model, and sends no request or staff message. A synthetic requirement fact is not an approval or payment decision.

## 1. Understand the join before the fields

Think of a dependency lockfile. If you agreed to test a package at version 1, finding its name in a version 2 environment does not prove the same behavior. The integration must preserve the conditions under which the earlier result was valid.

The terminology interpreter establishes a directed mapping from local-services, local-1, VISIT to synthetic-services, payer-1, SYNTHETIC-VISIT. The eligibility interpreter checks a response against a patient, coverage, payer, request, date, system and code. It does not check the vocabulary version. Connecting their outputs without adding that comparison leaves a real gap in this exercise.

The new connector prepares a question containing both the business context and mapped service. It asks the existing interpreter for a local candidate, then checks the response coding before releasing that candidate as a staff packet. “Ready for staff” means ready to inspect under the fictional contract, not a message sent or a production authorization.

## 2. Separate the three kinds of version

| Field | What changed when this version changes? | What it cannot establish |
| --- | --- | --- |
| ConceptMap.version | The mapping artifact's business revision | Which vocabulary revision the response actually used |
| Coding.version | The coding system revision used for the code | The response's transport, provenance or approval |
| Resource meta.versionId | A revision of that resource instance | The vocabulary revision of a service inside it |

FHIR R4 allows Coding.version to be absent. This workshop deliberately requires an explicit matching version. That restriction is an integration agreement for these invented vocabularies, not a claim that every valid FHIR response must include it. A real adapter needs an agreed policy for its actual code systems and source profiles.

The same caution applies to multiple codings. FHIR can represent a concept in more than one coding. Our small connector accepts exactly one coding on the selected service item. It refuses additional representations rather than guessing how they relate. Do not “repair” this by choosing array index zero or deleting inconvenient evidence.

## 3. Run the connected proof lab

Start with the [visual evidence explorer](/training/guides/healthcare-handoff#3-run-the-connected-proof-lab). Follow the local service through mapping, the prepared question, the response and the staff handoff. It displays eight saved runs from the Python lab, including three comparisons with the version check omitted. Predict the output before revealing it; then explain whether that output is supported. The browser view does not execute Python or save a score.

Download the [complete lab bundle](/templates/fde-healthcare-handoff.zip), unzip it into a new folder and keep its three Python files together. The bundle also includes this workbook. No package installation or provider account is needed.

```bash
python3 fde-healthcare-handoff.py
python3 fde-healthcare-handoff.py --json > handoff-guarded.json
python3 fde-healthcare-handoff.py --ignore-response-version --json > handoff-broken.json
```

The connector loads the original terminology and eligibility files beside it. It does not download or install them. You can also inspect the [connector source](/templates/fde-healthcare-handoff.py), [terminology source](/templates/fde-healthcare-terminology.py) and [eligibility source](/templates/fde-healthcare-eligibility.py) separately.

Before executing, predict the changed-response-version case. The question carries payer-1, but the response says payer-2. Guarded mode returns `needs_source` with `response_version_mismatch` and `authorization_required`: null. The deliberately broken mode ignores only the version check, so a true requirement escapes into `ready_for_staff`. Compare the unchanged inputs in both reports.

| Case | Guarded observation | What the engineer learns |
| --- | --- | --- |
| matching-version; explicit-false | Scoped true or false requirement released | Preserve the source boolean without turning it into approval |
| renamed-response-display | Same supported identity | Reader-facing words are not the join key |
| changed-response-version | `response_version_mismatch` | Matching system and code do not satisfy this version contract |
| missing-response-version | `response_version_unreported` | The request does not prove the response's vocabulary version |
| resource-version-is-not-vocabulary-version | `response_version_unreported` | A resource revision cannot substitute for a coding revision |
| ambiguous-response-codings | `response_coding_not_unique` | Resolve multiple representations under an explicit policy |
| ambiguous-response-items | `service_not_unique` | A matching first item does not hide a second candidate |
| wrong-patient; wrong-request | `reference_mismatch` | Version agreement cannot rescue the wrong business context |
| missing-requirement | `requirement_unreported` | Missing still does not mean false |
| partial-response | `processing_not_complete` | Do not turn incomplete processing into an answer |
| mapping-unresolved | `mapping_unresolved` | No downstream question is prepared from an unsupported mapping |
| transport-unavailable | `transport_not_successful` | An unavailable source is not a coverage decision |

There are fourteen cases. The broken comparison changes the three version-gap cases only; all other decisions remain guarded. A successful process exit means the report ran, not that the learner passed or the workflow is deployable.

## 4. Follow the evidence into the packet

For matching-version, inspect `result.mapping.target`, `result.question.service` and `result.binding.observed`. The same qualified identity must survive across those boundaries. The binding path points into the original response. The accepted `result.eligibility` contains the original interpreter's evidence for the requirement flag.

For changed-response-version, `result.binding` records the expected payer-1 and observed payer-2. `result.eligibility` is null; `authorization_required` is null. The internal candidate is withheld. The integration engineer receives a request to resolve the source agreement with the terminology owner. The packet does not say the service is denied.

For mapping-unresolved, `result.question` is null and the terminology steward receives the gap. This demonstrates a useful ordering rule: do not form a downstream question from an identity you have not established. For source failures, the trace shows which earlier condition stopped the run; do not claim later checks passed when they did not run.

## 5. Change the inputs without weakening the agreement

Create challenge.py in the unzipped folder. This adds a second representation to an otherwise successful response. Predict `response_coding_not_unique` before running it.

```python
import runpy
lab = runpy.run_path("fde-healthcare-handoff.py")
case = lab["fixture"]()
codes = case["response"]["insurance"][0]["item"][0]["productOrService"]["coding"]
codes.append({"system": "https://example.invalid/other-vocabulary",
              "version": "other-1", "code": "OTHER-VISIT"})
result = lab["connect"](case)
print(result["reason"])
assert result["authorization_required"] is None
```

Now move the matching insurance entry behind an unrelated plan and remove its display text. Predict that the accepted fact stays the same while its evidence path changes. Next, change only the service date in the response; version agreement should not make the answer applicable to another date.

Finally consider a provider that legitimately omits Coding.version. Write the source agreement and test you would need before supporting that behavior. Filling the missing field from the question makes the comparison pass but adds no observation. A separately controlled source policy must specify the vocabulary, applicable period, update process and accountable owner; designing that adapter is a further exercise.

## 6. Rehearse the receiving decision

Ask a peer or facilitator to change one version or context reference without telling you which. Explain the result to an operations colleague before opening JSON. If working alone, record self-review. This is a review exercise, not an available live mentor or credential.

For the changed version, say: “The service mapped under payer-1, but the response identifies payer-2. We have withheld the requirement fact. The integration engineer and terminology owner need to settle which source contract applies.” For a matching response, say: “This synthetic response reports that authorization is required for the scoped service. We have not established approval, payment or patient cost.”

Keep the original question, source records, two reports, an unseen-input challenge and your handoff wording. A real deployment still needs trusted source loading, profile validation, freshness rules, authorization, protected storage and an operational receiving process. This exercise proves one composition rule, not those integrations.

Continue with [financial-services business meaning](/training/guides/financial-services-operations) to compare how another industry's terminology changes the evidence needed.

Primary references checked 23 October 2026: [HL7 R4 Coding.version](https://hl7.org/fhir/R4/datatypes-definitions.html#Coding.version), [resource revision metadata](https://hl7.org/fhir/R4/resource-definitions.html#Meta.versionId), [eligibility response service and requirement fields](https://hl7.org/fhir/R4/coverageeligibilityresponse-definitions.html#CoverageEligibilityResponse.insurance.item.productOrService), and [eligibility request service fields](https://hl7.org/fhir/R4/coverageeligibilityrequest-definitions.html#CoverageEligibilityRequest.item.productOrService). The version policy, fixtures, connector and acceptance rules here are original workshop material.