/
(v3) Developer Guide MO VZVZ
Document toolboxDocument toolbox

(v3) Developer Guide MO VZVZ

Owned by Tjerk Drouen
Feb 04, 2025
17 min read

Table of Contents

Changelog

Version 0.0.1

First draft

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

Intended audience

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

References

Glossary

Term (English)

(Dutch)

Definition

Term (English)

(Dutch)

Definition

Medication agreement

Medicatieafspraak

'Medicatieafspraak / Medication agreement/ is the prescriber’s proposal for medication use with which the patient agrees. An agreement to discontinue medication is also an MA.

Variable dosing regimen

Wisselend doseerschema

'Wisselend doseerschema / Variable dosing regimen' contains the dosing instruction as composed by an (external) prescriber. In the WDS the element 'instructions for use' from the MA is further specified. The WDS can be modified without changing the MA.

Dispense request

Verstrekkingsverzoek

'Verstrekkingsverzoek / Dispense request' is the request from a prescriber to a pharmacist to supply the patient with one or more medicinal products in support of the current MA(s)

Administration agreement

Toedieningsafspraak

'Toedieningsafspraak / Administration agreement' contains the instructions for medication use (or administration) from the pharmacist to the patient (or his representative or administrator), adding to the MA.

Medication dispense

Medicatieverstrekking

'Medicatieverstrekking / Medication dispense' is the provision of a supply of medicinal product to the patient or his administrator or representative.

Medication administration

Medicatietoediening

'Medicatietoediening / Medication administration' is the registration of individual administrations of the medicinal product to the patient by the person who administers them (such as a nurse or the patient himself) in relation to the agreements made.

Medication use

Medicatiegebruik

'Medicatiegebruik / Medication use' is a statement about historical, current or intended use of a medicinal product.

Proposal medication agreement

Voorstel medicatieafspraak

'Voorstel medicatieafspraak / Proposal medication agreement' is a recommendation or request from the pharmacist, prescriber or the administrator to the prescriber of the MA about the medication agreed upon. The recommendation request may include evaluating, discontinuing, starting or modifying medication.

Reply proposal medication agreement

Antwoord voorstel medicatieafspraak

'Antwoord voorstel medicatieafspraak / Reply proposal medication agreement' is a reply from the prescriber to the VMA.

Proposal dispense request

Voorstel verstrekkingsverzoek

'Voorstel verstrekkingsverzoek / Proposal dispense request' is a proposal from the pharmacist to the prescriber to approve one or more MVE(s) in support of the current MA(s). This is comparable with the current situation of submitting the authorisation form or combined prescription or submitting a repeat prescription for signing. The patient may also submit a VVV to the prescriber.

Reply proposal dispense request

Antwoord voorstel verstrekkingsverzoek

'Antwoord voorstel verstrekkingsverzoek / Reply proposal dispense request' is a reply from the prescriber to the VVV.

Clinical Information Model (CIM)

zorginformatiebouwsteen (ZIB)

See Clinical Building Block (CBB)

Clinical Building Block (CBB)

zorginformatiebouwsteen (ZIB)

Related data elements are grouped together in a Clinical Information Model (CIM)

Therapeutic and logistical building blocks

Therapeutische en logistieke bouwstenen

The model is designed in such a way that therapeutic building blocks and logistical building blocks are separated from each other.

Pharmaceutical treatment

Medicamenteuze behandeling

'Pharmaceutical treatment' is a technical concept in the information standard. Its purpose is:

  • To unambiguously identify the set of interdependent medication building blocks, and

  • To apply rules to it to unambiguously determine the present situation.

Product Overview

Requirements (Programma van eisen)

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

(v3) 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.

Related documents

This section contains a list of all the links from other sections of this document as well as links to other relevant documents.

See (v3) Documentatieoverzicht.

The overview lists:

  • Requirements

  • Functional Designs

  • Technical Designs

  • Standards and Regulations

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 (v3) Architectuur.

 

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

Zie (v3) Architectuur

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

Flow chart

Algemene workflow uitwisseling

Onderstaande stappen zullen altijd uitgevoerd worden, ongeacht de inhoudelijke berichten. Voor het overzicht wordt de algemene workflow hier beschreven en wordt bij de inhoudelijke workflows alleen de stappen en berichten genoemd die aanvullend zijn op deze algemene workflow.

Opvragen medicatiegegevens

Workflow

  • vrager stelt generieke query / $get-aorta-data

  • LSP splitst in losse bouwsteen queries

  • zo nodig transformatie

  • antwoorden zo nodig getransformeerd

  • (getransformeerde) antwoorden worden gebundeld aangeleverd aan vrager

Interacties

  • lijst met interacties die bevraagd kunnen worden/ ontvangen kunnen worden

Berichten

Sturen en afhandelen medicatievoorschrift

Workflow

  • bron stuurt voorschrift-bericht naar ontvanger

  • ontvanger stuurt ontvangstbevestiging terug

  • ontvanger stuurt afhandeling-voorschrift-bericht naar bron

  • bron stuurt ontvangstbevestiging terug

Berichten

Sturen en afhandelen medicatiegegevens

Workflow

  • bron stuurt medicatiegegevens-bericht naar ontvanger

  • ontvanger stuurt ontvangstbevestiging terug

Berichten

Use cases

This section covers all available use cases as defined by Nictiz and the changes to the specfications as required by this Healthcare Application.

Which use cases should I support

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 Verzamelbestand met functionele, technische en infrastructurele documentatie Medicatieproces 9 t.b.v. Kickstart - informatiestandaarden.

(v3) Usecases & Processen contains additional business analysis by VZVZ.

Verzamelbestand VZVZ applicatie interfaces richting AORTA

Hier volgt een uitgebreide toelichting op het Verzamelbestand informatiestandaarden.

Dit uitgebreide verzamelbestand bevat informatie over:

  • VZVZ AoF BGx-Systeemrol (platformgeneriek voor FHIR)

  • VZVZ AORTA FHIR Systeemrol (specifiek voor zorgtoepassingen binnen FHIR)

  • VZVZ AORTA v3 Applicatiesysteemrol (specifiek voor zorgtoepassingen binnen v3)

Deze uitleg biedt ondersteuning bij de implementatie van de vereisten voor elke benodigde rol.

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 hanteren een generieke query (in FHIR in de vorm van een $get-aorta-data operation) voor vragende systemen, die door AORTA wordt omgezet naar FHIR searches (minus BSN) naar bronsystemen.

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.

Om security redenen nemen wij het BSN niet op in de URL van FHIR searches. Het is onderdeel van het token dat wordt meegestuurd (dat dus niet alleen autorisatiehulpmiddel is maar ook gegevensdrager).

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 FHIR Implementation Guide Medication Process 9 version 3.0.0-beta.4 - 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.

Het BSN van de betreffende patient is opgenomen in het 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

Sturen verzoek tot medicatieverstrekking van medicatie of verwerking van wijziging in medicatieafspraak.

VZVZ implementeert lab Observations als open-world extension boven op nictiz.fhir.nl.r4.medicationprocess9 | mp MedicationPrescription Bundle - SIMPLIFIER.NET.

Security

Wij hebben een security requirement en daarom is het nodig om een access token te verkrijgen dat meegestuurd wordt naar bronsystemen. Dit verandert niets aan de FHIR-search, maar wel de HTTP call.

HTTP-Headers

Daarnaast zijn er nog een aantal HTTP-headers die we gebruiken, zoals Content-Type (formaat FHIR-content), AORTA-ID (tracing/logging van interacties/ketens) en AORTA-Version (versie infrastructuur).

Zoals request-id, initial-request-id, etc.

 

AoF FHIR Search parameter support for generic query using get-aorta-data

MP9 search parameter

Description

FHIR search parameter

Nictiz

VZVA (AoF)

MP9 search parameter

Description

FHIR search parameter

Nictiz

VZVA (AoF)

PatientIdentificationNumber

Search on patient.

patient.identifier

subject:Patient.identifier

 

NOT supported on argument line

is part of context

Identification

Search on identifier.

identifier

GET [base]/MedicationRequest?identifier=http://example.nl/fhir/NamingSystem/MedicationRequest|999922448

Supported via

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

Use Cases Resource Broker v3-in

$get-aorta-data?

&instance-identifier=<http://example.nl/fhir/NamingSystem/MedicationRequest|<id>

Identification

Search on the pharmaceutical treatment identifier.

Note: retrieval of all medication resources belonging to one pharmaceutical treatment requires to search on all medication resource types.

pharmaceutical-treatment-identifier

GET [base]/MedicationRequest?pharmaceutical-treatment-identifier=http://example.nl/fhir/NamingSystem/pharmaceuticaltreatment|1247848

Supported via

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

Use Cases Resource Broker v3-in

$get-aorta-data?

&therapy-identifier=<http://example.nl/fhir/NamingSystem/pharmaceuticaltreatment|<id>

Type

Search on type of medication building block.

category

Retrieves all MedicationRequest resources that represent the building block MedicationAgreement.

GET [base]/MedicationRequest?category=http://snomed.info/sct|33633005

Retrieves all MedicationRequest resources that represent the building block DispenseRequest.

Retrieves all MedicationRequest resources that represent the building block VariableDosingRegimen.

Supported via

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

as

&category=http://snomed.info/sct|<category>

Retrieves all MedicationDispense resources that represent the building block MedicationDispense.

Retrieves all MedicationDispense resources that represent the building block AdministrationAgreement.

Supported

Retrieves all MedicationStatement resources that represent the building block MedicationUse2.

Supported

Retrieves all MedicationAdministration resources that represent the building block MedicationAdministration2.

Supported

MedicationCode

Search on medication code.

medication.code

 

NOT SUPPORTED?

PeriodOfUse

Search on the MedicationAgreement, VariableDosingRegimen, AdministrationAgreement and MedicationUse2 building blocks that are related to medication that was used, is used or will be used during the indicated period.

Whenever a search is done on the MedicationAgreement, VariableDosingRegimen or AdministrationAgreement building blocks it is required to also include the latest stopped building blocks of that kind within each pharmaceutical treatment, even if these have a period of use outside the PeriodOfUse that is being searched on.

period-of-use

 

Supported via effective-time as GebruiksPeriode

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

Use Cases Resource Broker v3-in

DispensePeriod

Returns all medication dispenses within the specified time period.

whenhandedover

 

Supported via effective-time as VerstrekkingsPeriode

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

Use Cases Resource Broker v3-in

AdministrationPeriod

Returns all medication administrations within the specified time period.

effective-time

 

Supported via effective-time as ToedieningsPeriode

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

Use Cases Resource Broker v3-in

-

The client may request that the server returns resources related to the search results, in order to reduce the overall network delay of repeated retrievals of related resources.

Supporting the include of the Patient and Medication resources referenced by building blocks is required. Others (Organization, Location, PractitionerRole, Practitioner, RelatedPerson, Observation) are optional. However: all resources referenced per literal reference SHALL be resolvable per the Nictiz IG.

_include=[type]:patient

_include=[type]:medication

 

Not Supported via arguments!

Includes are implicit and automatically added by VZVZ based on agreements with Nictiz.

 

Provenance Resources in FHIR response bundles

Also see (v3) Architectuur 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)

  • 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:

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

See DECOR informatie voor project: Medicatieproces (mp-) for Business Layer scenarios

See DECOR informatie voor project: Medicatieproces op LSP (mp-vzvz-) Medicatieproces op het LSP versie 1.5 en is gebaseerd op MP9 3.0.0-beta.4 HTML for Application Layer scenarios

See https://aorta-on-fhir.scrollhelp.site/aorta-on-fhir-specificaties/latest/sequence-diagrammen for AORTA-on-FHIR platform integrations.

See https://vzvz.atlassian.net/wiki/spaces/ZM/pages/1285750978

Class diagrams

Zie https://vzvz.atlassian.net/wiki/spaces/ZM/pages/1285947678

Zie ook (v3) Architectuur

Available APIs

The Healthcare Application Medicatieoverdracht spans a hybrid situation in which messages can be exchanged in both HL7 v3 and HL7 FHIR. The AORTA infrastructure uses a Transformation Service to transform one type into another so systems only supporting a specific format can still exchange information.

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.

 

 

TODO onderstaande tekst moet gecontroleerd worden (klopt alles en hoe is dit uitgewerkt in de PvE’s e.d.) en zo nodig hierboven herschreven/aangevuld worden.

Omschrijving: Hoe kunnen we tussen medicatiebouwstenen refereren in FHIR in een ecosysteem waarin ook geconverteerd moet worden van en naar HL7v3?

  • In HL7v3 kunnen absolute FHIR referenties niet overgebracht worden en bestaat een referentie uit een business identifier.

  • Bij het converteren van FHIR naar HL7v3 moet de business identifier dus achterhaald kunnen worden, anders verlies je de relatie.

  • Het verliezen van de relatie is niet acceptabel in verband met de afleidingsregels.

  • Op het LSP worden géén REST-calls gedaan om (FHIR-)referenties te kunnen resolven en dus een business identifier te achterhalen bij een absolute of relatieve FHIR URL.

  • Referenties kunnen ook gaan naar een bouwsteen die ‘van’ iemand anders is (een andere zorgaanbieder).

  • Bij een LSP-query mogen andermans bouwstenen niet opgeleverd worden. Hoe kan je dan (bij het antwoord op een query) een referentie resolven die in een FHIR bouwsteen een relatieve URL heeft naar je eigen server zonder een extra REST-call te doen naar die FHIR server?

  • Is het eventueel gewenst om URL’s naar ándere FHIR servers (bij andere zorgaanbieders) in jouw FHIR-bericht op te nemen?

  • Hoe weet je of een andere zorgaanbieder een échte FHIR-server heeft waar deze URL’s resolvable zijn, of wellicht alleen een façade?

In gesprek met Lauri R en Jelmer vd M kwamen we tot de voorzichtige conclusie dat - zo lang we te maken hebben met conversies van/naar HL7v3 - referenties tussen medicatiebouwstenen ook in FHIR altijd via business identifier zouden moeten gaan. Klopt die conclusie?
src: https://nictiz.atlassian.net/browse/MP-1596

See DECOR informatie voor project: Medicatieproces op LSP (mp-vzvz-) Medicatieproces op het LSP versie 1.5 en is gebaseerd op MP9 3.0.0-beta.4 XML for HL7 v3 SOAP interactions

See FHIR Implementation Guide Medication Process 9 version 3.0.0-beta.4 - informatiestandaarden for FHIR integration.

V3 messages and packages

FHIR profiles and packages

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

Project/package

Description

Project/package

Description

Nictiz R4 MedicationProcess

The profiles and examples related to MO

AoF

link naar de scrollhelp pagina met alle AORTA-profielen

Examples

API specification

AORTA specifications: see all the links combined in the AoF Releases as ‘AoF Release’ with label “AoF.2024.1” (Functionaliteit die nodig is voor de kickstart MO).

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

These are the naming conventions in Dutch:

Security

Identification and Authorization Management

See requirements in (v3) Programma van Eisen.

Encryption

See requirements in (v3) Programma van Eisen.

Authentication

Zie Autorisatierichtlijn Medicatieveiligheid | AORTA-LSP.

See requirements in (v3) Programma van Eisen.

See (v3) Architectuur; Actors

Configuration

Common Issues/Known Issues

Contact information

Person

Role/Type of questions

Contact

Person

Role/Type of questions

Contact

Bart Molenaar

Product Manager

-

VZVZ Testteam

 

validatie@medicatieoverdracht.nl

VZVZ Architects

 

solutionarchitecten@vzvz.nl

 

 

 

 

Related content

(v2) Developer Guide MO VZVZ
(v2) Developer Guide MO VZVZ
Zorgtoepassing Medicatieoverdracht
More like this
(v1) Developer Guide MO VZVZ
(v1) Developer Guide MO VZVZ
Zorgtoepassing Medicatieoverdracht
More like this
Developer Guide MO VZVZ
Developer Guide MO VZVZ
Zorgtoepassing Medicatieoverdracht
More like this
Changelog release 1.4.1
Changelog release 1.4.1
MedMij Afsprakenstelsel 1.4.1
More like this