Interop Service — Migration Plan

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · SERVICE_OVERVIEW · APPLICATION_LOGIC

1. Background

The interop-service consolidates two previously separate modules:

Legacy module	Status	What it owned
fhir-gateway	Retired as standalone; absorbed	FHIR R4 routing, CapabilityStatement, ABAC enforcement, bulk ops
hl7v2-interop	Retired as standalone; absorbed	MLLP listener, HL7 v2 message log, ADT/ORM/ORU/VXU mapping, connector registry

Both sub-domains are now co-located in a single NestJS process sharing one PostgreSQL schema and one NATS connection.

2. Migration Scope

2.1 Legacy HL7 v2 Integrations to Interop-Service Gateway

All existing external systems that used the standalone hl7v2-interop MLLP endpoint must re-register their connector configuration via the new Connector Registry in interop-service:

Legacy integration	Protocol	Migration action
External LIS (lab result ingest)	HL7 v2 ORU R01 (MLLP)	Re-register connector via POST /v1/connectors; update LIS MLLP destination to new port
Hospital Information System (ADT)	HL7 v2 ADT A01/A03/A08 (MLLP)	Re-register; new MLLP server address; test A01 round-trip
Immunization registry outbound	HL7 v2 VXU V04 (MLLP)	Re-register; validate VXU segment mapping
External LIS order dispatch	HL7 v2 ORM O01 (MLLP)	Re-register; validate ORM from orders-service activation event

Connector re-registration process:

1. Integration admin calls POST /v1/connectors with new connector payload (facility, direction, message types, auth).
2. Connectivity test via POST /v1/connectors/:id/test before go-live.
3. Update external system's MLLP destination to the new interop-service host/port.
4. Decommission legacy hl7v2-interop MLLP listener port after all connectors tested.

2.2 FHIR DSTU2 / STU3 Consumers Upgrading to R4

External systems that consumed FHIR DSTU2 or STU3 endpoints from the legacy fhir-gateway must migrate to FHIR R4:

Consumer type	Legacy version	Migration action
National HMIS bulk export	FHIR DSTU2 / custom	Migrate to R4 $export via /fhir/R4/Group/{id}/$export
Partner EMR (read queries)	FHIR STU3	Update resource URLs and field names (R4 alignment); re-test CapabilityStatement
Clinical decision support tools	FHIR STU3 ValueSet	Migrate to R4 terminology operations ($expand, $validate-code)
Patient portal (internal)	FHIR DSTU2	Migrate to R4; update patient-portal-service to use R4 endpoints

Backwards-compatibility shim timeline:

Shim	Availability	Deprecation date	Sunset date
FHIR STU3 read routes (/fhir/STU3/*)	Provided via header-routing shim	M2 (6 months post-R4 GA)	M4 (12 months post-R4 GA)
FHIR DSTU2 Patient read	Provided via narrow shim for HMIS bulk	M2	M3
Legacy HL7 v2 MLLP port (old address)	Forwarded to new interop-service port	M1 (30 days)	M1 + 30 days

All clients are notified at shim deployment with a Sunset HTTP header and Deprecation response header pointing to this document.

2.3 External System Cutover Strategy

Cutover gates per external system:

1. Connector re-registration tested with real messages.
2. Zero parse_failed messages in new interop-service within 48 h of shadow.
3. Response payloads validated against R4 CapabilityStatement.
4. External system team sign-off.

2.4 HL7 Message Log Migration

Legacy hl7v2-interop stored HL7 message logs in its own schema. These are migrated to the interop.hl7_messages table:

-- Migrate legacy HL7 message log (example)
INSERT INTO interop.hl7_messages (
  id, tenant_id, connector_id, direction, message_type,
  raw_payload, status, message_control_id, sending_app,
  received_at, created_at
)
SELECT
  gen_random_uuid(), legacy.tenant_id,
  connector_map.new_connector_id,
  legacy.direction, legacy.message_type,
  legacy.raw_message, 'processed',
  legacy.message_control_id, legacy.sending_application,
  legacy.received_at, legacy.received_at
FROM legacy_hl7.messages legacy
JOIN connector_id_map connector_map ON connector_map.legacy_id = legacy.connector_id;

Migration is idempotent (upsert on message_control_id + connector_id). Historical messages are preserved read-only for compliance (7-year retention).

2.5 FHIR Routing Rules Migration

Legacy fhir-gateway had hard-coded routing rules per resource type. The new interop-service uses a configurable fhir_routing_rules table:

-- Seed routing rules (run once at deployment)
INSERT INTO interop.fhir_routing_rules (resource_type, category_filter, target_service_url, priority)
VALUES
  ('Observation', 'laboratory', 'http://laboratory-service:3009/internal/fhir', 10),
  ('DiagnosticReport', NULL, 'http://laboratory-service:3009/internal/fhir', 10),
  ('ServiceRequest', NULL, 'http://orders-service:3010/internal/fhir', 10),
  ('MedicationRequest', NULL, 'http://orders-service:3010/internal/fhir', 10),
  ('Patient', NULL, 'http://registration-service:3002/internal/fhir', 10),
  ('Encounter', NULL, 'http://registration-service:3002/internal/fhir', 10),
  ('CarePlan', NULL, 'http://care-plan-service:3013/internal/fhir', 10),
  ('ValueSet', NULL, 'http://terminology-service:3020/internal/fhir', 10);

Rules are tenant-overridable for advanced routing configurations.

3. Rollback Plan

Trigger	Rollback action
MLLP parse failure rate > 1% in new service	Kong weight back to legacy MLLP; page integration team
FHIR routing mismatch (wrong owning service)	Update fhir_routing_rules table; no code deploy needed
External system reports non-conformant R4 responses	Re-enable STU3 shim; extend shim timeline
HL7 message log migration count mismatch > 0.5%	Halt cutover; re-run migration script with delta

4. Legacy Module Decommission Timeline

Module	Read-only window	Decommission date
fhir-gateway (standalone)	30 days post-cutover	M1 + 30 days
hl7v2-interop (standalone)	30 days post-cutover	M1 + 30 days
FHIR STU3 shim routes	12 months post-R4 GA	M4
FHIR DSTU2 shim routes	6 months post-R4 GA	M3

5. Open Questions

• Confirm HMIS team readiness for FHIR R4 bulk export migration (currently on DSTU2).
• Agree 7-year HL7 message log retention implementation with compliance team (hot vs cold storage).