Developer Guide MO VZVZ

Introduction

Purpose

The purpose of this document is to support the implementation of the Healthcare Application Medicatieoverdracht on the AORTA-LSP infrastructure.

Scope

This document gives a technical overview of the Healthcare Application with references to other documents with further information. It is intended as a landing page that refers to other locations with further information.

This document contains

• the system architecture to indicate how this Healthcare Application relates to other products

• information on the available APIs

• relevant policies and governance that must be adhered to to be able to use this Healthcare Application

• information regarding the configuration of the Healthcare Application, such as connection details for the test and acceptance environments

• an overview of common and known issues

• contact information

Disclaimer:

The scope of this developer guide is consistent with the information standard. However, it may differ from the scope outlined in the implementation contract between the MO program and the Information System vendor.

This documentation aims to comprehensively cover all aspects of the information standard and the Healthcare Application as supported by the AORTA-LSP.

Note: In case of discrepancies, the Nictiz scope takes precedence.

Intended audience

This document is intended for developers, product owners and architects of XIS-system development and integration.

Glossary

See Developer Guide - Glossary

Product Overview

Requirements (Programma van eisen)

The list of requirements for the healthcare application addressed in this Developer Guide can be found here:

See Programma van Eisen

Use cases (functional use cases)

The use cases were refined in cooperation with Nictiz. For the Healthcare Application.Medicatieoverdracht the following use cases are relevant and can be found on the Nictiz website or in the PSA which is developed internally.

See Medicatieprocessen

See Nictiz Functional Design

Related documents

See Documentatieoverzicht.

Business Architecture

Context

Vision

The Medication Transfer program works on good, complete electronic transfer of medication data. For an up-to-date and complete medication overview for every healthcare provider and every patient. A basic set of medication data has been agreed in the Guideline for Transfer of Medication Data in the Chain. These basic data must be available to every healthcare provider who prescribes, provides or administers. Three information standards enable the registration and exchange of this basic set. These are the information standards Medication Process, Lab values ​​for medication and CiO (Contraindications and hypersensitivities). The healthcare-wide implementation of the guideline and the associated information standards takes place within the Medication Transfer program. New agreements and procedures make network and chain care possible; the information standards included in software packages make digital data exchange possible.

Objectives

The Medication process program aims first to take away existing obstacles in the medication process, while taking into account current legislation and the possibility of obtaining tangible results in the foreseeable future.

Architecture:

The Healthcare Application Medicatieoverdracht consists of various parts:

• business layer architecture by Nictiz

  • Information standards

    • functional requirements

    • information models

• application layer architecture by VZVZ

  • application requirements

  • information models for data exchange on AORTA-LSP infrastructure

  • infrastructure integration specifications with centralized application services

This application layer architecture is related to the higher business layer architecture as formulated in Bedrijfsarchitectuur.

Terminology

AORTA 8 - Subscribe and notify

The terms; subscribe and notify need to be used instead of the legacy terms; signal, event and register.

In the AORTA v3 architecture the legacy terms are still present.

Context diagram

See Bedrijfsarchitectuur

This architecture is performed within a larger framework. See Nictiz page on Interoperabiliteit. This application mainly addresses Application and IT-infrastructure.

Business Processes

Business Processes MP9

The main business processes withn MP9 are typically triggered by patient encounters and/or receival of medication data.

The identified processes are:

• Prescribe

  • Medication verification by prescriber

• Dispense

  • Medication verification by pharmacist

• Administer

  • Administration list

  • Administration Registration

• Use

  • Medication Use Registration

At the start or during a business process relevant data may be received are retrieved.

At the middle of a business process, an external Healthprofessional may be contacted with proposals.

At the end of such a business process, data is exchanged. Data can be sent or be made available.

Relevant Business Processes per Information System category

The prescriber and the pharmacist as well as other administrators and patients (optional) all make use of an information system, respectively,

• an electronic prescribing system (‘elektronisch voorschrijfsysteem’ - EVS),

• an electronic client file (‘elektronisch cliëntendossier’ - ECD),

• a pharmacist information system (‘apothekersinformatiesysteem’ - AIS),

• a hospital pharmacist information system (‘ziekenhuisapotheekinformatiesysteem’ - ZAIS),

• an administration registration system (‘toedieningsregistratiesysteem’ - TRS),

• a thrombosis service information system (‘trombosedienstinformatiesysteem’ - TrIS)

• and a personal health environment (‘persoonlijke gezondheidsomgeving’ - PGO).

These information systems each have different system roles which enable the exchange of data between these information systems as part of the administration process. The information systems may have a function in compiling an administration list, and in the registration, the exchange and the delivering of an MTD.

Prescriber (EVS user)

Electronic prescribing system (‘elektronisch voorschrijfsysteem’ - EVS)

a thrombosis service information system (‘trombosedienstinformatiesysteem’ - TrIS)

The role of prescriber may be performed by anyone with a prescribing authorisation.

Dispenser (AIS user)

a pharmacist information system (‘apothekersinformatiesysteem’ - AIS)

a hospital pharmacist information system (‘ziekenhuisapotheekinformatiesysteem’ - ZAIS)

Administrator (eTRS user)

an administration registration system (‘toedieningsregistratiesysteem’ - TRS)

Business Process Medication data (PULL)

Context

Functioneel Ontwerp Medicatieproces 9 versie 3.0.0-rc.1 - informatiestandaarden

Trigger

• Notification of new medication data availability

• Patient encounter

Steps

• consulting information system pulls the Medication data

• LSP-AORTA

  • acts as an end-point for request from HealthProfessionals and/or Patients

  • allows for HL7v3/CDA and/or FHIR based requests

  • handles the generic query request

  • splits the generic query into specific queries towards the source information systems

  • transforms request where needed for compatibility

  • routes requests towards the relevant source information systems

• consulted information system makes medication data available

• LSP-AORTA

  • transforms response where needed for compatibility

  • aggregates responses into a single response bundle

  • responds to the consulting information system

Postcondition

• Consulted medication data and/or errors is available in the consulting information system

Business Process Medication data (PUSH)

Context

Functioneel Ontwerp Medicatieproces 9 versie 3.0.0-rc.1 - informatiestandaarden

Trigger

• New data, requests, proposals and/or replies have been created and are being made available

• MP9 Process step: ‘Send and/or make available’

Steps

• source information system sends the data, request, proposal or reply

• LSP-AORTA

  • acts as an end-point for send-request from HealthProfessionals and/or Patients

  • allows for HL7v3/CDA and/or FHIR based requests

  • handles the send request

  • transforms send request where needed for compatibility

  • routes the send request towards the relevant receiving information system

• receiving information system handles the receival with acknowledgment

• LSP-AORTA

  • transforms response where needed for compatibility

  • responds to the sending information system

Postcondition

• Send medication data and/or errors is received in the receiving information system

Business Transaction specific Dataset constraints

The dataset needs to adhere to the constraints set by the transaction

Per transaction in the data model in ART DECOR, in the Condition column, refinements are found on attributes. The implementation needs to adhere to these.
These refinements are often the same for all transactions, but sometimes they differ per transaction.
For example, when sending a prescription, there are some fields that are not needed in the prescription and therefore we do not expect them in the prescription. However, when you request and provide medication data, those fields would be included. There are small discrepancies between what is transmitted in one transaction and another.

The advice is to build the building blocks in such a way that you can hide or include attributes in that building block depending on the interaction.
This is also future-proof if you need to move to a newer version of FHIR or other transport protocols.

As implementor, the differences will become apparent, when you Compare transactions side by side.
On big difference is between prescription and medication agreement.

• The phone number is mandatory when sending a prescription, but it must not be included when making a medication agreement available (important - we also qualify on this).

• The VV relationship to MA (1-) on (0-) depends on the migration.

The information per transaction can be found in the ZorgView column under:

Business Data

See Raadpleging en Abonnement - Contexten

See Bedrijfsarchitectuur

Application Architecture

MP9v3 FO Transactions as AoF GBx-Systemrole Profiles

The Nictiz MP9v3 FO Transactions are implemented MP specific systemrole profiles on top of the AORTA-LSP AoF plaftorm.

The requirements are mentioned in the PvEs as MP systemrole profiles .

The MP systemrole profiles is formed by a composition of AoF GBX-systeemrol profiles.

Transactions

Context

Transactions as required within the context of AORTA-LSP.

Purpose

This section covers all available transactions as defined by Nictiz.

It details the mapping of those transactions to exchang format specific application layer transactions.

Those application layer transactions are exposed as AORTA-LSP using HL7v3 and/or FHIR interfaces.

This section also refines the application layer requirements by this Healthcare Application.

Scope

Which transactions should I support?

Scope of Kickstart

The scope is in accordance with the Compilation File containing functional, technical, and infrastructural documentation for Medication Process 9, intended for the Kickstart – information standards.

See Compilation File: Verzamelbestand met functionele, technische en infrastructurele documentatie Medicatieproces 9 t.b.v. Kickstart - informatiestandaarden

The functional design already includes more functionalities than are currently being implemented by the Kickstart vendors.

For example, the transaction "medication overview" does not need to be supported initially; and patients are not initially required to make Medication Use Records (MGBs) available.

Scope for Follower group

20 Mar 2025 Nictiz

The following vendors may align their implementation with that of the Kickstart vendors.
For now, the compilation file (the cross-reference tables) is leading and ensures that the same functionalities are implemented.

The following XIS vendors have contractually committed to the implementation of MP9, following the scope as defined by the Kickstart phase.
While the standard is broader—and also includes the LAB and CiO standards—these fall outside the initial scope and deadline that the vendors are currently focusing on.

End goals

However, it is important to realize that the final scope of MP9 is significantly broader.
The compilation file is therefore not a definitive representation of what ultimately needs to be implemented. Additional testing will be conducted for a number of functionalities. Moreover, the standard is still under development and subject to changes that will need to be incorporated.

Please take this into account during further implementation.

The Healthcare Application Medicatieoverdracht is very large and covers all use cases for every type of EHR system that participates. The list below indicates which use cases should be supported by each type of system. This allows vendors to drill down to only support the relevant use cases.

The roles and use-cases are summarized by Nictiz and the Program in the Compilation File.

See Compilation File.

Medicatieprocessen contains additional business analysis by VZVZ.

Transactions per system role

Legenda of details per transaction

• Indicator of scope:

  • DR - digitaal receptenverkeer

  • MO - medicatieoverdracht

  • TL - toedienlijst

  • MM - MedMij

• Indicator of actor:

  • Voorschrijver

  • Verstrekker

  • Toediener

  • PGO/Patient

• Eigen Only: Whether only own of foreign (copy) building-blocks are allowed?

• Systeemrol: Nictiz FO Systeemrol

• AoF GBx-Systeemrol: Required role to communicate via the AoF-route.

• FHIR_Systeemrol: Required role to communicate via FHIR.

• VZVZ AORTA v3 Applicatie systeemrol: required role to be implemented to communicate via HL7v3/CDA.

• VZVZ AORTA v3 Webservice: Webservice to communicatie via HL7v3/CDA.

• SOAP Message: Message to communicatie via HL7v3/CDA.

• AoF_Interactie: Message to communicatie via AoF (mainly FHIR).

• AoF_Interface: Interface to communicatie via AoF.

• AoF_Feature: Required feature capability to communicatie via AoF.

• ContextCode: Code which makes the transaction more specific for its context.

This explanation supports the implementation of the requirements for each necessary role.

Voorschrijver

Stap 3 - Voorschrijven

Stap 4- Verificatie en gebruiken

Stap 5- Verstrekken

Stap 6- Toedienen

Verstrekker

Stap 3 - Voorschrijven

Stap 4- Verificatie en gebruiken

Stap 5- Verstrekken

Stap 6- Toedienen

Toediener

Stap 3 - Voorschrijven

Stap 4- Verificatie en gebruiken

Stap 5- Verstrekken

Stap 6- Toedienen

Patient

Stap 3 - Voorschrijven

Stap 4- Verificatie en gebruiken

Stap 5- Verstrekken

Stap 6- Toedienen

Individual use cases

MP-MGR MP-MGB proxy-facade

AORTA acts as proxy-facade towards the source systems. The calls from a MP-MGR are distributed towards MP-MGB servers and the responses are aggregated as bundled response.

We use a generic query (in FHIR, in the form of a $get-aorta-data operation) for requesting systems, which is translated by AORTA into FHIR searches (excluding BSN) towards source systems.

MP-MGR MP-MGB FHIR includes

AORTA ensures that all relevant data is requested in a minimum number of requests. This avoids unnecessary round-trips, and ensures sufficient data retrieval to allow for the BTD to transform data between exchange formats.

These includes result in explicitely broadend FHIR searches with _include and _include:iterate parameters towards MP-MGB.

Patient identifier not part of argument but part of context

Patient identifier is not intended to be mentioned in the query parameters. This would impose a security risk.

For security reasons, we do not include the BSN (citizen service number) in the URL of FHIR searches. It is part of the token that is sent along (which is therefore not only an authorization tool but also a data carrier).

The patient indentifier needs to be communicated via the access-token.

This design-pattern is used for incoming as well as outgoing traffic on AORTA-LSP.

AORTA-LSP does NOT support patient identification with the use of search parameters.

As mentioned in the FHIR Implementation Guide Medication Process 9 version 3.0.0 - informatiestandaarden.

Within AORTA, each transaction is performed in the context of a specific patient, whose context might has been established using the authentication mechanisms. Patient is part of the token exchange.

The BSN of the patient in question is included in the access_token

HTTP argument patient.identifier is NOT supported like

GET [base]/MedicationRequest?
patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn%7C111222333

MP-VOS + LAB-LRS

Send a request for medication dispensing or for processing a change in a medication agreement.

VZVZ implements lab Observations as an open-world extension on top of profile mp-MedicationPrescription-Bundle.

Security

We have a security requirement, which makes it necessary to obtain an access token that is sent along to the source systems.
This does not change the FHIR search itself, but it does affect the HTTP call.

HTTP-Headers

In addition, there are several HTTP headers we use, such as:

• Content-Type (format of the FHIR content)

• AORTA-ID (for tracing/logging of interactions/chains)

• AORTA-Version (infrastructure version)

Examples include headers like request-id, initial-request-id, etc..

Provenance Resources in FHIR response bundles

Also see Bedrijfsarchitectuur for the functional description of Provenance.

During pull and push exchange, the AORTA-LSP as exchange system adds FHIR Provenance Resources into the bundles to indicate the source systems.

Logic in AORTA:

Per bundle only one specific Provenance-object is added per source systeem

Per bundle one specific Provenance-object is shared between all resources of the source

In the Provenance object each resource in the searchset bundle is referenced:

• fullUrl, if the fullUrl is a logical id (urn:uuid)

• http://resource.id , if the fullUrl contains an absolute Url

• Is the source returns a OperationOutcome, and it is not a part of the searchset, than a resource object is created with a logical id, which is referenced from the Provenance-Object

During aggregation of the sources, per source, a Provenance object is maintainted and expanded with the new target.reference(s).

After aggregation the Provenance object(en) are added to the consolidated bundle.

The Provenance objects are also included with regular FHIR search responses, not only during the get-aorta-data operation.

The same logic is being reused.

The Provenance contains the AORTA-app-id and URA to identify the source system.

Note: AORTA-LSP currently does not add user-friendly-name displaynames.

This element is NOT filled:

• Profile Element Provenance.contained.Device.deviceName of profile vzvz.fhir.nl-vzvz-core | NLVZVZDevice - SIMPLIFIER.NET

• Bundle Element /Bundle/entry/resource/Provenance/contained/Device[@id='#nl-vzvz-Device-contained']/deviceName/name as in example vzvz.fhir.aof | aorta-provenance-example-bundle - SIMPLIFIER.NET

The current focus is on reliability and efficiency over additional functionality.
The receiving party may use the Zorg-AB to obtain a user-friendly-name displayname.

Sequence diagrams

For Business Layer scenarios,
see DECOR informatie voor project: Medicatieproces (mp-).

For Application Layer scenarios,
see DECOR informatie voor project: Medicatieproces op LSP (mp-vzvz-)
”Medicatieproces op het LSP versie 1.6 en is gebaseerd op MP9 3.0.0-rc.1”

For AORTA-on-FHIR platform integrations, see https://aorta-on-fhir.scrollhelp.site/aorta-on-fhir-specificaties/latest/sequence-diagrammen .

For additional infrastructural usecases, see Uitwerking usecases VGU en abonneren en notificeren

Query Design

The query design supports the Nictiz transaction MP-MGR by means of both:

• AORTA-LSP HL7v3/CDA transaction

• AORTA-LSP AoF FHIR call

The query design supports the use of specific query filter parameters.

Within the information standaard MP9v3, specific parameters are defined for the queries.

Nictiz transaction

AORTA-LSP HL7v3/CDA transaction

Scenario

Dataset and Template

Data elements

hl7:GQZG_IN000001NL02
>hl7:ControlActProcess
>>hl7:queryByParameter
>>>hl7:parameter
>>>>hl7:value
>>>>hl7:semanticsText

AORTA-LSP AoF FHIR call

See Interfaces Resource Broker ZA-in

Call Syntax

GET [base]$get-aorta-data
?[context]
{&[destination]}
{&[effective-time]}
{&[therapy-identifier]}
{&[classifier]}
{&[instance-identifier]}

MP9v3 specific query filter parameters

Column AoF corresponds to the parameters for the AORTA-LSP AoF FHIR call.

Column HL7v3 corresponds to the parameters in the AORTA HL7v3/CDA Dataset and Template.

APIs

Supported APIs

The Medication Proces is supported by a various of API’s and Medication Information Standaards.

The AORTA-LSP platform is build using two main communication processing routes. The routes are a legacy ZIM-route and a replacing AoF-route. The replacing AoF-route is based on a more granular component infrastructure.

The AORTA-LSP contains a mix of Infrastructure-Routes with a legacy as well as a replacing AoF system composition.

The AORTA-LSP endpoints a corresponding APIs offer support for multiple exchange-formats.

The Healthcare Application Medicatieoverdracht spans a hybrid situation in which messages can be exchanged using both HL7 v3/CDA and/or HL7 FHIR exchange-formats. The AORTA-LSP infrastructure uses a Message Transformation Service (BTD=Berichten Transformatie Dienst) to transform formats and information standars.

To make this transformation possible without losing valuable information some restrictions to the FHIR implementation are required:

• ALWAYS make sure the resource instance has a valid business identifier

• do NOT use absolute FHIR references, they cannot be converted to an HL7 v3 reference

• ALWAYS add the necessary resources in a bundle, the LSP gateway cannot fetch the additional resources and incomplete bundles (i.e. with referenced resources that are not present in the bundle) can not be transformed.

API support HL7v3/CDA exchange format

See DECOR informatie voor project: Medicatieproces op LSP (mp-vzvz-)

Medicatieproces op het LSP versie 1.6 en is gebaseerd op MP9 3.0.0-rc.1

API support for FHIR R4

See FHIR Implementation Guide Medication Process 9 version 3.0.0-rc.1 - informatiestandaarden for FHIR integration.

Use of FHIR packages

Nictiz uses the FHIR Packaging mechanism. This conveniently bundles all profiles, terminology, example material and other conformance resources you need into a single archive, which can be downloaded or installed using the appropriate FHIR tooling. This version of the information standard uses the following packages:

• nictiz.fhir.nl.r4.medicationprocess9 version 2.0.0-rc.2 or compatible

• nictiz.fhir.nl.r4.nl-core version 0.11.0-beta.1 or compatible

Note: packages use Semantic Versioning. Other versions can be used at will as long as they have the same major.minor number or a minor number higher than the stated version.

Known issue:

• nl-core 0.12 generates too many unwanted warnings and error. Please use 0.11.

V3 messages and packages

Backwards compatibility for MP 6.12 transactions on AORTA 8.4

The 6.12 messages can and will be exchanged via AORTA 8.4. This no longer goes through the AORTA 6 version of the infrastructure.

The PvEs for the AORTA 6 version of the infrastructure are no longer used and have been replaced by the PvEs based on the 8.4 version of the infrastructure.

The old version of MO is also 6.x. That is why these messages are called 6.12 messages. The 6.12 messages can and will be exchanged via AORTA 8.4.

Two parallel paths

Within AORTA-LSP, there are two parallel paths for processing messages: a legacy path and a replacement path.

The legacy path is also known as the ZIM route.

The replacement path is also known as the AoF route.

With the introduction of AoF, a new architecture has started with a new replacement path that will eventually replace the legacy path.

FHIR profiles and packages

The FHIR profiles used in this Healthcare Application can be found on Simplifier.

Examples

See: FHIR profiles and packages

API specification

Future intention: OpenAPI specifications

Naming conventions

The various calls on the various API’s adhere to naming conventions by Nictiz and VZVZ.

These are the naming conventions in Dutch.

Nictiz - functional transactions

• Sturend

• Ontvangend

• Beschikbaarstellend

• Raadplegend

• Voorstel

• AntwoordVoorstel

VZVZ, AoF systemroles

• ZA Verzendend Systeem

• ZA Ontvangend Systeem

• ZA = ZorgAanbieder

VZVZ, AORTA v3

• Webservice

  • Versturen

  • Opvragen

• Transactierollen

  • xxZ - verzendendsysteem

  • xxD - ontvangendsysteem

  • Vxx - voorstel…

  • Axx - antwoord…

  • xxO - … opvragend systeem

  • xxV - …bronsysteem | …opleverend systeem

VZVZ, AoF zorgtoepassingsrollen

• SIS Search Initiërend Systeem

• SVS Search Verwerkend Systeem

• SOS Search result Ontvangend Systeem

• TIS Transaction Initiërend Systeem

• TVS Transaction Verwerkend Systeem

• CIS Create Initiërend Systeem

• CVS Create Verwerkend Systeem

• RIS Read Initiërend Systeem

• RVS Read Verwerkend Systeem

• OIS Operation Initiërend Systeem

SIS is intended for a client that can query using a specific query.
SOS is intended for a client that can query using a generic query.
SVS is intended for a server that can make query processing available for requests from AORTA-LSP.

Security

Identification and Authorization Management

See Programma van Eisen.

Encryption

See Programma van Eisen.

Authentication

See Autorisatierichtlijn Medicatieveiligheid | AORTA-LSP.

See Programma van Eisen.

See Bedrijfsarchitectuur; Actors