POC IZNC - Integrated Care Network Communication
0.1.2 - ci-build
POC IZNC - Integrated Care Network Communication - Local Development build (v0.1.2) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
⚠️ STATUS: DRAFT - FOR REVIEW
This specification is currently in draft status and is open for review and feedback. Implementation details may change based on community input and practical experience.
Author: roland@headease.nl
This document is released under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.
This document describes the role of mCSD (Mobile Care Services Discovery) and Generieke Functie Adressering (Generic Function Addressing) in the context of the POC IZNC implementation.
mCSD is ONLY for healthcare provider infrastructure:
The POC IZNC uses BSN-based discovery for patients/users, which is completely separate from mCSD. Understanding mCSD is important for the broader Matrix specification context, particularly for healthcare provider discovery and cross-organization federation.
mCSD (Mobile Care Services Directory) is an IHE (Integrating the Healthcare Enterprise) profile that provides a structured way to discover healthcare services, practitioners, organizations, and locations. It uses FHIR resources to create a searchable directory of care services and providers.
Core mCSD Resources (healthcare provider infrastructure):
Additional Resources (may be published in mCSD, but NOT identified by UZI/URA):
Important: BSN (patient identifier) is completely separate from mCSD. mCSD is specifically for discovering healthcare provider infrastructure (practitioners and organizations) using UZI and URA numbers.
Generieke Functie Adressering is a Dutch healthcare initiative that implements mCSD-based directory services for routing and addressing between healthcare organizations.
The LRZA (National Registry for Healthcare Addressing) serves as the central index where:
┌─────────────────────────────────────────────┐
│ LRZA (Central Registry) │
│ - URA → mCSD endpoint mapping │
│ - One entry per healthcare organization │
└────────────────┬────────────────────────────┘
│
┌────────┴────────┐
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Organization │ │ Organization │
│ A mCSD │ │ B mCSD │
│ Endpoint │ │ Endpoint │
├──────────────┤ ├──────────────┤
│ - Practitioners│ │ - Practitioners│
│ - Roles │ │ - Roles │
│ - Services │ │ - Services │
│ - Matrix IDs │ │ - Matrix IDs │
└──────────────┘ └──────────────┘
Note: LRZA is not yet capable of processing Matrix-related information. Currently, NUTS discovery is used to determine the mCSD endpoint based on URA number.
The Matrix specification for instant network communication relies heavily on mCSD for:
From the Matrix specification (Section 7):
Matrix User Discovery via mCSD
- Healthcare providers with Matrix contact information are published in mCSD records
- Matrix addresses are stored in the telecom array of Practitioner, Patient, and RelatedPerson resources
- Applications use mCSD to look up providers by function or location
- During identification and onboarding, UZI number, URA number, and role code(s) are linked to Matrix user accounts as 3PIDs
For Healthcare Providers (Practitioners):
For RelatedPersons and Clients:
The Matrix specification describes how practitioner identity flows through mCSD:
Matrix contact information is stored in the telecom array of FHIR resources using specific extensions:
Example: Practitioner Resource with Matrix ID
{
"resourceType": "Practitioner",
"id": "6a6b85e9-f7d8-4b62-8dc5-94f00b1d6594",
"identifier": [{
"system": "http://fhir.nl/fhir/NamingSystem/uzi-nr-pers",
"value": "123456789"
}],
"name": [{
"family": "Janssen",
"given": ["Dr. H."]
}],
"telecom": [
{
"system": "email",
"value": "dr.janssen@hospital-a.nl",
"use": "work"
},
{
"system": "other",
"value": "@dr.janssen:matrix.hospital-a.nl",
"use": "work",
"extension": [{
"url": "http://hl7.org/fhir/StructureDefinition/contactpoint-purpose",
"valueString": "matrix-messaging"
}]
}
]
}
ContactPoint Extensions for Matrix:
matrix-messaging: For individual Matrix user IDs (@user:homeserver.nl)matrix-homeserver: For homeserver addresses (homeserver.nl) at organization level{
"resourceType": "Organization",
"id": "07d91b7d-eb06-47ef-b077-28e0d274c161",
"name": "Hospital A",
"identifier": [{
"system": "http://fhir.nl/fhir/NamingSystem/ura",
"value": "00000001"
}],
"contact": [{
"purpose": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/contactentity-type",
"code": "ADMIN"
}]
},
"telecom": [{
"system": "other",
"value": "matrix.hospital-a.nl",
"use": "work",
"extension": [{
"url": "http://hl7.org/fhir/StructureDefinition/contactpoint-purpose",
"valueString": "matrix-homeserver"
}]
}]
}]
}
The POC IZNC implementation takes a different approach that abstracts away mCSD complexity:
Key Point: POC IZNC uses BSN (patient identifier) for discovery, which has nothing to do with mCSD. mCSD is only relevant when discovering practitioners (UZI) or organizations (URA).
Matrix Specification Approach (with mCSD):
Chat App → mCSD Lookup → Matrix Homeserver
↓
FHIR Resources
(Practitioner, Organization)
POC IZNC Approach (BSN-based):
Chat Backend → Matrix Bridge API → Matrix Homeserver
↓
BSN Mapping DB (encrypted)
Although POC IZNC doesn't require mCSD for basic operation (BSN-based discovery works for existing care network members), mCSD might be used for practitioner-related operations:
Key Point: mCSD is not required for core POC functionality (viewing existing care networks, reading/creating messages), but might be useful for practitioner management features.
Beyond the POC scope, mCSD becomes essential specifically for practitioner discovery (not patient/BSN discovery) in these scenarios:
When a care network includes practitioners from other organizations:
Example Flow (Practitioner Discovery):
Organization A needs to invite Dr. Smith (practitioner) from Organization B
1. Organization A has: UZI number of Dr. Smith (123456789) ← Practitioner identifier
2. Query LRZA: URA of Organization B → mCSD endpoint ← Organization identifier
3. Query mCSD: GET /Practitioner?identifier=http://fhir.nl/fhir/NamingSystem/uzi-nr-pers|123456789
4. Extract Matrix ID from result: @dr.smith:matrix.hospital-b.nl
5. Matrix Bridge invites: @dr.smith:matrix.hospital-b.nl to care network
Note: This is for practitioner discovery only. Patients (BSN) are NOT discovered via mCSD.
When a practitioner logs in for the first time:
Note: This is for practitioners only. Patients don't authenticate via UZI/URA - they use BSN which is NOT managed by mCSD.
When a healthcare organization switches vendors:
If the POC were to integrate with mCSD for practitioner management features, these components would be needed:
class MCSDClient:
def lookup_practitioner_matrix_id(self, uzi_number: str) -> Optional[str]:
"""
Look up practitioner's Matrix ID via mCSD
1. Determine organization's mCSD endpoint (via LRZA/NUTS)
2. Query mCSD for Practitioner by UZI number
3. Extract Matrix ID from telecom array
4. Return Matrix ID or None
"""
pass
def lookup_organization_homeserver(self, ura_number: str) -> Optional[str]:
"""
Look up organization's Matrix homeserver via mCSD
1. Determine organization's mCSD endpoint (via LRZA/NUTS)
2. Query mCSD for Organization by URA number
3. Extract homeserver from telecom array
4. Return homeserver domain
"""
pass
Synchronize Matrix IDs back to mCSD:
class MCSDSync:
def register_matrix_id(self, uzi_number: str, matrix_id: str):
"""
Register Matrix ID in local mCSD
1. Find or create Practitioner resource
2. Add matrix-messaging telecom entry
3. Update mCSD database
"""
pass
Add endpoints for getting practitioner details and searching practitioners:
POST /api/v1/practitioners/lookup
Purpose: Get full details about a practitioner from mCSD
Request:
{
"uziNumber": "123456789"
}
Response:
{
"uziNumber": "123456789",
"matrixUserId": "@dr.smith:matrix.hospital-b.nl",
"name": "Dr. H. Janssen",
"organization": {
"ura": "00000002",
"name": "Hospital B"
},
"role": {
"code": "158965000",
"display": "Medical practitioner"
},
"homeserver": "matrix.hospital-b.nl",
"email": "dr.janssen@hospital-b.nl"
}
POST /api/v1/practitioners/search
Purpose: Search for practitioners to invite to care network
Request:
{
"name": "Janssen",
"uraNumber": "00000002", // Optional: filter by organization
"roleCode": "158965000" // Optional: filter by role
}
Response:
{
"practitioners": [
{
"uziNumber": "123456789",
"matrixUserId": "@dr.janssen:matrix.hospital-b.nl",
"name": "Dr. H. Janssen",
"organization": "Hospital B",
"role": "Medical practitioner"
},
{
"uziNumber": "987654321",
"matrixUserId": "@dr.janssen2:matrix.hospital-b.nl",
"name": "Dr. M. Janssen",
"organization": "Hospital B",
"role": "Specialist"
}
]
}
Current Implementation (v0.1.x):
Optional Enhancement (could be added to v0.1.x or v0.2.x):
Future Enhancement (v0.2.x+):
Production implementations should consider:
What mCSD Handles (Healthcare Provider Infrastructure):
What mCSD Does NOT Handle (Patient/User Identity):
Version: 0.1.0 Status: Draft Specification - Open for Review Last Update: 2025-01-19