Inera Core Implementation Guide - Local Development build (v0.2.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Migration Guide from TKB to FHIR

Migration Guide: From TKB to FHIR – Architectural Transition Strategies

Purpose and Scope

This page describes architectural transition patterns for moving from Swedish RIVTA/TKB (Tjänstekontrakt) SOAP-based services to FHIR REST APIs.

The focus is architectural only:

• How to let existing TKB services and new FHIR APIs coexist over time
• How to reuse existing investments in TKB-based integrations and logic in current EHRs and Inera services
• How to design new systems so that they are aligned with EHDS / EEHRxF and can expose FHIR APIs with coverage comparable to today's TKB-based information exchange

Semantic mappings (ConceptMap, structure mappings), security/PDL and legal compliance are covered on other pages.

This guide is strongly inspired by the IHE mXDE (Mobile Cross-Enterprise Document Data Element Extraction) profile and its relationship to QEDm (Query for Existing Data for Mobile), which describe how coarse-grained document sharing and fine-grained FHIR data elements can safely coexist in the same infrastructure.

1. Architectural Goals

Across Inera infrastructure, regional EHRs and vendor platforms, the transition architecture should support:

1. Coexistence of coarse- and fine-grained access
   • Keep existing TKB–based services and/or document-style payloads where they work well
   • Add FHIR APIs for data-element level access to the same clinical content
2. Reuse of existing investments
   • Do not require immediate replacement of TKB integrations in regional EHRs
   • Allow national services to expose both TKB and FHIR for a long overlap period
3. EHDS/EHRxF readiness
   • Prepare for EHDS requirements on EHR systems and national infrastructures to expose standardized, FHIR-based interfaces and EEHRxF content for priority data categories.
4. Traceability back to the source
   • Ensure that data exposed via FHIR can always be traced back to the "source context" (TKB interaction, local document, EHR record), following the same principles as mXDE's Provenance-linked extraction.

2. Relation to IHE mXDE and QEDm

2.1 mXDE in one paragraph

The mXDE profile defines how to expose fine-grained FHIR data elements (e.g. allergies, medications, problems, procedures) extracted from a document sharing infrastructure (XDS/XCA/MHD/MHDS).

Key ideas:

• A Data Element Extractor actor pulls content from shared documents, extracts data elements and publishes them as FHIR resources, with Provenance links back to the original document(s).
• A Clinical Data Consumer actor queries FHIR data elements (typically using QEDm) and, when needed, follows the Provenance links back to the original document for full context.
• The profile describes several deployment models (central vs distributed repositories and data sources) and emphasizes that the external API can remain stable regardless of internal deployment choices.

2.2 Mapping mXDE concepts to the Swedish TKB context

Although TKB is not literally an IHE "document sharing infrastructure", the architectural pattern is analogous:

• TKB services provide a coarse-grained, service-specific view of clinical content (e.g. GetAlertInformation, GetMedicationHistory, GetActivities)
• FHIR APIs provide a fine-grained, resource-oriented view of the same underlying data (AllergyIntolerance, Condition, MedicationRequest, Procedure, etc.)
• A "Data Element Extractor" in the Swedish context is typically:
  • a TKB→FHIR transformation layer (façade or synchronization process), or
  • logic co-located with the EHR or Inera's central platform that reads TKB payloads or local data structures and publishes FHIR resources with Provenance links back to the TKB calls, local documents or internal records

The QEDm profile describes how a Clinical Data Source exposes FHIR-based queries for clinical data elements to a Clinical Data Consumer, using standard search parameters and returning data with associated Provenance.

In our setting, QEDm can be seen as a reference model for what "good" FHIR APIs over TKB-backed content should look like.

2.3 Relevant parts of mXDE for this guide

The following parts of mXDE are architecturally relevant:

• Actors and responsibilities – mXDE section 1:45.1 (Data Element Extractor and Clinical Data Consumer, grouped with a QEDm Clinical Data Source)
• Grouped Server internals – mXDE section 1:45.4.3.1 (trigger → retrieve documents → decompose into FHIR resources → create Provenance → record AuditEvents)
• Deployment Models A/B/C – mXDE section 1:45.7 (central vs distributed Document Sharing and fine-grained data sources)
• Cross Profile Considerations – mXDE section 1:45.6 (mXDE as a component in a broader document sharing exchange, including access control considerations based on document-level consent and Provenance)

We do not re-use the document-centric parts of mXDE literally, but we re-use the architectural pattern:

"Keep the coarse-grained, existing exchange (TKB services / documents), but add a FHIR/QEDm-style data element layer with robust traceability and coexistence."

3. Transition Architectures (Patterns)

Instead of a time-based migration plan with phases, this section describes four architectural patterns.
Most real deployments will combine two or more of these over time.

Pattern A – FHIR Façade (Data Element Extractor at the system edge)

Idea: Add a FHIR API in front of an existing TKB-based system. The façade acts as a Data Element Extractor: it calls TKB services, transforms the payloads into FHIR resources and returns them to FHIR clients.

FHIR Clients → FHIR API (façade) → [TKB→FHIR transformation] → TKB Backend

Typical use: Regional EHRs and vendor platforms where:

• TKB services are already implemented and stable
• Data model refactoring to FHIR will take time
• There is a need for quick FHIR enablement to support pilots, NPÖ 2.0, or EHDS-related experiments

Relation to mXDE/QEDm:

• The façade is a grouped mXDE Data Element Extractor + QEDm Clinical Data Source, but the "documents" are TKB responses instead of XDS documents.
• The FHIR façade should:
  • expose search patterns compatible with QEDm where feasible
  • create FHIR Provenance resources that link back to the originating TKB interaction or local record, in line with mXDE recommendations.

Pros (architecture):

• Minimal change in the core EHR / backend
• Enables parallel TKB + FHIR consumption
• Good way to learn where TKB semantics map cleanly to FHIR and where deeper refactoring is needed

Cons (architecture):

• Transformation layer can become complex if not well-factored
• Performance and caching need careful design
• Still bound to TKB's conceptual model and limitations

Pattern B – Dual-Native APIs on a Shared Domain Model

Idea: Implement both TKB and FHIR endpoints on top of a shared, refactored domain model. TKB is retained as a legacy / compatibility API, FHIR is the primary external API.

TKB Clients  → TKB API  ↘
                           Shared Domain Model → Database
FHIR Clients → FHIR API ↗

Typical use: Inera national services (e.g. demographics, directories, patient summary services) and large regional platforms with long-lived TKB integrations.

Relation to mXDE/QEDm:

• This resembles an mXDE "Grouped Server": the same internal data store supports both coarse-grained and fine-grained interfaces.
• The internal model is "FHIR-shaped", but TKB operations are implemented as:
  • Queries/operations over the same model, or
  • Transient projections generated from FHIR resources

Pros (architecture):

• Single source of truth
• FHIR can be designed for EHDS and EEHRxF use cases from the start
• TKB can be deprecated per domain when ready, without changing the internal model

Cons (architecture):

• Requires deeper refactoring in the backend
• Dual API surface to maintain for a considerable time

Guidance for Inera:

• For new versions of national services where Inera is system owner, Pattern B is often the target state: make FHIR the "native" interface to the domain, and keep TKB as a compatibility layer with a planned sunset strategy.

Pattern C – FHIR Mirror / Central Clinical Data Source

Idea: Create a central FHIR data store (or several domain-specific ones) that receives data from multiple TKB-based systems and exposes it as FHIR for NPÖ, patient portals, analytics, and EHDS export.

Regional EHRs / TKB systems → [ETL/Streaming Extractor] → Central FHIR Server
                                                        ↘ Provenance to source
FHIR Clients (NPÖ, portals, analytics, EHDS gateways) → FHIR APIs (often QEDm-like)

Typical use:

• NPÖ-like scenarios where Inera aggregates data from many caregivers
• Patient portals and analytics platforms that need read-optimized FHIR access without touching operational EHRs
• EHDS / EEHRxF gateways that must provide standard FHIR-based export from heterogeneous sources

Relation to mXDE/QEDm:

• This maps closely to mXDE Deployment Models B/C – a central fine-grained Clinical Data Source that extracts from distributed repositories.
• The extractor components are mXDE Data Element Extractors, implemented as ETL or streaming pipelines from TKB (or other local sources) into FHIR, with Provenance back to the source.

Pros (architecture):

• Decouples operational EHRs from cross-organizational and EHDS-oriented workloads
• Makes it easier to adopt QEDm-like APIs for NPÖ and future EHDS proxy services
• Allows gradual onboarding of new source systems without changing the central API

Cons (architecture):

• Requires synchronization logic and monitoring (lag, error handling)
• Data duplication (operational vs. aggregated store)
• Write operations need careful design (who is allowed to write where?)

Guidance for Inera:

• For NPÖ-liknande tjänster and future EHDS/EEHRxF gateway functions, Pattern C is often the most realistic approach:
  • keep regional EHRs and TKB services as sources
  • central FHIR servers as aggregated Clinical Data Sources with QEDm-like capabilities

Pattern D – FHIR-Native Systems with TKB Compatibility

Idea: For new systems or major replacements, design them as FHIR-native from day one. TKB is added only if absolutely required for legacy integration.

FHIR Clients → FHIR API → FHIR-shaped domain model → Database
                   ↘ optional TKB adapter/bridge (for specific integrations)

Typical use:

• New national services
• New subsystem modules in regional EHR landscapes
• Vendor platforms aiming at EHDS "by design"

Relation to EHDS and EEHRxF:

• EHDS and EEHRxF emphasize standardized electronic health record formats, with FHIR as a core technical building block and priority data categories that must be supported across borders.
• FHIR-native design makes it easier to:
  • adopt HL7 Europe / EEHRxF FHIR IGs as they stabilize
  • integrate directly with mXDE/QEDm-style infrastructures without translation layers

Pros (architecture):

• Clean architecture, aligned with future European ecosystem
• Easier to adopt new FHIR IGs for EU priority data categories
• Less legacy baggage long-term

Cons (architecture):

• Requires explicit strategy for how to integrate with TKB while those services remain in use
• Higher initial investment if many existing systems still only support TKB

4. Strategy by System Type

This section reframes the earlier "Recommendations by context" in architectural terms, independent of project phases.

4.1 Inera National Services

Recommended primary pattern: Pattern B – Dual-Native APIs

• Design new versions of national services (demographics, directories, patient summaries etc.) with:
  • a FHIR-native domain model
  • both FHIR and TKB endpoints during a long transition
• Make FHIR the reference for EHDS/EEHRxF alignment; treat TKB as a compatibility layer.

Complementary pattern: Pattern C – FHIR Mirror / Clinical Data Source

• For NPÖ-type services and future EHDS gateways, aggregate data from many systems into a central FHIR server following mXDE/QEDm principles.

4.2 Regional EHR Systems and Vendor Platforms

Recommended evolution path: Pattern A → Pattern B

1. Short/medium term – Pattern A (FHIR façade)
   • Put a FHIR façade in front of existing TKB implementations
   • Use façade logic as a prototype Data Element Extractor:
     • learn which mappings are straightforward
     • identify domains where the underlying data model needs to change
2. Long term – Pattern B (dual-native on a shared model)
   • Refactor internal EHR domain models to be FHIR-shaped
   • Re-implement TKB services as operations on the same model
   • Plan a sunset strategy for TKB per domain when clients are ready

4.3 NPÖ, Analytics and Patient Portals

Recommended pattern: Pattern C – FHIR Mirror / Central Clinical Data Source

• Use ETL or streaming pipelines as Data Element Extractors from TKB and EHR systems into central FHIR stores
• Expose APIs:
  • for clinical viewing (NPÖ-like UI)
  • for patient access (portals, apps)
  • for secondary use / analytics where allowed by law and policy
• Make sure that:
  • every FHIR resource has a Provenance link to its source (system, TKB operation, local record)
  • there is a clear policy for how to follow these links for audit and context, as envisioned by mXDE.

4.4 New and "Greenfield" Systems

Recommended pattern: Pattern D – FHIR-Native with optional TKB bridge

• Design the domain model based on FHIR resources and profiles from:
  • Swedish national IGs
  • EEHRxF / HL7 Europe IGs where relevant
• Provide:
  • FHIR APIs as primary interface
  • small, targeted TKB bridges only where integration with legacy national services is needed

5. Summary of Patterns

6. Out-of-Scope Topics and Further Reading

This page is intentionally limited to architectural transition strategies.

The following aspects are treated in separate guidance:

• Semantic mappings (TKB → FHIR, ConceptMaps, terminology bindings)
• Security and access control (OAuth2, SMART-on-FHIR, mXDE/QEDm Provenance-driven access control, PDL/PDL2)
• Logging, audit and legal traceability

References:

• IHE mXDE – Mobile Cross-Enterprise Document Data Element Extraction
• IHE QEDm – Query for Existing Data for Mobile
• European Health Data Space (EHDS)
• European Electronic Health Record Exchange Format (EEHRxF)