Netherlands - Generic Functions for data exchange Implementation Guide
0.2.0-ballot - ci-build
Netherlands - Generic Functions for data exchange Implementation Guide
0.2.0-ballot - ci-build
Netherlands - Generic Functions for data exchange Implementation Guide - Local Development build (v0.2.0-ballot) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| Page standards status: Draft |
Generic Function Addressing (GFA) defines how healthcare parties can publish, discover, and use trusted addressing information for organizations, services, locations, and endpoints. Its purpose is to make healthcare data exchange interoperable and reliable by helping practitioners and systems route requests, referrals, data retrievals and notifications to the correct destination.
This specification is based on the IHE mCSD profile and reuses the actor and transaction definitions that were defined in that specification. You should be able to read this specification without prior knowledge of IHE mCSD, but a basic understanding of the FHIR specification is preferred.
Here is a brief overview of the processes that are involved:
This overview implies a decentralized architecture with local Data Source actors and LRZa Directory replicas. An important central component is the LRZa Administration Directory, but this central component is not a crucial asset at data exchange runtime (only for creating or updating addressable entities). The LRZa Directory periodically imports Organization, Location and Practitioner(-Role) resources from the KvK and DEZI-registry.
This specification is based on the IHE mCSD profile and constrains and profiles the mCSD specification for the Dutch national context. The following national choices apply:
Data model profiling: The national profiles SHALL be based on NL-core where available and SHALL be aligned with relevant IHE mCSD profile constraints.
Device resource addition: The Device resource is added as a national extension to support efficient endpoint lookup and query-routing. Device usage SHALL support national workflows including GF Localization and TA Notified Pull.
LRZa Directory operational role:
The LRZa Directory SHALL NOT support matching of care service entities (e.g. query for a specific type of HealthcareService or Endpoint). Matching SHALL be performed on a local Directory (LRZa replica). The LRZa Directory SHALL act as single source of truth and distribution point, and SHALL NOT have a direct operational role in healthcare data exchange transactions. For replication purposes, LRZa SHALL support search-type interactions from the mCSD ITI-90 transaction without search parameters for the initial load of the local replica.
No deletes:
Addressable entities (e.g. a Location or HealthcareService) may become inactive/deprecated over time, but their identifier will be used and referred to from health records for their lifetime. Therefore, deletion of addressable entities SHALL not be supported by the LRZa Directory. The status of an addressable entity may be adjusted to inactive, off, entered-in-error or whatever appropriate status for the resource type.
Each actor will now be discussed in more detail.
The LRZa Directory is the central national directory for publishing and distributing addressable entities. It is the authoritative source for nationally governed directory content and provides interfaces for administration and retrieval of updates. The LRZa Directory is not intended for runtime matching in operational healthcare workflows; searching/matching SHALL be performed on local replicas. This Directory provides an API for the 'Data Source' and 'Query & Update Client' that implements these CapabilityStatements:
A Data Source is a client/actor of an authorized party (e.g. an IT vendor or the care provider itself) that publishes and maintains directory entities on behalf of care providers. The Data Source actor SHALL use interactions conforming to CapabilityStatement ITI-130-NL, including create/update for Organization, Location, HealthcareService, Endpoint, and Device.
The Query & Update Client refers to two separate actors defined in IHE mCSD and are grouped for the Dutch national context. This actor uses the search-type interaction (without search parameters) for the initial load of the local Directory (replica). It also periodically synchronizes from the LRZa Directory to a local replica using history-type interactions and _since parameter to request incremental updates. It consumes search interactions conforming to CapabilityStatement ITI-90-NL and update-oriented interactions defined in CapabilityStatement ITI-91-NL.
For more information, see the synchronization example
The Query Client uses the local replica to find organizations, healthcare services, locations, endpoints, devices, and organizational relationships for routing and discovery. Note that the data exchange between Query Client and (local) Directory MAY use a proprietary interface. Use case 3 and use case 4 illustrate how to search for healthcare services and endpoints.
Transactions between Service Providers and the LRZa are defined here. Other (local or 3rd party) transactions are not specified here. These transactions MAY reuse/adopt IHE mCSD and FHIR transactions, but are not obliged.
The Data Source publishes entities to the LRZa Directory using create/update semantics as profiled in the Data Source capability statement. CapabilityStatement: ITI-130-NL
The Query Client loads/queries directory data for initial population of the local replication using search-type interactions without search parameters.
CapabilityStatement: ITI-90-NL
The Update Client retrieves changes from the LRZa Directory using history-type interactions per supported resource, optionally constrained by _since for incremental synchronization.
CapabilityStatement: ITI-91-NL
Within GF Addressing, several addressable entities are used to capture and publish information. An overview of the most common elements and relations between entities:
A brief description of the entities:
Healthcare services are used to publish which (medical) services are provided by a (child) Organization at some Location(s). Examples include surgical services, antenatal care services, or primary care services. These services in HealthcareService.type can be extended by references to specific ActivityDefinitions and PlanDefinitions that are supported. The combination of a HealthcareService offered at a Location may have specific attributes including contact person, hours of operation, etc. Typically, HealthcareServices use Endpoints that support receiving notifications or requests.
The NL-GF-HealthcareService profile is used to represent healthcare service offerings.
Key attributes:
| Attribute | Card. | Description |
|---|---|---|
| identifier (CustodianAssignedIdentifier) | 1..1 | identifier for provenance and traceability. |
| providedBy → Organization | 1..1 | The organization that provides this service. |
| type | 1..* | The type of service (required binding to NL-GF Service Types, including procedure and care-type codesystems in CBV, DHD, Geboortezorg, GGZ, NHG, NZa and WLZ). |
| type.supportedActivityDefinitions | 0..* | References to ActivityDefinitions or PlanDefinitions specifying the service type further. |
| specialty | 0..* | The specialty of the service (required binding). |
| name | 0..1 | A human-readable name for the service. |
| telecom | 0..* | Contact details for the service. |
| location → Location | 0..* | The location(s) where this service is available. |
| availableTime | 0..* | Times the service is available. |
| endpoint → Endpoint | 0..* | Technical endpoints for notifications or requests. |
Organizations are “umbrella” entities; these may be considered the administrative bodies under whose auspices care services are provided. Typically, (top-level)Organization-instances use Endpoints that publish healthcare data for other (healthcare) organizations to query. Departments of an institution, or other administrative units, may be represented as child Organizations of a parent Organization. The NL-GF-Organization profile is used to represent organizations and their hierarchical relations in this guide. Key attributes:
| Attribute | Card. | Description |
|---|---|---|
| identifier (URA or KVK) | 0..* | An Organization must have a URA or KVK identifier, or be partOf another Organization. |
| type | 1..* | Type of organization, including an SBI (Standaard Bedrijfsindeling) code (extensible binding to NL-GF Organization Types). |
| name | 1..1 | The name of the organization. |
| alias | 0..* | Alternative names. |
| telecom | 0..* | Contact details. |
| partOf → Organization | 0..1 | The parent organization (for departments or sub-units). |
| endpoint → Endpoint | 0..* | Technical endpoints used by this organization. |
An addressable entity may be reachable for electronic data exchange through electronic Endpoint(s). An Endpoint may be a FHIR server, a DICOM web service, OAuth token endpoint, or some other mechanism. Typically, Organizations, Devices and HealthcareServices refer to Endpoints. This relationship is meant to indicate that, e.g., a care provider (Organization) uses an Endpoint. An Endpoint also refers to one specific organization that manages the Endpoint (e.g. IT vendor); this is not the organization using the endpoint. The NL-GF-Endpoints profile is used to represent electronic access points for data exchange. Key attributes:
| Attribute | Card. | Description |
|---|---|---|
| status | 1..1 | The operational status of the endpoint (e.g. active, off). |
| connectionType | 1..1 | The type of connection (extensible binding to Core connection types and NL-GF Connection Types). |
| payloadType | 1..* | The payload type(s) supported (extensible binding to NL-GF Payload Types). |
| address | 1..1 | The technical address (URL) of the endpoint. |
| managingOrganization → Organization | 1..1 | The organization that manages this endpoint (e.g. IT vendor). |
Device resources are, in GF Addressing, used to represent software applications or technical systems involved in healthcare data exchange. A Device can reference one or more Endpoints that it uses/provides, enabling efficient endpoint lookup and query-routing in workflows such as GF Localization, eOverdracht, and TA Notified Pull. In this guide, Devices are also referenced from OrganizationAffiliation to indicate which technical system is authorized in the relationship between a care provider and an IT vendor. The NL-GF-Device profile is used to represent these technical systems and their endpoint references. Key attributes:
| Attribute | Card. | Description |
|---|---|---|
| identifier (DeviceUrn) | 1..1 | A globally unique URN identifier for the device/application. |
| udiCarrier | 0..* | UDI carrier information from e.g. EUDAMED or GS1 register (if applicable). |
| owner → Organization | 1..1 | The organization that owns/manages this device. |
| endpoint → Endpoint (extension) | 0..* | Endpoints associated with this device. |
Locations are physical places where care can be delivered such as buildings (NL: Vestiging), wards, rooms, or vehicles. A Location may have geographic attributes (address, geocode), attributes regarding its hours of operation, etc. Each Location is related to one Organization. A location may have a hierarchical relationship with other locations (e.g. building > floor > room). The NL-GF-Location profile is used to represent physical care-delivery locations. Key attributes:
| Attribute | Card. | Description |
|---|---|---|
| identifier (CustodianAssignedIdentifier) | 1..1 | identifier for provenance and traceability. |
| name | 1..1 | The name of the location. |
| type | 1..1 | The type of location. |
| status | 1..1 | The operational status (e.g. active, inactive). |
| address | 0..1 | The physical address. |
| managingOrganization → Organization | 1..1 | The organization responsible for this location. |
| partOf → Location | 0..1 | The parent location (e.g. building → floor → room). |
Practitioner resources represent healthcare professionals as persons, independent of where or in which role they are currently working. In GF Addressing, a Practitioner is used as the stable identity anchor for professional identification across organizations, and can be linked to one or more PractitionerRole resources that describe context-specific roles and specialties. Practitioner identifiers typically include a DEZI number and MAY include a BIG number for professional registration details. The NL-GF-Practitioner profile is used to represent healthcare professionals. Key attributes:
| Attribute | Card. | Description |
|---|---|---|
| identifier (DEZI/BIG) | 0..* | Professional identifiers, typically DEZI and optionally BIG. |
| name | 1..* | Human name of the practitioner. |
| qualification | 0..* | Professional qualifications, licenses, or registrations relevant for care delivery. |
PractitionerRole resources are used to define the specific roles, specialties, and responsibilities that a Practitioner holds within an Organization. PractitionerRole enables precise modeling of relationships between practitioners and organizations and MAY represent employment relationships. It supports scenarios like assigning practitioners to departments, specifying their roles (e.g., surgeon, nurse), and linking them to particular healthcare services or locations. A PractitionerRole may have contact details for phone, mail, or direct messaging, but should not contain privacy-sensitive data. The NL-GF-PractitionerRole profile is used to represent practitioner roles and responsibilities within organizations. Key attributes:
| Attribute | Card. | Description |
|---|---|---|
| identifier (CustodianAssignedIdentifier) | 1..1 | Identifier for provenance and traceability; UZI/DEZI-number |
| practitioner → Practitioner | 1..1 | The practitioner fulfilling this role, identified by its, e.g., BIG-number. |
| organization → Organization | 1..1 | The organization where the practitioner works. |
| code | 1..* | The role(s) the practitioner performs. |
| specialty | 0..* | The specialty of the practitioner in this role. |
| telecom | 0..* | Contact details (no privacy-sensitive data). |
OrganizationAffiliation resources are used to represent relationships between organizations, such as a software vendor managing the Endpoint that is used by a care provider. The LRZa Directory uses OrganizationAffiliations to authorize incoming create and update interactions of service providers. It could also be used to represent multiple care providers working together under some agreement (e.g. in a region). The NL-GF-OrganizationAffiliation profile is used to represent organizational relationships in this guide. Key attributes:
| Attribute | Card. | Description |
|---|---|---|
| active | 1..1 | Whether this affiliation is currently active. |
| organization → Organization | 1..1 | The care provider organization. |
| participatingOrganization → Organization | 1..1 | The affiliated party (e.g. IT vendor). |
| code | 1..* | The type of affiliation (required binding to NL-GF Authorization Types). |
| device (extension) | 0..* | Device identifier(s) authorized in this affiliation. |
A Data Source actor SHALL use mTLS for transport layer security. Qualified certificates from Qualified Trusted Service Providers (like PKIoverheid) should be trusted. (GF-Adressering, ADR#178).
The LRZa-Directory SHALL only support creation/updates of OrganizationAffiliations by Care Providers, not by the parties that are being authorized (the .participatingOrganization).
This sequence shows a two-step onboarding flow: first, the care provider administrator creates an OrganizationAffiliation that authorizes the service provider (and optionally a Device). After this authorization exists, the service provider is able to register their Endpoints and Devices (if not already registered). Finally, the care provider administrator is able to register and update the remaining mCSD resource types in the application of the service provider (e.g. the EHR).
The following sequence diagram illustrates how a Query Client and Update Client synchronize data from the LRZa Directory into a local replica:
The patient, Vera Brooks, consults with her physician who recommends surgery. The physician can assist the patient in finding a suitable care provider, taking into consideration the location and specialty for orthopedic surgeons.
Dr. West just created a referral (for patient Vera Brooks from use case #3). The EHR has to notify Hospital East and the Orthopedic department of this referral. This may include some recurring requests: