Free learning / 50-minute integration lab

Healthcare integration: keep the service identity across the handoff

Connect terminology mapping to eligibility interpretation. Follow the version across both systems, run fourteen cases and expose a condition that component tests miss.

Begin reading Download a working copy

No account needed. Use your own copy for writing and keep the original as a reference.

Engineering lab library / Run locally

Connect the question to the answer.

Follow a mapped service into a scoped eligibility response, then prove why dropping its version releases an unsupported fact.

Local Python with invented records. Unzip the bundle and keep its three scripts together. No network, patient data, source writes or live request.

Start here / Python 3.11+ · Standard library
Connected healthcare proof lab
Run fourteen connected cases and prove why a successful component can still lose a required vocabulary version.
Python 3.11+ · Unzip three Python files and workbook · No packages
Open walkthrough Download file

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.

UNDERSTAND THE SYSTEM

Keep the same service all the way to the answer

A correct translation and a readable response can still describe different vocabulary versions. Follow the identity across the join before handing a fact to staff.

FOLLOW ONE EXAMPLE

See what moves and why.

Authored illustration

01 / EXPLORE THE PARTSTap a part to explain it

Direction of information or workReturn / feedback

Read the connections in plain English

01
Local service → Mapped identity
Unresolved mappings stop before a question is formed.
02
Mapped identity → Scoped question
The target system, version and code travel together.
03
Scoped question → Compare the versions
The prepared question supplies the version to compare, not evidence of what the response used.
04
Response coding → Compare the versions
Compare the actual response field, without filling it from the request.
05
Compare the versions → Receiving owner
Matching versions allow a scoped requirement fact with its evidence. A missing or changed version withholds that fact and routes the gap for source-contract resolution. Neither result establishes approval or payment.

Check your understanding: The response omits Coding.version but meta.versionId is payer-1. Is that sufficient?

No. meta.versionId identifies a revision of that resource; Coding.version identifies the vocabulary revision. This workshop requires the latter explicitly. A real system may use an independently agreed version policy, but it cannot infer one from a coincidental string match.

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

← Back to lab library Download Connected healthcare proof lab ↓

Choose a healthcare handoff case

A local team calls the service VISIT. The mapping names it SYNTHETIC-VISIT in payer-1. Follow that identity into the question and the response before passing a requirement to staff.

STAGE 1 OF 4 / VERSION-BOUND CONNECTOR

Map the service

A code system is a vocabulary. Its code names a concept, and its version tells us which edition supplied that meaning. A mapping connects the local identity to the payer vocabulary.

LOCAL INPUT

VISIT

Vocabulary version: local-1
Code system: https://example.invalid/local-services

Display label: Visit

ACCEPTED MAP TARGET

SYNTHETIC-VISIT

Vocabulary version: payer-1
Code system: https://example.invalid/synthetic-services

Display label: Office encounter

Mapping artifact: workshop-1. This versions the mapping itself; it is separate from both vocabularies.

Recorded mapping reason: mapped_identity

Inspect the original map and its recorded evidence

{
  "concept_map": {
    "resourceType": "ConceptMap",
    "url": "https://example.invalid/maps/local-to-payer",
    "version": "workshop-1",
    "status": "active",
    "group": [
      {
        "source": "https://example.invalid/local-services",
        "sourceVersion": "local-1",
        "target": "https://example.invalid/synthetic-services",
        "targetVersion": "payer-1",
        "element": [
          {
            "code": "VISIT",
            "display": "Visit",
            "target": [
              {
                "code": "SYNTHETIC-VISIT",
                "display": "Office encounter",
                "equivalence": "equal"
              }
            ]
          }
        ]
      }
    ]
  },
  "mapping": {
    "state": "mapped",
    "reason": "mapped_identity",
    "source": {
      "system": "https://example.invalid/local-services",
      "version": "local-1",
      "code": "VISIT",
      "display": "Visit"
    },
    "target": {
      "system": "https://example.invalid/synthetic-services",
      "version": "payer-1",
      "code": "SYNTHETIC-VISIT",
      "display": "Office encounter"
    },
    "map": {
      "url": "https://example.invalid/maps/local-to-payer",
      "version": "workshop-1"
    },
    "evidence": [
      {
        "path": "url + version",
        "value": [
          "https://example.invalid/maps/local-to-payer",
          "workshop-1"
        ]
      },
      {
        "path": "group[0].element[0].target[0]",
        "value": {
          "code": "SYNTHETIC-VISIT",
          "display": "Office encounter",
          "equivalence": "equal"
        }
      }
    ],
    "owner": "eligibility_operations",
    "next_action": "Use the mapped identity in a separately scoped eligibility question.",
    "not_established": [
      "coverage",
      "authorization_requirement",
      "authorization_approval",
      "payment"
    ]
  }
}

Start with the visual evidence explorer. 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, 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.

Code example

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, terminology source and eligibility source 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.

Code example

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 to compare how another industry's terminology changes the evidence needed.

Primary references checked 23 October 2026: HL7 R4 Coding.version, resource revision metadata, eligibility response service and requirement fields, and eligibility request service fields. The version policy, fixtures, connector and acceptance rules here are original workshop material.