MyHealth@Eu NCPeH API - Local Development build (v10.0.0-ci) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Dispensation Provision and Retract

This page describes the implementation options of the Dispensation Provision and Retract task.

Business View

The overall business scenarios associated to this task are described in the Business view page.

Application View

The implementation-independent sequence diagrams associated to this task are described in the Application view page.

The context: HL7 CDA to FHIR-based service migration

Based on the context described in the Prescribed item Retrieval page, the new approach could reasonably be based on MedicationDispense notification.

This proposed solution could be sufficient to notify the receiving system about the occurrence of a dispensation event, or to indicate that a dispensation has been cancelled. However, it does not provide all the details needed to fully specify the dispensation act, such as the details of the dispensed medication.

Implementation pre-requisites

The MyHealth@EU general architecture requires that no assumptions are made on the way the service is implemented at the national level.

This implies that any solution adopted for the NCPeH to NCPeH communications has to work properly independently from the fact that a HL7 FHIR server, a national dispensation repository, or any other national solution is locally adopted.

Country B's dispensation system acts as an implicit subscription provider for a MedicationDispense-based availability topic.

When a dispensed item is issued or made available, the system prepares a Bundle containing the MedicationDispense and the supporting resources needed to represent that event.

This Bundle of type collection is used to group the resources associated with the dispensed item. It is intended to realize the concept of a subscription-notification Bundle, even if it is not necessarily exchanged as part of an explicit event notification workflow.

Note: Different patterns may be used to implement the dispense notification scenario described above. One possible pattern is presented below, while alternative patterns may be listed in a later version of this page.

Implementation

The dispensation notification mechanism permits realizing the Dispensation Provision and Retract process described in the Application view.

In the following diagram the NCP of Country B sends dispensation information to the NCP of Country A. The same interaction pattern can be used to communicate that a previously sent dispensation has been cancelled or entered in error.

In summary:

• Country B performs the dispensation.
• Country B prepares a MedicationDispense resource representing the performed dispensation.
• Country B prepares the corresponding collection Bundle, including the MedicationDispense and the supporting resources needed to process the event.
• Country B sends the collection Bundle to Country A.
• Country A uses the received information to update the status of the prescription and record that the dispensation has been performed.
• If a previously communicated dispensation was entered in error, Country B sends an updated MedicationDispense with the appropriate status, for example entered-in-error.

Scenarios

Dispense Notification

Dispensation Performed

The Requestor performs the dispensation of the prescribed item.

Prepare MedicationDispense

The Requestor prepares a MedicationDispense resource representing the dispensation event.

Prepare Collection Bundle

The Requestor prepares a Bundle of type collection containing the MedicationDispense and the supporting resources needed to process the event.

eHDSI Bundle Notification Request

The Requesting NCP sends the collection Bundle to the Responding NCP using the FHIR API call:

POST $server/Bundle

The Requesting NCP can indicate whether the entire resource is returned using the HTTP return preference. It SHOULD use

Prefer: return=minimal OR Prefer: return=OperationOutcome

Request processed

Receiving the Bundle at the Bundle endpoint does not imply by default that its content will be extracted and processed. For the purpose of this transaction, it is expected that the Responding NCP processes and extracts the received resources, updating the status of the prescription and recording that the dispensation has been performed.

eHDSI Bundle Notification Response

In case of success, the Responding NCP returns a 201 Created HTTP status code, and SHALL also return a Location header which contains the new Logical Id and Version Id of the created resource version:

Location: [base]/[type]/[id]/_history/[vid]

where [id] and [vid] are the newly created id and version id of the created resource.

If Prefer: return=minimal - or not specified - then the Server SHOULD return no body. If Prefer: return=OperationOutcome the Server SHOULD return an OperationOutcome resource containing hints and warnings about the operation rather than the full resource.

Dispensation Notification HTTP Error Response Codes

Dispensation cancellation

Prepare updated MedicationDispense

The Requestor prepares an updated MedicationDispense resource with the appropriate status, for example entered-in-error.

eHDSI MedicationDispense Notification Request

This is realized as an optional Dispensation Retract step, sent instead of, or after, the initial notification.

The Requesting NCP sends the updated MedicationDispense to the Responding NCP using the FHIR API call:

PUT $server/MedicationDispense?identifier=http://your-system.org/fhir/identifier|12345

The Responding NCP uses the received information to update or correct the status of the corresponding dispensation record and, where appropriate, the related prescription status.

eHDSI MedicationDispense Notification Response

Since the request uses a conditional update (PUT with a search criteria), the outcome depends on how many resources match the search:

• If exactly one resource matches the search, the corresponding dispensation record is updated.
• If zero resources match a 404 Not Found is returned.
• If more than one resource matches, the server returns 412 Precondition Failed (ambiguous match).

Dispensation Cancellation HTTP Error Response Codes

Alternatives to be discussed

Notification (MedicationDispense and Bundle)

Country B performs the dispensation.

Country B prepares a MedicationDispense resource representing the performed dispensation.

Country B prepares the corresponding collection Bundle, including the MedicationDispense and the supporting resources needed to process the event.

Country B sends the MedicationDispense and the collection Bundle to Country A.

Country A uses the received information to update the status of the prescription and record that the dispensation has been performed.

Notification (MedicationDispense, minimal workflow control)

Country B performs the dispensation.

Country B prepares a MedicationDispense resource representing the performed dispensation.

Country B sends the MedicationDispense to Country A.

Country A uses the received information to update the status of the prescription and record that the dispensation has been performed.

Notification (MedicationDispense) and Retrieval (Bundle)

Country B performs the dispensation.

Country B prepares a MedicationDispense resource representing the performed dispensation.

Country B sends the MedicationDispense to Country A.

Country A uses the received information to update the status of the prescription and record that the dispensation has been performed.

If more details about the dispensation are needed, Country A retrieves the collection Bundle from Country B.

Options assessment

Implementation alternatives

The Dispensation Provision and Retract task is realized by sending dispensation information from the country of treatment to the country of affiliation and, when needed, sending an update that cancels or retracts a previously communicated dispensation.

For HL7 FHIR R4, dispensation events are represented by MedicationDispense resources. A collection Bundle can be used to group the MedicationDispense and the supporting resources needed to represent and process the dispensation event.

The exact national backend used to record the dispensation and update the prescription workflow remains outside the scope of this page.

Open points to be further assessed

The FHIR R5 Subscription Backport Implementation Guide does not appear to be actively maintained as a stable reference for this use case. The current published release is still from 2023, while later material appears to be available only as ballot or continuous-build content. It is therefore not yet clear how reliable it is as a reference source.

The R4 backport approach appears to require the first Bundle entry to contain parameters that simulate the role of the newer SubscriptionStatus resource. This should be assessed carefully, because SubscriptionStatus includes a mandatory reference to a Subscription resource. Such a reference may not be appropriate or necessary in an implicit subscription scenario, where no explicit FHIR Subscription resource is created or managed by Country B. Similar considerations may apply to other parameters listed in the backport specification.

The usage of a transaction Bundle should be evaluated.

To allow the wallet case, Bundle retrieval for dispensation should be enabled from Country B.

It should be evaluated whether the Bundle could include many MedicationDispense resources for multi-item prescriptions.

Notes

The term "implicit subscription" is used here as an architectural pattern, not as a formal FHIR mechanism.

The pattern is inspired by the FHIR Subscriptions framework, where a SubscriptionTopic defines the event of interest and a Subscription defines the client's request to receive notifications. In the proposed cross-border architecture, however, the receiving country does not create or manage an explicit FHIR Subscription resource. Instead, the notification-like behavior is established by predefined business rules, configuration, and architectural agreements between the participating systems.

For this reason, the prescription or collection Bundle may be inspired by the concept of a FHIR subscription-notification Bundle, but it should not be assumed to formally conform to the FHIR subscription-notification Bundle structure unless the required subscription-related metadata, including the reference to an explicit Subscription, is actually meaningful and supported.