Technical Specifications PoC's 11 & 13 "BgZ referral and eOverdracht using partly harmonized notified pull"

[jorritspee]

Demo Script

The demo is performed by couples of two parties: the Sender and the Receiver.

Steps:

• Step 1: Receiver shall publish a representative selection of real life organizational entities in an mCSD Directory.
• Step 2: The demo consists of showing a handoff or referral (the workflow-task) where a Sender-application uses the GF Addressing to find a receiving healthcare service and location and obtain the associated endpoint to send the notification.
• Step 3: The receiving organization can show that the hand-off/referral comes to the right location/part of the organization instead of a general or organization-wide list/inbox.
• Step 4: Healthcare professional logs into EHR of Receiver using Dezi
• Step 5: Receiver sends a request for patient-identifying data to Sender
• Step 6: Receiver updates status of Task living at Sender that represents the referral or handoff

Parties

Vendor	Sender eO	Receiver eO	Sender BgZ	Receiver BgZ	Date end demo
Gerimedica	Y	Y	N.a	N.a	1st april
Nedap	Y	Y	N.a.	N.a.	1st april
SYS (EPD DiSy)	N.a.	N.a.	Y	x	20 April
Topicus	N.a.	N.a.	Y	Y	20 April

KPN is presumed to be out of PoC 11 and will participate in other PoCs.

The demo on the 1st of April will be bi-directional where parties perform both the role of Sendor and Receiver.
The demo on the 20th of April will have Sys refer to Topicus, and Topicus refer to itself (fallback to be evaluated: see if Nedap/Gerimedica could be receiver).

Principles

1. Use cases are eOverdracht (same as PoC 8) and BgZ referral (the same use case as PoC 9)
2. All needed generic functions are in scope, and implemented using the nl-generic-functions-ig
   • Authentication of organisations
     • We use Twiin TA Authentication 1.0.0
     • We use x509Credentials based on fake or test UZI-server-certs to identify and authenticate Sender and Receiver
   • Authentication of persons
     • The healthcare professional logs in once at the local Receiver EHR using Dezi. The resulting Dezi-claims are then transported to the Data-holder-organisation as a Verifiable Credential (VC) conforming to the Twiin TA Authentication.
     • We use the DeziIDTokenCredential for transport of the Dezi attestation.
       • When requesting an access token from the Nuts node, pass the "verklaring" from the UserInfo object as id_token property.
     • Key properties: single login at local EHR, works for both Notified Pull (1 data holder) and (Indexed) Pull (n data holders), Data-holder can verify integrity of identity-claims, Data-holder trusts Data-user-organisation not to mix up user sessions internally
   • Addressing (also on sub-organisation-level)
     • We use GF Addressing
   • Authorization
     • We use proposal GF Authorization
   • Notification
     • We use a notification mechanism that is based on the Twiin TA NP 1.0.1
     • This script will use a minimized version of the "dunne notificatie", the exact data model is specified in this script
3. Routing is in scope, we use the specifications in the Twiin Technical Agreement Routing
4. Notification is in scope
   • we use the notification message data structure that is defined in the Twiin TA Notified Pull (that was also part of PoC 9)
5. We use the current BgZ STU3 resource profiles
   • Rationale: minimize changes in current FHIR-data
   • Rationale: mixing STU3 for 'data' and Tasks and R4 for mCSD/Addressing seems like a bad idea. But we need to be able to support two FHIR-versions in parallel anyway to be able to implement new information standards (usually a dakpan-constructie is used in The Netherlands where at 1 point in time 2 versions need to be supported)
6. Data in scope is: Patient (in intersection of BgZ and eOverdracht), BloodPressure (in intersection of BgZ and eOverdracht), BodyWeight (in intersection of BgZ and eOverdracht)
   • Rationale: This PoC is not about data. But we need some data to show that it works. I just picked 3 profiles that are the same in eO and BgZ and are lightweight.
7. This specification is primarily aimed at developers that use the open source software Knooppunt to implement the generic functions and the open source software Nuts v6 to implement the generic function Authentication

Step 0: Preparation

1. Deploy Knooppunt
2. Deploy Nuts node as part of Knooppunt or independent
3. Create Organization Identity: https://wiki.nuts.nl/books/implementing-a-nuts-use-case/page/1-create-organization-identity
4. Use x509credential based on fake or test uzi cert
5. Dezi Login:
   Senders must set up a local Dezi login. To do so, they need to request and complete the following form:
   https://www.dezi.nl/documenten/2025/12/18/aanvraagformulier-dezi-client-dezi01.1
   Technical documentation for setting up the login is available here:
   https://www.dezi.nl/leveranciers
   Please note that this concerns the CIBG Dezi test environment only; the iRealisatie test environment is out of scope.

Step 1: Publish HealthcareServices, Endpoints, Locations

• eOverdracht: see Step 1 of Technical Specifications PoC 8 "eOverdracht" #73
• BgZ: see Step 1 of Technical specifications PoC 9 "BgZ referral" #72

Step 2: Sender sends notification

• BgZ: see Step 2 of Technical specifications PoC 9 "BgZ referral" #72
• Use the following Notification-Task (STU3) data structure (based on Twiin TA NP):

{
  "resourceType": "Task",
  "basedOn": [
    {
      "identifier": {
        "system": "http://example.com/tasks",
        "value": "workflow-task-identifier-value-sending-party"
      }
    }
  ],
  "status": "requested",
  "intent": "proposal",
  "code": {
    "coding": [
      {
        "code": "pull-notification",
        "system": "http://fhir.nl/fhir/NamingSystem/TaskCode"
      }
    ]
  },
  "requester": {
    "agent": {
      "identifier": {
        "system": "urn:ietf:rfc:3986",
        "value": "software-uuid-or-oid-sending-party"
      }
    },
    "onBehalfOf": {
      "identifier": {
        "system": "http://fhir.nl/fhir/NamingSystem/ura",
        "value": "12345678"
      }
    }
  },
  "owner": {
    "identifier": {
      "system": "http://fhir.nl/fhir/NamingSystem/ura",
      "value": "87654321"
    }
  }
}

• Receiver PDP authorizes incoming notification request using policy "1. Receiver organisation authorizes incoming notification message": Authorization in PoC 11&13 #88

Step 3: The receiving organization can show that the hand-off/referral comes to the right location/part of the organisation instead of a general or organization-wide list/inbox.

• eOverdracht: see step 3.1 until and including 3.9 of Technical Specifications PoC 8 "eOverdracht" #73
• BgZ: see step 3.1 until and including 3.5 of Technical specifications PoC 9 "BgZ referral" #72
• Sender PDP authorizes incoming Task read request using policy "2. Sender organisation authorizes incoming read-request on Workflow/eOverdracht-Task": Authorization in PoC 11&13 #88

Step 4: Healthcare professional logs into their own EHR (that of the Receiver) using Dezi

The Data-holder-organisation needs to verify which natural person wants to access data and that this person is related to the Data-user-organisation. The Dezi attestation obtained here will be transported as a Verifiable Credential in Steps 5 and 6.

1. User logs into Receiver EHR
   • EHR redirects to Dezi
   • Use this specification (version January 2026) for the CIBG-Dezi-testing-environment
2. User is logged into EHR of Receiver (Data-user)
   • Dezi attestation is available inside the EHR user session
   • These claims will be included in access token requests in subsequent steps

Step 5: Receiver sends a request for patient-identifying data to Sender

1. Receiver EHR finds correct endpoints of Sender in its Query Directory
   • FHIR endpoint (which payloadType?)
   • Access token endpoint (payloadType: Nuts-OAuth)
2. Receiver requests access token using Nuts OAuth endpoint
   • See: Requesting access (outbound)
   • Either use Knooppunt or project-gf version of Nuts node
   • The Dezi attestation ("verklaring") from the Dezi UserInfo object, from Step 4 is included in the access token request as id_token
     • The Nuts node will wrap this attestation in a DeziIDTokenCredential
   • See: Getting an access token
3. Sender (Data-holder) handles incoming access token request
   • Nuts-node handles incoming request without manual action
   • Either use Knooppunt or project-gf version of Nuts node
4. Receiver sends data request
   • Receiver puts received access token in HTTP header Authorization, prefixed by Bearer
   • Receiver XIS follows the references in Task.input for Patient, BloodPressure, BodyWeight OR Composition
   • Receiver XIS fetches:
     • Composition if it is mentioned in the Task.input, OR
     • Patient
     • BloodPressure
     • BodyWeight
5. Sender (Data-holder) handles incoming data request
   • Data-holder introspects the access token via the Nuts-node introspect-token endpoint
     • See: Verifying access tokens
       • Either use Knooppunt or project-gf version of Nuts node
   • From the introspection response, the Data-holder extracts:
     • Data-user organisation claims (organization_ura)
     • Healthcare professional Dezi claims (employee_roles)
   • Data-holder PEP sends request authorization request to Data-holder PDP with the following claims from token introspection:
     • subject.properties.subject_id = employee_identifier
     • subject.properties.subject_role = employee_roles
     • subject_organization_id = organization_ura
     • subject_facility_type = "" (not needed in PoC 11 because no explicit consent is required)
     • client_qualifications = scope
     • Patient can be referred to by FHIR Patient ID or BSN
   • Sender PDP authorizes incoming data read/search requests using policy "3. Sender organisation authorizes incoming read- and/or search-request(s) on data": Authorization in PoC 11&13 #88
6. Receiver XIS shows the FHIR-resources that it supports
   • Patient (in intersection of BgZ and eOverdracht)
   • BloodPressure (in intersection of BgZ and eOverdracht)
   • BodyWeight (in intersection of BgZ and eOverdracht)

Step 6: Receiver updates status of Task living at Sender that represents the referral or handoff

1. Receiver EHR finds correct endpoints of Sender in its Query Directory
   • fhir endpoint, Which payloadType?
   • access token endpoint, payloadType Nuts-OAuth
2. Receiver requests access token using Nuts OAuth endpoint
   • https://wiki.nuts.nl/books/implementing-a-nuts-use-case/page/requesting-access-outbound
   • Dezi-id-token not needed
3. Sender (Data holder) handles incoming access token request
   • Nuts-node handles incoming request without manual action
4. Receiver sends data requests
   • PUT on Task
5. Data holder handles incoming data request
   • Sender PDP authorizes incoming Task update requests using policy "4. Sender organisation authorizes incoming update-request on Task": Authorization in PoC 11&13 #88

[gasperr]

What exactly is the purpose of subscriptions here? Sender creates a subscription on behalf of the receiver then, so receiver is notified when a workflow task is created? So something like this?

{
  "resourceType": "Subscription",
  "id": "example",
  "status": "requested",
  "reason": "BgZ Referral Workflow Task Creation",
  "criteria": "Task?code=http://snomed.info/sct|3457005",    <-- this would be the workflow task code
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://receiver-notification-endpoint",
    "payload": "application/fhir+json",
    "header": [
      "Authorization: Bearer something dynamic something something?"
    ]
  }
}

If that's the case, then I think this Subscription doesn't serve any purpose, because sender knows already when to notify, no? What really matters is the notification message, not the subscription itself.

Reading this: https://www.hl7.org/fhir/R4/subscription.html#2.46.7.1 empty payload notification that eOverdracht currently defines isn't so weird.

What do you think? Or what am I missing - why subscriptions?

[jorritspee]

What do you think? Or what am I missing - why subscriptions?

Well I always thought that in the FHIR-world Subscriptions where mandatory when you want to send a Notification.
@bramwesselo can you shed your light on this?

[bramwesselo]

I think we have the assumption of using the R5-subcription-backport; In that backport, an Notification Event Bundle requires a subscriptionStatus (with a required reference to a subscription).

[jorritspee]

For now, we will just reuse the notification mechanism that were part of PoC 8 and PoC 9. So no fancy FHIR Notification or Messaging.

[SimonVeldhuijzen]

Do I understand this script correctly when I say that this is just Poc 8/9, but with the addition of logging in through Dezi and checking consent through Mitz? As far as I know, consent in eOverdracht is implicit. What role does Mitz then play in this script?

[jorritspee]

Hi Simon,
Mitz is not in scope for this script.
This script must become: PoC 8/9 + Dezi + Authorization
Dezi stuff: #85
Authorization stuff: #88

[reinkrul]

If Authorization is in scope, maybe we should add steps to the test script that show it's functioning? E.g. non-happy flows (fetching resources not given access to).

[edwindoit]

@reinkrul do we already know what to fill in for the Payload Type?

[SimonVeldhuijzen]

I think we're still missing a policy definition for the Nuts node access token request

[edwinrozendom]

@edwindoit The specifications look good! i have 1 suggestion regarding the authorization with the use of authorization-base.

Step 2: sender sends notification:

The example is missing the authorization-base that is needed for authorization. This is an example with input[authorization-base]

{
    "resourceType": "Task",
    "basedOn": [
        {
            "identifier": {
                "system": "http://example.com/tasks",
                "value": "workflow-task-identifier-value-sending-party"
            }
        }
    ],
    "status": "requested",
    "intent": "proposal",
    "code": {
        "coding": [
            {
                "code": "pull-notification",
                "system": "http://fhir.nl/fhir/NamingSystem/TaskCode"
            }
        ]
    },
    "requester": {
        "agent": {
            "identifier": {
                "system": "urn:ietf:rfc:3986",
                "value": "software-uuid-or-oid-sending-party"
            }
        },
        "onBehalfOf": {
            "identifier": {
                "system": "http://fhir.nl/fhir/NamingSystem/ura",
                "value": "12345678"
            }
        }
    },
    "owner": {
        "identifier": {
            "system": "http://fhir.nl/fhir/NamingSystem/ura",
            "value": "87654321"
        }
    },
    "input": [
        {
            "type": {
                "coding": [
                    {
                        "system": "http://fhir.nl/fhir/NamingSystem/TaskParameter",
                        "code": "authorization-base"
                    }
                ]
            },
            "valueString": "ZGFhNDFjY2MtZGFmMi00YjZkLThiNDYtN2JlZDk1MWEyYzk2"
        }
    ]
}

[yob1997]

I've also added the authorization base to our notification task, I was running into this same problem last week.