Ministerie van Volksgezondheid,Welzijn en Sport
Generic Functions & Patterns - Implementation Guide
0.9.9 - trial-use
Ministerie van Volksgezondheid,Generic Functions & Patterns - Implementation Guide
0.9.9 - trial-use
Generic Functions & Patterns - Implementation Guide - Local Development build (v0.9.9) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| Page standards status: Draft |
Patient data is often divided over multiple data holders. Generic Function Localization provides a standardized framework that enables healthcare professionals to discover which organizations hold relevant patient data of a specific type.
GF-Localization is based on the IHE MHD profile and follows the choices made by the MinvWS Localization working group, see GF-Lokalisatie, ADR's. This guide specifies the choices made. Most impactful/striking choice are:
Here is a brief overview of the processes that are involved:
These processes require the use of pseudonyms generated by the national Pseudonymization Service (PRS). The Localization service-response provides a list of data holders; the endpoints of these data holders (e.g. FHIR or DICOM-urls) need to be resolved using a Care service (Query) Directory. This process is illustrated in this example.
For more detail on the topology of GF-Localization, see GF-Lokalisatie, ADR-2. Each component, data model, and transaction will be discussed in more detail.
A (Medical Record) Localization Service is responsible for managing the registration, maintenance, and publication of localization records. It should be able to create and update localization records. A Localization Service MUST implement these FHIR capabilities
The Pseudonymization Service (PRS) is responsible for creating recipient-scoped pseudonyms of patient identifiers using HKDF and Oblivious Pseudorandom Function (OPRF) protocols. See GF Pseudonymisation for the full specification.
A Localization Client is responsible for registering and managing localization records at the Localization Service on behalf of healthcare organizations. The client is typically embedded within or integrated with Electronic Health Record (EHR) systems, Picture Archiving and Communication Systems (PACS), or other clinical systems that manage patient data.
The Localization Client MUST support the following capabilities:
The client SHALL be able to create and register List resources (localization records) at the Localization Service. The client MUST support Bundle transactions to register localization records:
transactionPseudonymization Integration: Before submitting localization records, the client MUST compose a pseudonymized patient identifier using the Pseudonymization Service (PRS). When the pseudonym is forwarded to the NVI, the client packages the JWE and blind_factor together as a base64url-encoded JSON object:
{
"evaluated_output": "<JWE compact serialization>",
"blind_factor": "<base64url-encoded blind_factor>"
}
This object is used in the subject.identifier.value element (using the system http://minvws.github.io/generiekefuncties-docs/NamingSystem/nvi-identifier).
Data Holder Identification: The client MUST include the appropriate organization identifier (URA) in the nl-gf-localization-custodian extension of each localization record to identify the data holder/custodian.
Example Bundle Transaction: For more information on the content, see the paragraph on Localization record
{
"resourceType": "Bundle",
"id": "nvi-org1",
"entry": [
{
"request": {
"method": "POST",
"url": "List"
},
"resource": {
"resourceType": "List",
"extension": [
{
"valueReference": {
"identifier": {
"system": "http://fhir.nl/fhir/NamingSystem/ura",
"value": "11111111"
}
},
"url": "http://minvws.github.io/generiekefuncties-docs/StructureDefinition/nl-gf-localization-custodian"
}
],
"subject": {
"identifier": {
"system": "http://minvws.github.io/generiekefuncties-docs/NamingSystem/nvi-identifier",
"value": "eyJldmFsdWF0ZWRfb3V0cHV0IjoiSldFX0ZST01fUFJTIiwiYmxpbmRfZmFjdG9yIjoiQ0xJRU5UX0dFTl9CTElORF9GQUNUT1IifQ"
}
},
"source": {
"identifier": {
"system": "http://minvws.github.io/generiekefuncties-docs/NamingSystem/oauth-client-id",
"value": "ehr-client-org2"
}
},
"status": "current",
"mode": "working",
"emptyReason": {
"coding": [
{
"code": "withheld",
"system": "http://terminology.hl7.org/CodeSystem/list-empty-reason"
}
]
},
"code": {
"coding": [
{
"code": "MedicationRequest",
"system": "http://minvws.nl/CodeSystem/nl-gf-data-categories-cs",
"display": "Medicatie voorschrift"
}
]
}
}
}
],
"type": "transaction"
}
The client SHALL support searching for List resources (localization records). This enables healthcare professionals to discover which organizations hold relevant patient data. The Localization Client SHALL support the following search parameters:
Client SHALL either use the subject:identifier or source:identifier in a search.
Example Search Query:
GET [base]/List?subject:identifier=http://minvws.github.io/generiekefuncties-docs/NamingSystem/nvi-identifier|UHN1ZWRvYnNuOiA5OTk5NDAwMw==&code=LABBEPALING
The search operation returns a Bundle of type searchset containing matching List resources, allowing the client to identify which data holders have specific types of patient data.
This response will not contain the (pseudomized) subject.identifier for privacy/security reasons.
For detailed OPRF integration requirements, see GF Pseudonymisation and the reference implementation.
Within GF-Localization the NL-gf-localization-List profile is used to register, search, and validate localization records (NL-GF-IG, ADR#10). This data model basically states "Care provider X has data of type Y for Patient Z". It contains the following elements:
client_id) of the specific software installation (e.g., EHR deployment) that registered this localization record.emptyReason is set to withheld because this List signals the existence of data at a custodian, without enumerating the actual records. The List resource is used as a localization pointer, not as a container for document referencesA Location record example is in the IG artifacts.
See GF Pseudonymisation for PRS authentication requirements.
Scenario: Dr. Carter, a radiologist at a care provider organization, performs an imaging study for a patient. To enable data discovery by other healthcare professionals, Dr. Carter's organization must register the existence of this imaging data in the national localization index (NVI). This process involves pseudonymizing the patient's identifier, creating a localization record, and submitting it to the NVI with the appropriate authorization attributes.
The following diagram illustrates the registration workflow, including interactions between the radiologist, the PACS system and the NVI. For brevity, interactions to the Pseudonymization Service are left out here.
sequenceDiagram
actor doctor as Dr. Carter<br/>(Internist)
participant ehr as EHR @<br/>(Care Provider, URA 123)
participant prs as Pseudonymization<br/>Service (PRS)
participant nvi as Localization Service<br/>(NVI)
doctor->>ehr: Register finding at first consult<br/>for patient (BSN:987654321)
ehr->>ehr: Create Encounter and Condition for patient
Note over doctor,nvi: Pseudonymization
ehr->>ehr: Generate context info +<br/>HKDF key derivation + OPRF blinding
activate prs
ehr->>prs: POST /evaluate blinded_input
prs->>prs: Evaluate and encrypt<br/>with NVI public key
prs-->>ehr: JWE (encrypted pseudonym)<br/>+ blind_factor retained
deactivate prs
Note over doctor,nvi: Registration
ehr->>ehr: Create List resource with:<br/>- subject.identifier.value (Pseudo-BSN JWE)<br/>- code (data type)<br/>- source (Device)<br/>- extension.custodian (Organization URA)
ehr->>nvi: POST Bundle (transaction) with List resource
nvi->>nvi: Decrypt JWE and unblind<br/>to get final Pseudo-BSN
nvi-->>ehr: 200 OK, Bundle (transaction-response)
Scenario: Dr. Smith, a cardiologist at Hospital A, is treating a patient who was recently referred from another hospital. She needs to know what imaging data (X-rays, CT scans, MRIs) might be available from other healthcare providers to avoid unnecessary duplicate examinations and to get a complete picture of the patient's medical history.
sequenceDiagram
actor doctor as Dr. Smith<br/>(Cardiologist)
participant ehr as EHR System @<br/>(Care Provider, URA 456)
participant prs as Pseudonymization<br/>Service (PRS)
participant nvi as Localization Service<br/>(NVI)
participant addressing as Addressing Service
participant ehr_reg as EHR @<br/>(Care Provider)
doctor->>ehr: Request data for patient (BSN:987654321)
Note over doctor,ehr_reg: Pseudonymization
ehr->>ehr: Generate context info +<br/>HKDF key derivation + OPRF blinding
activate prs
ehr->>prs: POST /evaluate blinded_input
prs->>prs: Evaluate and encrypt<br/>with NVI public key
prs-->>ehr: JWE (encrypted pseudonym)
deactivate prs
Note over doctor,ehr_reg: Localization
ehr->>ehr: Prepare search with Pseudo-BSN (JWE) +<br/>retain blind_factor
ehr->>nvi: Search /List?<br/>subject:identifier={JWE} &code={data-type}
nvi->>nvi: Decrypt JWE and unblind<br/>to get final Pseudo-BSN
nvi->>nvi: Search localization records
nvi-->>ehr: Bundle (searchset) with List resources<br/>containing data holder organizations (URAs)
ehr->>ehr: Extract organization URAs<br/>from List.extension.custodian
Note over doctor,ehr_reg: Addressing and fetching data
loop for each data holder organization (URA)
ehr->>addressing: Search /Organization?identifier=ura|{URA}<br/>&_include=Organization:endpoint
addressing-->>ehr: Organization + Endpoint resources
ehr->>ehr_reg: GET /Condition?subject=bsn|987654321
ehr_reg-->>ehr: Condition resources
end
ehr-->>doctor: Display consolidated list of<br/>conditions to Dr. Smith
Scenario: A healthcare organization needs to retrieve all localization records it has registered in the National Localization Service (NVI). This is useful for administrative purposes, data quality checks, reconciliation, or audit trails. This query retrieves all localization records registered by a specific client/system (the Localization Client)
GET [base]/List?source:identifier=http://minvws.github.io/generiekefuncties-docs/NamingSystem/oauth-client-id|ehr-client-org2
Response: The NVI returns a Bundle of type searchset containing all matching List resources registered by the specified organization or client.
Potential future enhancements to the Localization Service include: