# Hybrid HL7 and FHIR Delivery Playbook

Illustrative template created for this portfolio. Contains no client data and is not a historical project deliverable. Example scenarios are synthetic; blank measurement fields are for future use.

Updated: 2026-09-08

## When to use

A program introduces FHIR or API exchange alongside existing HL7 interfaces. Use one set of decision gates while documenting each connection’s actual technical behavior.

## Decision this supports

Choose coexistence, phased migration, or replacement based on workflow coverage and operational evidence. Advance a connection only when its contract, validation, reconciliation, and support ownership are ready.

## 1. Inventory the coexistence model

Identify where legacy and modern paths overlap before introducing conflicting writes or duplicate workflow events.

### Workflow inventory

For each workflow, record source, destination, business owner, current connection, planned connection, and systems that remain in service.

Response: ____________________

### Source of truth

Record ownership of identifiers, terminology mapping, updates, corrections, and conflict resolution for each data domain.

Response: ____________________

### Migration choice

Coexist, migrate in phases, or replace [ ]; rationale [ ]; excluded workflows [ ]; review trigger [ ].

Response: ____________________

### Dependency map

Record partner release windows, vendor capabilities, endpoint availability, security decisions, and owners.

Response: ____________________

### Review checks

- [ ] No data domain has two undefined write authorities.
- [ ] Installed-base support responsibilities remain assigned during transition.

## 2. Agree on separate technical contracts

Use consistent ownership and review without assuming HL7 messaging and FHIR exchange have equivalent semantics.

### HL7 contract

Record version, message and trigger types, transport, mapping, acknowledgment mode, timeout, retry, duplicate detection, ordering, and reconciliation.

Response: ____________________

### FHIR or API contract

Record version, profiles, supported resources and operations, search parameters, pagination, validation expectations, and error responses.

Response: ____________________

### Authorization contract

Record supported OAuth flow, SMART context if applicable, scopes, token lifetime assumptions, service identity, and rotation owner.

Response: ____________________

### Failure contract

Define permanent versus retriable errors, retry limits, quarantine or exception workflow, replay authorization, and incident escalation.

Response: ____________________

### Review checks

- [ ] Partner documentation and endpoint capabilities agree with the proposed contract.
- [ ] A transport acknowledgment or successful HTTP response is not used alone as proof of correct downstream workflow.
- [ ] Retry and replay paths protect against unintended duplicate effects.

## 3. Run common evidence gates

Compare readiness through the same evidence categories while retaining protocol-specific test cases.

### Test record

Scenario [ ]; expected receiving-workflow behavior [ ]; protocol [ ]; evidence [ ]; actual result [ ]; defect owner [ ]; approver [ ].

Response: ____________________

### Coverage

Include successful exchange, invalid or missing data, corrections, duplicates, delayed or out-of-order events, unavailable endpoints, expired credentials, and reconciliation.

Response: ____________________

### Representative volume

Agreed operating profile [ ]; test environment limitations [ ]; backlog recovery expectations [ ]; observed evidence [ ].

Response: ____________________

### User acceptance

Receiving user [ ]; workflow validation steps [ ]; acceptance evidence [ ]; unresolved gap [ ].

Response: ____________________

### Review checks

- [ ] Engineering, QA, and the receiving workflow owner review failures and limitations together.
- [ ] Uncovered behavior is recorded as a risk, not silently counted as a pass.

## 4. Release, observe, and decide the next phase

Make the decision to expand or retire a connection dependent on stable observed behavior.

### Release sequence

Cohort [ ]; launch owner [ ]; decision gates [ ]; containment or rollback path [ ]; communication plan [ ].

Response: ____________________

### Operational ownership

Alert source [ ]; support owner [ ]; engineering escalation [ ]; reconciliation cadence [ ]; coverage window [ ].

Response: ____________________

### Measurement record

Metric [ ]; definition and denominator [ ]; baseline [ ]; target [ ]; result [ ]; observation window [ ]; source [ ]; owner [ ].

Response: ____________________

### Expansion or retirement decision

Evidence reviewed [ ]; remaining legacy dependency [ ]; decision [ ]; approver [ ]; next review date [ ].

Response: ____________________

### Review checks

- [ ] A legacy path is retired only after affected workflow coverage and remaining dependencies are accepted.
- [ ] Post-live findings become named product or operational follow-up work.

## Synthetic worked example

Synthetic scenario: a fictional specialty network keeps HL7 results while introducing FHIR reads for a separate application workflow.

Illustrative decision: coexist initially. Assign ownership per workflow, verify the endpoint’s FHIR profile and authorization behavior, and keep the existing results support path staffed.

Required evidence: clear data authority, scenario-level receiving-workflow checks, failure and credential-expiry tests, reconciliation results, and an explicit review before expansion. No migration benefit or performance result is assumed.

Portfolio: https://jasonpagliaro.com/work-samples/hybrid-hl7-fhir-delivery-playbook