Healthcare Integration Onboarding

TL;DR

• A new healthcare feed is not a new parser. It is a new source profile — a named configuration that governs tolerance, mapping, classification, and what “good” means for that specific feed.
• Variance lives in config, not code. The parser, workflow, and routing should stay small; the profile absorbs the weirdness of each partner or vendor.
• Treat partner data as untrusted input with a contract. Validate against an explicit schema, classify deviations as warnings or errors by policy, and never let unrecoverable records silently vanish.
• Onboarding is not done when the feed parses. It is done when you can replay, observe, and degrade gracefully under realistic partner behavior.
• The cheapest way to slow this down is to treat each feed as a special project. The cheapest way to speed it up is to treat the onboarding itself as a process.

When to use this playbook

You are adding a new healthcare feed, API, or integration partner, and one or more applies:

• HL7v2, CSV/flatfile, EDI X12, CDA/CCDA, or FHIR data is inbound from a new source.
• You have an existing integration platform and want each new onboarding to compound rather than sprawl.
• You have been bitten by a partner API contract that was not what the docs said, and you want a repeatable way to catch that earlier.
• Operations is fielding too many "the feed broke" pages that turn out to be "the feed changed and nobody noticed."

If you are integrating a single feed, one-off, and never again, this is more process than you need. If you are integrating a second or tenth, this is where the saved time lives.

Inputs

Before onboarding starts, you need:

• Sample messages. Real ones, from the partner, with real variance. Not the spec's example. Not a sanitized test fixture. If you cannot get realistic samples, every downstream decision is a guess.
• A partner contact who can answer questions. You will have questions the documentation does not answer. Someone has to be on the other end.
• A named product or clinical owner for this feed. Someone who can make a call on "is this record good enough to send downstream" when edge cases show up.
• A target consumer. Someone, or something, downstream of this feed who has an opinion about what a good record looks like.

If you are missing the samples or the partner contact, pause. You will pay 10x later.

The onboarding

Five phases. The first four are per-feed; the fifth is ongoing.

1. Profile — write down what this feed is, and what "good" looks like.
2. Parse — normalize, parse, and extract semantic events.
3. Route — decide where each event goes and under what conditions.
4. Verify — replay real samples, observe the output, exercise failure modes.
5. Operate — watch the feed in production with the instrumentation you built.

Phase 1: Profile

The profile is the contract. Everything else is downstream.

A source profile includes:

• Identity. Partner name, feed name, version, contact, notification channel.
• Format. HL7v2, FHIR R4, EDI X12-837, flat CSV with a specific header. Version pinned.
• Tolerance policy. What counts as a warning, what counts as an error, what counts as unrecoverable. This is the decision that drives operations for the life of the feed.
• Mapping. Local codes to LOINC, SNOMED, or the canonical set. Partner identifiers to your internal IDs.
• Event classification. When a record arrives, what canonical semantic event is it — admit, discharge, lab result, claim, referral?
• Routing. Which workflow picks this up, on what conditions.

The profile is a YAML (or equivalent) file under version control. It is the artifact the product owner signs off on. No profile, no onboarding.

Done-state for Phase 1: the profile describes the feed in enough detail that a parser can be written against it and an operator can answer "is this record okay" by looking at the profile plus the record.

Phase 2: Parse

The parser's job is to turn bytes into semantic events, governed by the profile.

Structure parsing as three sequential steps:

• Byte normalization. Encoding, line endings, delimiter conventions, segment boundaries. Make the input predictable before you try to understand it.
• Syntactic parse. Turn the normalized bytes into the format's structure — HL7 segments, FHIR resources, EDI loops, CSV rows with typed fields.
• Semantic extraction. Pull the canonical event out of the structure. An HL7 ADT-A01 becomes a patient_admit event; an EDI 837 becomes a claim_submitted event.

Each step has different failure modes. Byte normalization failures are usually unrecoverable (garbled encoding). Syntactic failures are usually recoverable (one field malformed, rest of the record fine). Semantic failures are a policy call — the record parsed, but do we trust it?

Done-state for Phase 2: a realistic batch of partner messages parses, with each record classified as success, warning, or error according to the profile's policy. The warnings and errors are inspectable.

Phase 3: Route

Routing is where the semantic event meets the business workflow.

Structure routing as a small DSL (CEL expressions, a workflow YAML, a rules engine — the shape matters less than the declarativeness). The rules should be:

• Predicates over the semantic event's fields — "if this is a lab result and the test is a creatinine and the value is critical..."
• Actions that are idempotent — send to queue X, write to store Y, call downstream API Z, raise alert A.
• Versioned. Rule changes go through review, just like code.

Avoid:

• Routing decisions buried in the parser.
• Downstream systems that accept events without contract validation of their own.
• Rules that silently drop records on unmatched conditions. Explicit "no route" is a category; implicit is a bug.

Done-state for Phase 3: every semantic event that parses successfully has a defined route, including a route for "nothing matched this record." The routing rules are readable by the product owner without a parser expert in the room.

Phase 4: Verify

Do not ship a new feed based on live traffic. Verify first.

Run the new feed through three tests:

• Replay. Take a day or a week of real partner messages and run them through the pipeline offline. Count successes, warnings, errors. Verify the shape matches what the profile predicts.
• Simulation. Inject deliberate variance — truncated messages, wrong codes, missing fields, duplicate sends, out-of-order delivery. Observe the pipeline's behavior. Each behavior should match the profile's tolerance policy.
• Degradation. Fail downstream systems intentionally. The feed should absorb the failure with retries, queues, and dead-letter handling. The feed should never silently drop data when a downstream goes away.

The simulations are not academic. Every partner will eventually do all of these. Better to discover the behavior before they do.

Done-state for Phase 4: you have a replay report, a simulation report, and a degradation test report, each with evidence (log snippets, metric screenshots) and a sign-off from the operations owner.

Phase 5: Operate

The feed is in production. The onboarding is ongoing.

Instrument:

• Volume. Messages per hour, by day of week. Baseline it. Alert on a deviation threshold, not an absolute.
• Classification mix. Successes, warnings, errors. The mix drifts when the partner changes something.
• Latency. Ingest to downstream-committed. This is the real SLO, not the parser's internal latency.
• Dead-letter queue depth. It should be near zero. When it grows, someone should notice within the hour.

Maintain:

• A partner change log. Every time the partner deviates from the profile, record it. Update the profile or push back. Do not adapt silently; the next engineer will not know which behaviors were deliberate.
• A replay tool. You will want to re-process historical messages when a bug is found or a rule changes. Build it now.

Done-state for Phase 5: a new engineer can look at the feed's dashboard and answer, in ten minutes, "is this feed healthy and what changed recently."

Gates summary

Phase	Gate	Evidence
Profile	Product owner sign-off on the profile YAML	Signed, version-controlled
Parse	Batch parses with expected mix of success/warning/error	Replay report
Route	Every semantic event has a defined route	Rule file + coverage check
Verify	Replay, simulation, and degradation tests pass	Three written reports
Operate	On-call engineer can read the feed's health at a glance	Dashboard + runbook

Anti-patterns

• Per-feed parsers. Every new feed becomes a new codebase. Integration engineers never compound experience.
• Implicit tolerance. The parser silently accepts odd records because someone was lenient in code. Three feeds later, nobody knows what "good" means.
• Skipping the simulation phase because "the parser works on sample data." The parser always works on sample data. Partners never send only sample data.
• Treating dead-letter queue depth as a metric, not an alert. A DLQ that grows unnoticed is a silent incident in progress.
• No replay tool. When the inevitable rule change lands, you cannot reprocess history, and you end up with a feed that is partially on the old rules and partially on the new. This is the worst possible state for audit.

What this looks like in practice

In the fi-fhir platform, onboarding a new feed produces:

• One new YAML profile under version control, reviewed by the clinical owner.
• Zero new parser code in the common case. The three-phase parser handles the format; the profile handles the variance.
• A new workflow entry routing the semantic events downstream.
• A verification packet: replay, simulation, and degradation test results, each inspectable.
• A dashboard and runbook entry, both generated from the profile.

The onboarding time goes from weeks to days because the work shifts from writing code to writing down what the feed is. That is almost always the harder and more durable artifact anyway.

Source material

The source posts and case studies are listed at the bottom of the page. fi-fhir is the reference implementation; the patient-matching and operationalizing-integrations posts are the scar tissue that shaped the approach.